Log::Dispatch(3)      User Contributed Perl Documentation     Log::Dispatch(3)



NAME
       Log::Dispatch - Dispatches messages to one or more outputs

VERSION
       version 2.29

SYNOPSIS
         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 );

DESCRIPTION
       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.

CONSTRUCTOR
       The constructor ("new") takes the following parameters:

       o   outputs( [ [ class, params, ... ], [ class, params, ... ], ... ] )

           This parameter is a reference to a list of lists. Each inner list
           consists of a class name and a set of constructor params. The class
           is automatically prefixed with 'Log::Dispatch::' unless it begins
           with '+', in which case the string following '+' is taken to be a
           full classname. e.g.

               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 "add").

           See "OUTPUT CLASSES" for the parameters that can be used when
           creating an output object.

       o   callbacks( \& or [ \&, \&, ... ] )

           This parameter may be a single subroutine reference or an array
           reference of subroutine references.  These callbacks will be called
           in the order they are given and passed a hash containing the
           following keys:

            ( 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!

METHODS
   Logging
       o   log( level => $, message => $ or \& )

           Sends the message (at the appropriate level) to all the output
           objects that the dispatcher contains (by calling the "log_to"
           method repeatedly).

           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.

       o   debug (message), info (message), ...

           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");

       o   log_and_die( level => $, message => $ or \& )

           Has the same behavior as calling "log()" but calls
           "_die_with_message()" at the end.

       o   log_and_croak( level => $, message => $ or \& )

           This method adjusts the $Carp::CarpLevel scalar so that the croak
           comes from the context in which it is called.

       o   _die_with_message( message => $, carp_level => $ )

           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.

           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.

       o   log_to( name => $, level => $, message => $ )

           Sends the message only to the named object. Note: this will not
           properly handle a subroutine reference as the message.

       o   add_callback( $code )

           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.

   Log levels
       o   level_is_valid( $string )

           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.

       o   would_log( $string )

           Given a log level, returns true or false to indicate whether or not
           anything would be logged for that log level.

       o   is_$level

           There 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.

   Output objects
       o   add( Log::Dispatch::* OBJECT )

           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.

       o   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.

       o   output( $name )

           Returns the output object of the given name.  Returns undef or an
           empty list, depending on context, if the given output does not
           exist.

OUTPUT CLASSES
       An output class - e.g. Log::Dispatch::File or Log::Dispatch::Screen -
       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.

       o   name ($)

           A name for the object (not the filename!). This is useful if you
           want to refer to the object later, e.g. to log specifically to it
           or remove it.

           By default a unique name will be generated.  You should not depend
           on the form of generated names, as they may change.

       o   min_level ($)

           The minimum logging level this object will accept. Required.

       o   max_level ($)

           The maximum logging level this object will accept.  By default the
           maximum is the highest possible level (which means functionally
           that the object has no maximum).

       o   callbacks( \& or [ \&, \&, ... ] )

           This parameter may be a single subroutine reference or an array
           reference of subroutine references.  These callbacks will be called
           in the order they are given and passed a hash containing the
           following keys:

            ( 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!

       o   newline (0|1)

           If true, a callback will be added to the end of the callbacks list
           that adds a newline to the end of each message. Default is false,
           but some output classes may decide to make the default true. See
           "NEWLINES" for more details.

LOG LEVELS
       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:

       debug
       info
       notice
       warning
       error
       critical
       alert
       emergency

       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'.

SUBCLASSING
       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 Log::Dispatch::Output docs for more
       details.

       If you would like to create your own subclass for sending email then it
       is even simpler.  Simply subclass Log::Dispatch::Email and override the
       "send_email" method.  See the Log::Dispatch::Email 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").

RELATED MODULES
   Log::Dispatch::DBI
       Written by Tatsuhiko Miyagawa.  Log output to a database table.

   Log::Dispatch::FileRotate
       Written by Mark Pfeiffer.  Rotates log files periodically as part of
       its usage.

   Log::Dispatch::File::Stamped
       Written by Eric Cholet.  Stamps log files with date and time
       information.

   Log::Dispatch::Jabber
       Written by Aaron Straup Cope.  Logs messages via Jabber.

   Log::Dispatch::Tk
       Written by Dominique Dumont.  Logs messages to a Tk window.

   Log::Dispatch::Win32EventLog
       Written by Arthur Bergman.  Logs messages to the Windows event log.

   Log::Log4perl
       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.

   Log::Dispatch::Config
       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.

   Log::Agent
       A very different API for doing many of the same things that
       Log::Dispatch does.  Originally written by Raphael Manfredi.

SUPPORT
       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.

       The code repository is at http://hg.urth.org/hg/Log-Dispatch.

SEE ALSO
       Log::Dispatch::ApacheLog, Log::Dispatch::Email,
       Log::Dispatch::Email::MailSend, Log::Dispatch::Email::MailSender,
       Log::Dispatch::Email::MailSendmail, Log::Dispatch::Email::MIMELite,
       Log::Dispatch::File, Log::Dispatch::File::Locked,
       Log::Dispatch::Handle, Log::Dispatch::Output, Log::Dispatch::Screen,
       Log::Dispatch::Syslog

AUTHOR
       Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE
       This software is Copyright (c) 2011 by Dave Rolsky.

       This is free software, licensed under:

         The Artistic License 2.0 (GPL Compatible)



perl v5.16.3                      2011-03-18                  Log::Dispatch(3)
