NAME

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

SYNOPSIS

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

$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 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 handle or file path, default => 'STDERR')

$log->log_level();

set the thrshold for which messages will actiually be logged, only messages with a log_level set to a (nuerically) 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 ther 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");

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, <theo@taowebs.net<gt>

SEE ALSO

perl.