NAME

Log::Log4perl::Appender - Log appender class

SYNOPSIS

  use Log::Log4perl;

      # Define a logger
  my $logger = Log::Log4perl->get_logger("abc.def.ghi");

      # Define a layout
  my $layout = Log::Log4perl::Layout::PatternLayout->new(
                   "%d (%F:%L)> %m");

      # Define an appender
  my $appender = Log::Log4perl::Appender->new(
                   "Log::Dispatch::Screen",
                   name => 'dumpy');

      # Set the appender's layout
  $appender->layout($layout);
  $logger->add_appender($appender);

DESCRIPTION

This class is a wrapper around the Log::Dispatch::* collection of dispatchers, so they can be used by Log::Log4perl. The module hides the idiosyncrasies of Log::Dispatch (e.g. every dispatcher gotta have a name, but there's no accessor to retrieve it) from Log::Log4perl and yet re-uses the extremely useful variety of dispatchers already created and tested in Log::Dispatch.

FUNCTIONS

Log::Dispatch::Appender->new($dispatcher_class_name, ...);

The constructor new() takes the name of the Log::Dispatcher class to be created as a string (!) argument, optionally followed by a number of Log::Dispatcher::Whatever-specific parameters, for example:

      # Define an appender
  my $appender = Log::Log4perl::Appender->new("Log::Dispatch::File"
                                              name => 'dumpy',
                                              file => 'out.log');

If no name parameter is specified, the appender object will create a unique one (format appNNN), which can be retrieved later via the name() method:

  print "The appender's name is ", $appender->name(), "\n";

Other parameters are specific to the Log::Dispatch module being used. In the case above, the file parameter specifies the name of the Log::Dispatch::File dispatcher used.

However, if you're using a Log::Dispatch::Email dispatcher to send you email, you'll have to specify from and to email addresses. Every dispatcher is different. Please check the Log::Dispatch::* documentation for the appender used for details on specific requirements.

The new() method will just pass these parameters on to a newly created Log::Dispatch::* object of the specified type.

When it comes to logging, the Log::Log4perl::Appender will transparently relay all messages to the Log::Dispatch::* object it carries in its womb.

$appender->layout($layout);

The layout() method sets the log layout used by the appender to the format specified by the Log::Log4perl::Layout::* object which is passed to it as a reference. Currently there's two layouts available:

    Log::Log4perl::Layout::SimpleLayout
    Log::Log4perl::Layout::PatternLayout

Please check the Log::Log4perl::Layout::SimpleLayout and Log::Log4perl::Layout::PatternLayout manual pages for details.

Supported Appenders

Here's the list of appender modules currently available via Log::Dispatch, if not noted otherwise, written by Dave Rolsky:

       Log::Dispatch::ApacheLog
       Log::Dispatch::DBI (by Tatsuhiko Miyagawa)
       Log::Dispatch::Email,
       Log::Dispatch::Email::MailSend,
       Log::Dispatch::Email::MailSendmail,
       Log::Dispatch::Email::MIMELite
       Log::Dispatch::File
       Log::Dispatch::Handle
       Log::Dispatch::Screen
       Log::Dispatch::Syslog
       Log::Dispatch::Tk (by Dominique Dumont)

Log4perl doesn't care which ones you use, they're all handled in the same way via the Log::Log4perl::Appender interface. Please check the well-written manual pages of the Log::Dispatch hierarchy on how to use each one of them.

Pitfalls

Since the Log::Dispatch::File appender truncates log files by default, and most of the time this is not what you want, we've instructed Log::Log4perl to change this behaviour by slipping it the mode => append parameter behind the scenes. So, effectively with Log::Log4perl 0.23, a configuration like

    log4j.category = INFO, FileAppndr
    log4j.appender.FileAppndr          = Log::Dispatch::File
    log4j.appender.FileAppndr.filename = test.log
    log4j.appender.FileAppndr.layout   = Log::Log4perl::Layout::SimpleLayout

will always append to an existing logfile test.log while if you specifically request clobbering like in

    log4j.category = INFO, FileAppndr
    log4j.appender.FileAppndr          = Log::Dispatch::File
    log4j.appender.FileAppndr.filename = test.log
    log4j.appender.FileAppndr.mode     = write
    log4j.appender.FileAppndr.layout   = Log::Log4perl::Layout::SimpleLayout

it will overwrite an existing log file test.log and start from scratch.

SEE ALSO

Log::Dispatch

AUTHOR

Mike Schilli, <log4perl@perlmeister.com>

cpanm Log::Log4perl

perl -MCPAN -e shell
install Log::Log4perl