NAME

Easy::Log - Easy to use, feature rich general purpose logging utility

SYNOPSIS

  use Easy::Log;
  $log = new Easy::Log;

$log->write([{ OPTIONS }], <LOG_LEVEL>, @message );

This is the main function for this package. If the first argument is a hash reference, it is taken as options to the logger for this log call ONLY, and may contain values for ANY of the options that the logger knows how to use. The first argument after the optional OPTIONS hash MUST BE the log level for this log. If it ends up being something that is not a log_level, then a default log_level is assigned to the write call. If the $log->write($log_level, @message) is equal to or greater than the $log->log_level() [or the $OPTIONS->{log_level}] then it will be output, otherwise it will not.

$log->clone( [$data] );

make a duplicate of the supplied $data or this log object if no data is supplied. Uses data dumper to duplicate original, therefore CODE references are not necessarily handled, although the contents of $log->prefix() will be assigned to the new (cloned) object from the original. returns the cloned object

OPTIONS

$log->n();

set the message terminator for this log object, each log message output will be terminated with the contents of this setting (default "\n")

$log->log();

set/return the log object to use for actual write operation, this occurrs AFTER the decision as to whether or not this log message will be processed. This allows one to set the log object to another logging module (such as running under apache)

$log->log_file();

set the output file for messages processed through this log object ( can be a file path ( TBD -- or a file handle -- TBD -- a subroutine which returns a filehandle of filename -- TBD ), the default is 'STDOUT'. In the case of a file path, you may specify a write mode in the normal fashion: '>' to overwrite, '>>' to append ( eg $log->log_file( ">>$filename" ) or $log->write({log_file => ">$filename"}, $log_level, ...) If you specify '>' then the target file will be clobbered on the first $log->write() call when the target file is specified and a write file handle will be opened for the remainder of the life of the process. In subsequent calls, even if a '>' is specified, the file will not be re-clobbered, unless the filehandle has been explicitly closed since the last $log->write() call.

$log->log_level();

set the threshold for which messages will actiually be logged, only messages with a log_level set to a (numerically) higher value will be output (default => WARN)

$log->dump_refs();

set the behavior when references are encountered in the message list contents (default => 1) if true, use data dumper to dump out the references

$log->handle_fatals();

if true, log module will terminate program execution on any log calls marked as FATAL or CRIT (CRIT for now [maybe add EMERG], default => 1)

$log->exclusive();

if true, and set to a colon delimited set of log_level indicators, this log object will only output its message if the current log call is for a level listed in exclusive (default => undef)

$log->stack_trace();

if true (and this log message is of sufficient log_level to be output), issue a pretty little stack trace for the log call

$log->email(); #NOT YET IMPLEMENTED

for a log level of MESSAGE, send the log message to the email address listed here, if not set, and a MESSAGE log comes in, then send the email to the owner of the process

$log->prefix();

set the prefix that each log message will have, may be either a string, or a CODE ref

DESCRIPTION

  This logging facility has many features developers may find handy.

FILTERING

One of the coolest things is FILTERING (see log_level_filtered). Using filtering we can greatly decrease the performance penalty of copious log entries (each requireing >1 subroutine call) by filtering out log messages at compile time. Here is the general idea:

 # FILTERED
 $log->write($dll, "Nifty stuff");

 # NOT-FILTERED, but will issue a warning if $ENV{WARN_FILTER} is true.
 # because it looks kind of like a log_level indicator that sould be filtered ($dll)
 $log->write(dll, "Nifty stuff");

 # NOT-FILTERED, functionally equivalent to previous example
 $log->write(DEBUG, "Nifty stuff");

PACKAGE SPECIFIC LOGGING

Need docs here -

set environment variable to a `#' separated list of regular expressions to match the names of packages where log messages should or should not be logged

eg LOG_PACKAGES='!.*Foo.*#.*Bar.*' -- this would explicitly exclude log messages from any package matching Foo and would include log messages from packages matching Bar (this particular setting would effectively allow messages ONLY from packages matching Bar, because of an implicit deny for anything NOT matching Bar -- precedence is ALLOW -> DENY such that you can DENY broadly and ALLOW more specifically within a previously denied set)

TBD -- Allow the setting of log levels on a per package basis eg '.*Foo.*=(DEBUG|INFO)'

LOG_EXCLUSIVE

Need docs here - Log only message whose log level matches the exclusive setting TBD -- Allow the setting of packages on a per log levels basis eg '(DEBUG|INFO)=.*Foo.*' similar to the proposed situation for LOG_PACKAGES

EXPORT

None by default.

log

exports a log object into your namespace. This is most likely an application global log object meaning that if you wan't specific logging behavior in any given package, you'll probably want to intanntiate a new log object

log_level

exports several constants into your namespace: DEFAULT MESSAGE LOUD CLEAN EMERG ALERT CRIT FATAL ERROR WARN NOTICE INFO DEBUG TRACE SPEW

log_level_filtered

these are scalar variable ($) aliases for the constants mentioned in log_level, the convention is that each alias begins with the same letter as the real log_level, followed by 2 `l's (eg ERROR => $ell, DEBUG => $dll, etc)

These log_level specifiers, when used with the leading dollar sign MAY BE FILTERED OUT depending upon the settings for $ENV{LOG_FILTER}

log_level_not_filtered

in name, these are identical to the log_level_filtered variables, but they are implemented as constants (no leading $) and they ARE NOT SUBJECT TO FILTERING AS IS THE CASE FOR log_level_filtered

HISTORY

0.01 Basic package w/ full functionality, but no docs yet

0.01.1 Basic package w/ full functionality, but no docs yet, used make dist to create pause upload

0.01.2 Added some documentation

TODO

0.01

DOCUMENTATION DOCUMENTATION DOCUMENTATION DOCUMENTATION DOCUMENTATION !!!!!

0.02

change the codes which represent the log_levels such that $xll style log calls can have slightly different behavior in terms of being programmer-debug calls, which will probably want to have detailed prefix informtaion, while non-programmer-debug calls may want different prefix info ($dll vs DEBUG)

AUTHOR

Theo Lengyel, <dirt@cpan.org<gt>

SEE ALSO

perl.