SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from RedHat EL 8 perl-Log-Log4perl-1.50-1.el8.noarch.rpm

Appender

Section: User Contributed Perl Documentation (3)
Updated: 2020-07-22
Index 

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::Log4perl::Appender::Screen",                   name => 'dumpy');      # Set the appender's layout  $appender->layout($layout);  $logger->add_appender($appender);
 

DESCRIPTION

This class is a wrapper around the "Log::Log4perl::Appender"appender set.

It also supports the <Log::Dispatch::*> collections of appenders. Themodule hides the idiosyncrasies of "Log::Dispatch" (e.g. everydispatcher gotta have a name, but there's no accessor to retrieve it)from "Log::Log4perl" and yet re-uses the extremely useful variety ofdispatchers already created and tested in "Log::Dispatch". 

FUNCTIONS

 

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

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

      # Define an appender  my $appender = Log::Log4perl::Appender->new(      "Log::Log4perl::Appender::File"      filename => 'out.log');

In case of "Log::Dispatch" appenders,if no "name" parameter is specified, the appender object will createa unique one (format "appNNN"), which can be retrieved later viathe "name()" method:

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

Other parameters are specific to the appender class being used.In the case above, the "filename" parameter specifies the name of the "Log::Log4perl::Appender::File" dispatcher used.

However, if, for instance, 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 usedfor 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 transparentlyrelay all messages to the "Log::Dispatch::*" object it carries in its womb. 

$appender->layout($layout);

The "layout()" method sets the log layoutused 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::FileRotate (by Mark Pfeiffer)       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. 

Parameters passed on to the appender's log() method

When calling the appender's log()-Funktion, Log::Log4perl will submit a list of key/value pairs. Entries to the following keys areguaranteed to be present:
message
Text of the rendered message
log4p_category
Name of the category of the logger that triggered the event.
log4p_level
Log::Log4perl level of the event
 

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 behavior by slipping it the "mode => append" parameter behind the scenes. So, effectivelywith "Log::Log4perl" 0.23, a configuration like

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

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

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

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

Appenders Expecting Message Chunks

Instead of simple strings, certain appenders are expecting multiple fieldsas log messages. If a statement like

    $logger->debug($ip, $user, "signed in");

causes an off-the-shelf "Log::Log4perl::Appender::Screen" appender to fire, the appender will just concatenate the three message chunks passed to itin order to form a single string.The chunks will be separated by a string defined in $Log::Log4perl::JOIN_MSG_ARRAY_CHAR (defaults to the empty string"").

However, different appenders might choose to interpret the message above differently: Anappender like "Log::Log4perl::Appender::DBI" might take thethree arguments passed to the logger and put them in three separaterows into the DB.

The "warp_message" appender option is used to specify the desired behavior.If no setting for the appender property

    # *** Not defined ***    # log4perl.appender.SomeApp.warp_message

is defined in the Log4perl configuration file, theappender referenced by "SomeApp" will fall back to the standard behaviorand join all message chunks together, separating them by$Log::Log4perl::JOIN_MSG_ARRAY_CHAR.

If, on the other hand, it is set to a false value, like in

    log4perl.appender.SomeApp.layout=NoopLayout    log4perl.appender.SomeApp.warp_message = 0

then the message chunks are passed unmodified to the appender as anarray reference. Please note that you need to set the appender'slayout to "Log::Log4perl::Layout::NoopLayout" which just leaves the messages chunks alone instead of formatting them or replacingconversion specifiers.

Please note that the standard appenders in the Log::Dispatch hierarchywill choke on a bunch of messages passed to them as an array reference. You can't use "warp_message = 0" (or the function name syntaxdefined below) on them.Only special appenders like Log::Log4perl::Appender::DBI can deal withthis.

If (and now we're getting fancy)an appender expects message chunks, but we would like to pre-inspect and probably modify them before they're actually passed to the appender's "log"method, an inspection subroutine can be defined with theappender's "warp_message" property:

    log4perl.appender.SomeApp.layout=NoopLayout    log4perl.appender.SomeApp.warp_message = sub { \                                           $#_ = 2 if @_ > 3; \                                           return @_; }

The inspection subroutine defined by the "warp_message" property will receive the list of message chunks, like they werepassed to the logger and is expected to return a corrected list.The example above simply limits the argument list to a maximum ofthree by cutting off excess elements and returning the shortened list.

Also, the warp function can be specified by name like in

    log4perl.appender.SomeApp.layout=NoopLayout    log4perl.appender.SomeApp.warp_message = main::filter_my_message

In this example,"filter_my_message" is a function in the "main" package, defined like this:

    my $COUNTER = 0;    sub filter_my_message {        my @chunks = @_;        unshift @chunks, ++$COUNTER;        return @chunks;    }

The subroutine above will add an ever increasing counteras an additional first field to every message passed to the "SomeApp" appender --- but not toany other appender in the system. 

Composite Appenders

Composite appenders relay their messages to sub-appenders after providingsome filtering or synchronizing functionality on incoming messages. Examples are Log::Log4perl::Appender::Synchronized,Log::Log4perl::Appender::Limit, andLog::Log4perl::Appender::Buffer. Check their manual pages for details.

Composite appender objects are regular Log::Log4perl::Appender objects, but they have the composite flag set:

    $app->composite(1);

and they define a post_init() method, which sets the appender it relaysits messages to:

    ###########################################    sub post_init {    ############################################        my($self) = @_;            if(! exists $self->{appender}) {            die "No appender defined for " . __PACKAGE__;        }            my $appenders = Log::Log4perl->appenders();        my $appender = Log::Log4perl->appenders()->{$self->{appender}};            if(! defined $appender) {            die "Appender $self->{appender} not defined (yet) when " .                __PACKAGE__ . " needed it";        }            $self->{app} = $appender;    }

The reason for this post-processing step is that the relay appendermight not be defined yet when the composite appender gets defined.This can happen if Log4perl is initialized with a configuration file(which is the most common way to initialize Log4perl), becauseappenders spring into existence in unpredictable order.

For example, if you define a Synchronized appender like

    log4perl.appender.Syncer            = Log::Log4perl::Appender::Synchronized    log4perl.appender.Syncer.appender   = Logfile

then Log4perl will set the appender's "appender" attribute to thename of the appender to finally relay messages to. After theLog4perl configuration file has been processed, Log4perl will remember to call the composite appender's post_init() method, which will grabthe relay appender instance referred to by the name (Logfile) and set it in its "app" attribute. This is exactly what thecode snippet above does.

But if you initialize Log4perl by its API, you need to remember toperform these steps. Here's the lineup:

    use Log::Log4perl qw(get_logger :levels);        my $fileApp = Log::Log4perl::Appender->new(                'Log::Log4perl::Appender::File',                name     => 'MyFileApp',                filename => 'mylog',                mode     => 'append',                );    $fileApp->layout(                Log::Log4perl::Layout::PatternLayout::Multiline->new(                        '%d{yyyy-MM-dd HH:mm:ss} %p [%c] #%P> %m%n')                );      # Make the appender known to the system (without assigning it to      # any logger    Log::Log4perl->add_appender( $fileApp );        my $syncApp = Log::Log4perl::Appender->new(                'Log::Log4perl::Appender::Synchronized',                name       => 'MySyncApp',                appender   => 'MyFileApp',                key        => 'nem',                );    $syncApp->post_init();    $syncApp->composite(1);      # The Synchronized appender is now ready, assign it to a logger      # and start logging.    get_logger("")->add_appender($syncApp);    get_logger("")->level($DEBUG);    get_logger("wonk")->debug("waah!");

The composite appender's log() function will typically cache incoming messages until a certain trigger condition is met and then forward a bulkof messages to the relay appender.

Caching messages is surprisingly tricky, because you want them to looklike they came from the code location they were originally issued fromand not from the location that triggers the flush. Luckily, Log4perloffers a cache mechanism for messages, all you need to do is call thebase class' log() function with an additional reference to a scalar,and then save its content to your composite appender's message bufferafterwards:

    ###########################################    sub log {    ###########################################        my($self, %params) = @_;        # ... some logic to decide whether to cache or flush            # Adjust the caller stack        local $Log::Log4perl::caller_depth =              $Log::Log4perl::caller_depth + 2;            # We need to cache.            # Ask the appender to save a cached message in $cache        $self->{relay_app}->SUPER::log(\%params,                             $params{log4p_category},                             $params{log4p_level}, \my $cache);            # Save it in the appender's message buffer        push @{ $self->{buffer} }, $cache;    }

Note that before calling the log() method of the relay appender's base class(and thus introducing two additional levels on the call stack), we need toadjust the call stack to allow Log4perl to render cspecs like the %M or %Lcorrectly. The cache will then contain a correctly rendered message, accordingto the layout of the target appender.

Later, when the time comes to flush the cached messages, a call to the relayappender's base class' log_cached() method with the cached message as an argument will forward the correctly rendered message:

    ###########################################    sub log {    ###########################################        my($self, %params) = @_;        # ... some logic to decide whether to cache or flush            # Flush pending messages if we have any        for my $cache (@{$self->{buffer}}) {            $self->{relay_app}->SUPER::log_cached($cache);        }    }
 

SEE ALSO

Log::Dispatch 

LICENSE

Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess <cpanAATTgoess.org>.

This library is free software; you can redistribute it and/or modifyit under the same terms as Perl itself. 

AUTHOR

Please contribute patches to the project on Github:

    http://github.com/mschilli/log4perl

Send bug reports or requests for enhancements to the authors via our

MAILING LIST (questions, bug reports, suggestions/patches): log4perl-develAATTlists.sourceforge.net

Authors (please contact them via the list above, not directly):Mike Schilli <m@perlmeister.com>,Kevin Goess <cpanAATTgoess.org>

Contributors (in alphabetical order):Ateeq Altaf, Cory Bennett, Jens Berthold, Jeremy Bopp, HuttonDavidson, Chris R. Donnelly, Matisse Enzer, Hugh Esco, AnthonyFoiani, James FitzGibbon, Carl Franks, Dennis Gregorovic, AndyGrundman, Paul Harrington, Alexander Hartmaier David Hull, Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter, Brett Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope, Lars Thegler, David Viner, Mac Yang.


 

Index

NAME
SYNOPSIS
DESCRIPTION
FUNCTIONS
Log::Log4perl::Appender->new($dispatcher_class_name, ...);
$appender->layout($layout);
Supported Appenders
Parameters passed on to the appender's log() method
Pitfalls
Appenders Expecting Message Chunks
Composite Appenders
SEE ALSO
LICENSE
AUTHOR

This document was created byman2html,using the manual pages.