NAME

Log::Simplest - Simple log module. Writes log messages to file and/or STDERR.

You should use this module when you want to have very simple programming interface to log your messages. If you want some flexibility of message format and log file names, you should use some of others Log::* modules available at CPAN.

This module gives the least flexibility among existing Log modules. However it requires the least programmer's effort to write log messages to file.

USAGE

 use Log::Simplest;
 &Log("Informative log message");
 &Fatal("I am dying...");

Log files opened and closed by module initialization/end routines and does not require programmer's attention. When your main script contains only "use Log::Simplest" directive and does not have any calls to Log() and Fatal() functions, Log::Simplest will:

    * open log file;
    * write start time and date of the script;
    * write end time and date of the script;
    * close log file.

1)

Log::Simplest creates log file during module initialization (i.e. load of the module). On file opening module writes time and date of main script start time.

Log::Simplest uses environment variable ${LOG_DIR} for log file location. Log file is created in directory defined by ${LOG_DIR}, if it is defined, or in "tmp" if environment variable is not defined or empty.

2)

Log file name format is fixed and consists of:

    * name of main script (without extension .pl); 
    * time and date when script started;
    * PID of main script;
    * extension .log. 

3)

Log message format is fixed too. Each row contains log message passed to one of the functions &Log() or &Fatal() with pre-pended time-stamp.

4)

Log file is closed automatically when module unloads with message containing time-stamp when script ended.

DEPENDENCIES

This module requires these other modules and libraries:

     FileHandle
     POSIX

EXPORTED FUNCTIONS

See below for description and/or usage.

&Log()

&Fatal()

&NOFILE &NOSTDERR

OK to export variables:

$Log_file

Log file handler

$StartTime

Time-stamp of script start (same as used in the file name of Log file).

FUNCTIONS =head3 &Log ("log message")

Prints message with time stamp to log file.

If variable $logToSTDERR is not 0 than, message is also printed to STDERR (this is default).

&Fatal ("error message");

Same as &Log(), dies with an error after printing log message. Internally calls &Log().

NOFILE, NOSTDERR

Can be passed as additional parameters to &Log(). Do not print log to the corresponding media even if log level is high enough

STOP_LOG_STDERR START_LOG_STDERR

Disable/enable logging to STDERR. Both functions change value of $logToSTDERR variable. At the module initialization it is set to 1, i.e. enable printing log messages to STDERR.

Please note that, very first message about start of main script will always print to STDERR because it happens before you can call any of these two functions.

EXAMPLES

LOG MESSAGES EXAMPLE

 #!/usr/bin/perl
 use Log::Simplest;
 Log("This is normal log message");
 Fatal("After printing this I will die");

Running this script should produce output similar to:

 09/03/18 13:34:26:  *** example *** starting *** 
 09/03/18 13:34:26: Log file: /tmp/example.090318:13:34:26.9941.log
 09/03/18 13:34:26: This is normal log message
 09/03/18 13:34:26: FATAL ERROR: After printing this I will die
 FATAL : After printing this I will die at Log/Simplest.pm line 157.
 09/03/18 13:34:26:  ***  Closing file /tmp/example.090318:13:34:26.9941.log *** 
 09/03/18 13:34:26:  *** example *** Completed *** 

SIMPLEST EXAMPLE

 #!/usr/bin/perl
 use Log::Simplest;
 exit;

 This script will produce following output both on STDERR and into a file:

 $ ./simplest.pl 
 09/03/20 13:34:24:  *** simplest *** starting *** 
 09/03/20 13:34:24: Log file: /tmp/simplest.090320:13:34:24.25745.log
 09/03/20 13:34:24:  ***  Closing file /tmp/simplest.090320:13:34:24.25745.log *** 
 09/03/20 13:34:24:  *** simplest *** Completed *** 
 $

AUTHOR

Dmytro Kovalov, dmytro.kovalov@gmail.com

HISTORY

First public release: March, 2009

Although I have been using this module for quite a while in my scripts, I have never though about publishing it in theу wild. Finally I have decided to write little bit longer POD description and put it on CPAN.

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Dmytro Koval'ov

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.9 or, at your option, any later version of Perl 5 you may have available.

# LocalWords: dk qw PID pre FileHandle POSIX strftime NOFILE NOSTDERR MyName # LocalWords: StartTime logToSTDERR localtime basename ENV eq LogFileName msg # LocalWords: sprintf printf

cpanm Log::Simplest

perl -MCPAN -e shell
install Log::Simplest