use Log::Report; # The following will be created for you automatically dispatcher 'PERL', 'default', accept => 'NOTICE-'; dispatcher close => 'default'; # after deamonize dispatcher 'FILE', 'log' , mode => 'DEBUG', to => '/var/log/mydir/myfile'; # Full package name is used, same as 'FILE' dispatcher Log::Report::Dispatch::File => 'stderr' , to => \*STDERR, accept => 'NOTICE-'; # Within a "try" block, there is only one dispatcher dispatcher TRY => 'try';
This base-class handles the creation of dispatchers, plus the common filtering rules.
See the DETAILS section, below.
When a dispatcher is created (via new() or Log::Report::dispatcher()), you must specify the TYPE of the dispatcher. This can either be a class name, which extends a Log::Report::Dispatcher, or a pre-defined abbreviation of a class name. Implemented are:
print()
, warn()
and die()
to ventilate
reports. This is the default dispatcher.
Log::Dispatch::*
Log::Log4perl
The modules which use Log::Report
will only specify the base of
the message string. The base dispatcher and the back-ends will extend
this message with additional information:
$!
When the message is a translatable object (Log::Report::Message, for instance created with Log::Report::__()), then the added components will get translated as well. Otherwise, all will be in English.
Exactly what will be added depends on the actual mode of the dispatcher (change it with mode(), initiate it with new(mode)).
mode mode mode mode REASON SOURCE TE! NORM -v -vv -vvv trace program ... S assert program ... SL SL info program T.. S S S notice program T.. S S S S mistake user T.. S S S SL warning program T.. SL SL SL SL error user TE. S S SL SC fault system TE! S S SL SC alert system T.! S S SC SC failure system TE! S S SC SC panic program .E. SC SC SC SC -v = verbose, -vv = debug, -vvv = trace T - usually translated E - exception ! - will include $! text B - leave block with exception D - delayed; only shown when block completes without error L - include filename and linenumber S - show/print when accepted C - stack trace (like Carp::confess())
With a filter, you can block or modify specific messages before translation. There may be a wish to change the REASON of a report or its content. It is not possible to avoid the exit which is related to the original message, because a module's flow depends on it to happen.
When there are filters defined, they will be called in order of
definition. For each of the dispatchers which are called for a
certain REASON (which accept
that REASON), it is checked whether
its name is listed for the filter (when no names where specified,
then the filter is applied to all dispatchers).
When selected, the filter's CODE reference is called with four arguments:
the dispatcher object (a Log::Report::Dispatcher), the HASH-of-OPTIONS
passed as optional first argument to Log::Report::report(), the
REASON, and the MESSAGE. Returned is the new REASON and MESSAGE.
When the returned REASON is undef
, then the message will be ignored
for that dispatcher.
Be warned about processing the MESSAGE: it is a Log::Report::Message
object which may have a prepend
string and append
string or
object. When the call to Log::Report::report() contained multiple
comma-separated components, these will already have been joined together
using concatenation (see Log::Report::Message::concat().
dispatcher filter => \&myfilter, 'syslog'; # ignore all translatable and non-translatable messages containing # the word "skip" sub myfilter($$$$) { my ($disp, $opts, $reason, $message) = @_; return () if $message->untranslated =~ m/\bskip\b/; ($reason, $message); }
dispatch filter => \&take_warns_serious; sub take_warns_serious($$$$) { my ($disp, $opts, $reason, $message) = @_; $reason eq 'MISTAKE' ? (ERROR => $message) : $reason eq 'WARNING' ? (FAULT => $message) : ($reason => $message); }