| Log::Dispatch - Dispatches messages to one or more outputs |
new(...)clone()callbacks()$levelremove($)outputs()
Log::Dispatch - Dispatches messages to one or more outputs
version 2.54
use Log::Dispatch;
# Simple API
#
my $log = Log::Dispatch->new(
outputs => [
[ 'File', min_level => 'debug', filename => 'logfile' ],
[ 'Screen', min_level => 'warning' ],
],
);
$log->info('Blah, blah');
# More verbose API
#
my $log = Log::Dispatch->new();
$log->add(
Log::Dispatch::File->new(
name => 'file1',
min_level => 'debug',
filename => 'logfile'
)
);
$log->add(
Log::Dispatch::Screen->new(
name => 'screen',
min_level => 'warning',
)
);
$log->log( level => 'info', message => 'Blah, blah' );
my $sub = sub { my %p = @_; return reverse $p{message}; };
my $reversing_dispatcher = Log::Dispatch->new( callbacks => $sub );
This module manages a set of Log::Dispatch::* output objects that can be logged to via a unified interface.
The idea is that you create a Log::Dispatch object and then add various
logging objects to it (such as a file logger or screen logger). Then you
call the log method of the dispatch object, which passes the message to
each of the objects, which in turn decide whether or not to accept the
message and what to do with it.
This makes it possible to call single method and send a message to a log file, via email, to the screen, and anywhere else, all with very little code needed on your part, once the dispatching object has been created.
This class provides the following methods:
new(...)This method takes the following parameters:
outputs => [ [ 'File', min_level => 'debug', filename => 'logfile' ],
[ '+My::Dispatch', min_level => 'info' ] ]
For each inner list, a new output object is created and added to the
dispatcher (via the add() method).
See OUTPUT CLASSES for the parameters that can be used when creating an output object.
( message => $log_message, level => $log_level )
In addition, any key/value pairs passed to a logging method will be passed onto your callback.
The callbacks are expected to modify the message and then return a
single scalar containing that modified message. These callbacks will
be called when either the log or log_to methods are called and
will only be applied to a given message once. If they do not return
the message then you will get no output. Make sure to return the
message!
clone()This returns a shallow clone of the original object. The underlying output objects and callbacks are shared between the two objects. However any changes made to the outputs or callbacks that the object contains are not shared.
Sends the message (at the appropriate level) to all the output objects that
the dispatcher contains (by calling the log_to method repeatedly).
The level can be specified by name or by an integer from 0 (debug) to 7 (critical).
This method also accepts a subroutine reference as the message argument. This reference will be called only if there is an output that will accept a message of the specified level.
You may call any valid log level (including valid abbreviations) as a method
with a single argument that is the message to be logged. This is converted
into a call to the log method with the appropriate level.
For example:
$log->alert('Strange data in incoming request');
translates to:
$log->log( level => 'alert', message => 'Strange data in incoming request' );
If you pass an array to these methods, it will be stringified as is:
my @array = ('Something', 'bad', 'is', 'here');
$log->alert(@array);
# is equivalent to
$log->alert("@array");
You can also pass a subroutine reference, just like passing one to the
log() method.
Has the same behavior as calling log() but calls
_die_with_message() at the end.
This method adjusts the $Carp::CarpLevel scalar so that the croak
comes from the context in which it is called.
You can throw exception objects by subclassing this method.
If the carp_level parameter is present its value will be added to
the current value of $Carp::CarpLevel.
Sends the message only to the named object. Note: this will not properly handle a subroutine reference as the message.
Adds a callback (like those given during construction). It is added to the end of the list of callbacks. Note that this can also be called on individual output objects.
callbacks()Returns a list of the callbacks in a given output.
Returns true or false to indicate whether or not the given string is a valid log level. Can be called as either a class or object method.
Given a log level, returns true or false to indicate whether or not anything would be logged for that log level.
$levelThere are methods for every log level: is_debug(), is_warning(), etc.
This returns true if the logger will log a message at the given level.
Adds a new output object to the dispatcher. If an object
of the same name already exists, then that object is replaced, with
a warning if $^W is true.
remove($)Removes the object that matches the name given to the remove method. The return value is the object being removed or undef if no object matched this.
outputs()Returns a list of output objects.
Returns the output object of the given name. Returns undef or an empty list, depending on context, if the given output does not exist.
This method is used by log_and_die and will either die() or croak()
depending on the value of message: if it's a reference or it ends
with a new line then a plain die will be used, otherwise it will
croak.
An output class - e.g. the Log::Dispatch::File manpage or the Log::Dispatch::Screen manpage - implements a particular way of dispatching logs. Many output classes come with this distribution, and others are available separately on CPAN.
The following common parameters can be used when creating an output class. All are optional. Most output classes will have additional parameters beyond these, see their documentation for details.
By default a unique name will be generated. You should not depend on the form of generated names, as they may change.
( message => $log_message, level => $log_level )
The callbacks are expected to modify the message and then return a
single scalar containing that modified message. These callbacks will
be called when either the log or log_to methods are called and
will only be applied to a given message once. If they do not return
the message then you will get no output. Make sure to return the
message!
The log levels that Log::Dispatch uses are taken directly from the syslog man pages (except that I expanded them to full words). Valid levels are:
Alternately, the numbers 0 through 7 may be used (debug is 0 and emergency is 7). The syslog standard of 'err', 'crit', and 'emerg' is also acceptable. We also allow 'warn' as a synonym for 'warning'.
This module was designed to be easy to subclass. If you want to handle
messaging in a way not implemented in this package, you should be able to add
this with minimal effort. It is generally as simple as subclassing
Log::Dispatch::Output and overriding the new and log_message
methods. See the the Log::Dispatch::Output manpage docs for more details.
If you would like to create your own subclass for sending email then
it is even simpler. Simply subclass the Log::Dispatch::Email manpage and
override the send_email method. See the the Log::Dispatch::Email manpage
docs for more details.
The logging levels that Log::Dispatch uses are borrowed from the standard UNIX syslog levels, except that where syslog uses partial words (``err'') Log::Dispatch also allows the use of the full word as well (``error'').
Written by Tatsuhiko Miyagawa. Log output to a database table.
Written by Mark Pfeiffer. Rotates log files periodically as part of its usage.
Written by Eric Cholet. Stamps log files with date and time information.
Written by Aaron Straup Cope. Logs messages via Jabber.
Written by Dominique Dumont. Logs messages to a Tk window.
Written by Arthur Bergman. Logs messages to the Windows event log.
An implementation of Java's log4j API in Perl. Log messages can be limited by fine-grained controls, and if they end up being logged, both native Log4perl and Log::Dispatch appenders can be used to perform the actual logging job. Created by Mike Schilli and Kevin Goess.
Written by Tatsuhiko Miyagawa. Allows configuration of logging via a text file similar (or so I'm told) to how it is done with log4j. Simpler than Log::Log4perl.
A very different API for doing many of the same things that Log::Dispatch does. Originally written by Raphael Manfredi.
Please submit bugs and patches to the CPAN RT system at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Log%3A%3ADispatch or via email at bug-log-dispatch@rt.cpan.org.
Support questions can be sent to me at my email address, shown below.
If you'd like to thank me for the work I've done on this module, please consider making a ``donation'' to me via PayPal. I spend a lot of free time creating free software, and would appreciate any support you'd care to offer.
Please note that I am not suggesting that you must do this in order for me to continue working on this particular software. I will continue to do so, inasmuch as I have in the past, for as long as it interests me.
Similarly, a donation made in this way will probably not make me work on this software much more, unless I get so many donations that I can consider working on free software full time, which seems unlikely at best.
To donate, log into PayPal and send money to autarch@urth.org or use the button on this page: http://www.urth.org/~autarch/fs-donation.html
the Log::Dispatch::ApacheLog manpage, the Log::Dispatch::Email manpage, the Log::Dispatch::Email::MailSend manpage, the Log::Dispatch::Email::MailSender manpage, the Log::Dispatch::Email::MailSendmail manpage, the Log::Dispatch::Email::MIMELite manpage, the Log::Dispatch::File manpage, the Log::Dispatch::File::Locked manpage, the Log::Dispatch::Handle manpage, the Log::Dispatch::Output manpage, the Log::Dispatch::Screen manpage, the Log::Dispatch::Syslog manpage
Dave Rolsky <autarch@urth.org>
This software is Copyright (c) 2016 by Dave Rolsky.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
| Log::Dispatch - Dispatches messages to one or more outputs |