NAME
Log::ProgramInfo - log global info from a perl programs.
VERSION
Version 0.1.13
SYNOPSIS
use Log::ProgramInfo qw(
[ -logname LOGNAME ]
[ -logdir LOGDIR ]
[ -logext LOGEXT ]
[ -logdate none|date|time|datetime ]
[ -stdout ]
[ -suppress ]
[ -log $log4perl_log ]
);
# main program does lots of stuff...
exit 0;
After the program has run, this module will automatically
log information about this run into a log file and/or to a
log object. It will list such things as:
- program
- name
- version
- command line arguments
- version of perl
- modules loaded
- source code location
- Version
- run time
If a -log parameter is provided, it should be a log object that provides
an info method (i.e. a Log4Perl object is likely). The info will be sent
sent to this log in addition to writing it to a log file. This logging
is not affected by the -suppress attribute - use that if you don't want a
file log written too.
Warning, the log parser will have to be modified if you need to parse this
info out of a log4perl log - there is extra text in the lines (and any
other logging from the program) which will need to be pruned.
The log is appended to the file whose name is determined by:
LOGDIR/LOGDATE-LOGNAME.LOGEXT
where
LOGDIR defaults to . (the current directory when the program terminates)
LOGDATE defaults to the date that the program was started
LOGNAME defaults to the basename of the program
LOGEXT defaults to ".programinfo"
The -ARG specifiers in the "import" list can be used to over-ride these defaults. Specifying:
-logname LOGNAME will use LOGNAME instead of the program name
-logdir LOGDIR will use LOGDIR instead of the current directory
- if it is a relative path, it will be based on the
current directory at termination of execution
-logext EXT will add .EXT to the log filename
-logext .EXT will add .EXT to the log filename
-logext "" will add no extension to the log filename
-logdate STRING
will specify the LOGDATE portion of the filename. The STRING can be:
none LOGNAME (and no dash)
date YYYYMMDD-LOGNAME (this is the default)
time HHMMSS-LOGNAME
datetime YYYYMMDDHHMMSS-LOGNAME
-stdout will cause the log to be sent to stdout instead of a file
-suppress will suppress logging (unless environment variable
LOGPROGRAMINFO_SUPPRESS is explcitly set to 0 or null)
Normally, neither -suppress nor -stdout will be set in the
use statement, and the environment variables can then be
used to disable the logging completely or to send it to
stdout instead of to the selected file.
For some programs, however, it may be desired to not normally
provide any logging. Specifying -suppress will accomplish
this. In such a case, setting the environment variable
LOGPROGRAMINFO_SUPPRESS=0 will over-ride that choice, causing
the log to be written (as specified by the other options
and environment variables).
Environment variables can over-ride these parameters:
LOGPROGRAMINFO_SUPPRESS=x boolean suppresses all logging if true
LOGPROGRAMINFO_STDOUT=x boolean sets -stdout
LOGPROGRAMINFO_DIR=DIR string sets the target directory name
LOGPROGRAMINFO_NAME=NAME string sets the target filename LOGNAME
LOGPROGRAMINFO_EXT=EXT string sets the target extension
LOGPROGRAMINFO_DATE=DATE string sets the target filename LOGDATE selector
(there is no environment variable for setting the log attribute, that
can only be done within the program)
Adding extra loggable information:
If you want to add your own classes of loggable info, there are a
few restrictions.
You define a logging extension routine using:
Log::ProgramInfo::add_extra_logger( \&my_logger );
Your logger routine should be defined as:
sub my_logger {
my $write_entry = shift;
$write_entry->( $key1, $value );
$write_entry->( $key1, $key2, $value );
}
The $write_entry function passed to my_logger must be called with
2 or 3 arguments. The leading arguments are major (and minor if
desired) keys, the final one is the value for the key(s).
Try to keep the first key to 7 characters, and the second to 8 to
keep the log readable by humans. (It will be parseable even if you
use longer keys.)
Help improve the world! If you are writing additional classes of
info loggers, please consider whether they are truly unique to your
own environment. If there is a chance that they would be useful to
other environments, please be encouraged to send your logger to be
included into Log::ProgramInfo as either a standard default logger
or as an available optional logger.
Parsing the log file:
The log file is designed to be easily parsed.
A log always starts with a line beginning with 8 hash marks in column
one (########) plus some identifying info.
The value lines are of the form:
key : value
key1 : key2 : value
The first key is extended to at least 7 characters with blanks, the
second key (if any) is extended to at least 8 characters. There is
always a separator of (space(colon)(space) between a key and the
following field. (A key can be provided with leading spaces for making
the log more readable by humans - the readlog function in the test suite
will remove such spaces.)
Two subroutines are available to do this parsing for you:
my $firstonly = 0;
@logs = readlog( $filepath [, $acceptsub] [, $firstonly] );
@logs = parselog( $filehandle [, $acceptsub] [, $firstonly] );
$logs = readlog( $filepath [, $acceptsub ], 1 );
$logs = parselog( $filehandle [, $acceptsub ] ,1 );
The first parameter to each is either a string pathname (for readlog)
or an already opened readable file handle (for parselog).
If a subroutine reference arg $acceptsub is provided, each log that is
read will be passed to that sub reference. If the acceptsub returns
true the log is retained, otherwise it is discarded. If a trailing
(non-sub-ref) value is provided, it selects whether only the first
(acceptable) log found will be returned as a single hash reference, or
whether all of the (accepted) logs in the file will be returned as a
list of hash references.`
The hash reference for each accepted log contains the key/value (or
key1 => { key2/value pairs }) from that log.
Whenever a key (or key1/key2 pair) is seen multiple times, the value
is an array ref instead of a scalar. This only happens with the
MODULE pairs (MODULE/NAME, MODULE/LOC, MODULE/VERSION), and the INC
key. (User-provided keys are not currently permitted to use the same
key set multiple times.)