.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Appender 3"
.TH Appender 3 "2015-09-15" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Log::Log4perl::Appender \- Log appender class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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 => \*(Aqdumpy\*(Aq);
\&
\&      # Set the appender\*(Aqs layout
\&  $appender\->layout($layout);
\&  $logger\->add_appender($appender);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class is a wrapper around the \f(CW\*(C`Log::Log4perl::Appender\*(C'\fR
appender set.
.PP
It also supports the <Log::Dispatch::*> collections of appenders. The
module hides the idiosyncrasies of \f(CW\*(C`Log::Dispatch\*(C'\fR (e.g. every
dispatcher gotta have a name, but there's no accessor to retrieve it)
from \f(CW\*(C`Log::Log4perl\*(C'\fR and yet re-uses the extremely useful variety of
dispatchers already created and tested in \f(CW\*(C`Log::Dispatch\*(C'\fR.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "Log::Log4perl::Appender\->new($dispatcher_class_name, ...);"
.IX Subsection "Log::Log4perl::Appender->new($dispatcher_class_name, ...);"
The constructor \f(CW\*(C`new()\*(C'\fR takes the name of the appender
class to be created as a \fIstring\fR (!) argument, optionally followed by 
a number of appender-specific parameters,
for example:
.PP
.Vb 4
\&      # Define an appender
\&  my $appender = Log::Log4perl::Appender\->new(
\&      "Log::Log4perl::Appender::File"
\&      filename => \*(Aqout.log\*(Aq);
.Ve
.PP
In case of \f(CW\*(C`Log::Dispatch\*(C'\fR appenders,
if no \f(CW\*(C`name\*(C'\fR parameter is specified, the appender object will create
a unique one (format \f(CW\*(C`appNNN\*(C'\fR), which can be retrieved later via
the \f(CW\*(C`name()\*(C'\fR method:
.PP
.Vb 1
\&  print "The appender\*(Aqs name is ", $appender\->name(), "\en";
.Ve
.PP
Other parameters are specific to the appender class being used.
In the case above, the \f(CW\*(C`filename\*(C'\fR parameter specifies the name of 
the \f(CW\*(C`Log::Log4perl::Appender::File\*(C'\fR dispatcher used.
.PP
However, if, for instance, 
you're using a \f(CW\*(C`Log::Dispatch::Email\*(C'\fR dispatcher to send you 
email, you'll have to specify \f(CW\*(C`from\*(C'\fR and \f(CW\*(C`to\*(C'\fR email addresses.
Every dispatcher is different.
Please check the \f(CW\*(C`Log::Dispatch::*\*(C'\fR documentation for the appender used
for details on specific requirements.
.PP
The \f(CW\*(C`new()\*(C'\fR method will just pass these parameters on to a newly created
\&\f(CW\*(C`Log::Dispatch::*\*(C'\fR object of the specified type.
.PP
When it comes to logging, the \f(CW\*(C`Log::Log4perl::Appender\*(C'\fR will transparently
relay all messages to the \f(CW\*(C`Log::Dispatch::*\*(C'\fR object it carries 
in its womb.
.ie n .SS "$appender\->layout($layout);"
.el .SS "\f(CW$appender\fP\->layout($layout);"
.IX Subsection "$appender->layout($layout);"
The \f(CW\*(C`layout()\*(C'\fR method sets the log layout
used by the appender to the format specified by the 
\&\f(CW\*(C`Log::Log4perl::Layout::*\*(C'\fR object which is passed to it as a reference.
Currently there's two layouts available:
.PP
.Vb 2
\&    Log::Log4perl::Layout::SimpleLayout
\&    Log::Log4perl::Layout::PatternLayout
.Ve
.PP
Please check the Log::Log4perl::Layout::SimpleLayout and 
Log::Log4perl::Layout::PatternLayout manual pages for details.
.SH "Supported Appenders"
.IX Header "Supported Appenders"
Here's the list of appender modules currently available via \f(CW\*(C`Log::Dispatch\*(C'\fR,
if not noted otherwise, written by Dave Rolsky:
.PP
.Vb 12
\&       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)
.Ve
.PP
\&\f(CW\*(C`Log4perl\*(C'\fR doesn't care which ones you use, they're all handled in 
the same way via the \f(CW\*(C`Log::Log4perl::Appender\*(C'\fR interface.
Please check the well-written manual pages of the 
\&\f(CW\*(C`Log::Dispatch\*(C'\fR hierarchy on how to use each one of them.
.SH "Parameters passed on to the appender's \fIlog()\fP method"
.IX Header "Parameters passed on to the appender's log() method"
When calling the appender's \fIlog()\fR\-Funktion, Log::Log4perl will 
submit a list of key/value pairs. Entries to the following keys are
guaranteed to be present:
.IP "message" 4
.IX Item "message"
Text of the rendered message
.IP "log4p_category" 4
.IX Item "log4p_category"
Name of the category of the logger that triggered the event.
.IP "log4p_level" 4
.IX Item "log4p_level"
Log::Log4perl level of the event
.SH "Pitfalls"
.IX Header "Pitfalls"
Since the \f(CW\*(C`Log::Dispatch::File\*(C'\fR appender truncates log files by default,
and most of the time this is \fInot\fR what you want, we've instructed 
\&\f(CW\*(C`Log::Log4perl\*(C'\fR to change this behavior by slipping it the 
\&\f(CW\*(C`mode => append\*(C'\fR parameter behind the scenes. So, effectively
with \f(CW\*(C`Log::Log4perl\*(C'\fR 0.23, a configuration like
.PP
.Vb 4
\&    log4perl.category = INFO, FileAppndr
\&    log4perl.appender.FileAppndr          = Log::Dispatch::File
\&    log4perl.appender.FileAppndr.filename = test.log
\&    log4perl.appender.FileAppndr.layout   = Log::Log4perl::Layout::SimpleLayout
.Ve
.PP
will always \fIappend\fR to an existing logfile \f(CW\*(C`test.log\*(C'\fR while if you 
specifically request clobbering like in
.PP
.Vb 5
\&    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
.Ve
.PP
it will overwrite an existing log file \f(CW\*(C`test.log\*(C'\fR and start from scratch.
.SH "Appenders Expecting Message Chunks"
.IX Header "Appenders Expecting Message Chunks"
Instead of simple strings, certain appenders are expecting multiple fields
as log messages. If a statement like
.PP
.Vb 1
\&    $logger\->debug($ip, $user, "signed in");
.Ve
.PP
causes an off-the-shelf \f(CW\*(C`Log::Log4perl::Appender::Screen\*(C'\fR 
appender to fire, the appender will 
just concatenate the three message chunks passed to it
in order to form a single string.
The chunks will be separated by a string defined in 
\&\f(CW$Log::Log4perl::JOIN_MSG_ARRAY_CHAR\fR (defaults to the empty string
"").
.PP
However, different appenders might choose to 
interpret the message above differently: An
appender like \f(CW\*(C`Log::Log4perl::Appender::DBI\*(C'\fR might take the
three arguments passed to the logger and put them in three separate
rows into the \s-1DB.\s0
.PP
The  \f(CW\*(C`warp_message\*(C'\fR appender option is used to specify the desired 
behavior.
If no setting for the appender property
.PP
.Vb 2
\&    # *** Not defined ***
\&    # log4perl.appender.SomeApp.warp_message
.Ve
.PP
is defined in the Log4perl configuration file, the
appender referenced by \f(CW\*(C`SomeApp\*(C'\fR will fall back to the standard behavior
and join all message chunks together, separating them by
\&\f(CW$Log::Log4perl::JOIN_MSG_ARRAY_CHAR\fR.
.PP
If, on the other hand, it is set to a false value, like in
.PP
.Vb 2
\&    log4perl.appender.SomeApp.layout=NoopLayout
\&    log4perl.appender.SomeApp.warp_message = 0
.Ve
.PP
then the message chunks are passed unmodified to the appender as an
array reference. Please note that you need to set the appender's
layout to \f(CW\*(C`Log::Log4perl::Layout::NoopLayout\*(C'\fR which just leaves 
the messages chunks alone instead of formatting them or replacing
conversion specifiers.
.PP
\&\fBPlease note that the standard appenders in the Log::Dispatch hierarchy
will choke on a bunch of messages passed to them as an array reference. 
You can't use \f(CB\*(C`warp_message = 0\*(C'\fB (or the function name syntax
defined below) on them.
Only special appenders like Log::Log4perl::Appender::DBI can deal with
this.\fR
.PP
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 \f(CW\*(C`log\*(C'\fR
method, an inspection subroutine can be defined with the
appender's \f(CW\*(C`warp_message\*(C'\fR property:
.PP
.Vb 4
\&    log4perl.appender.SomeApp.layout=NoopLayout
\&    log4perl.appender.SomeApp.warp_message = sub { \e
\&                                           $#_ = 2 if @_ > 3; \e
\&                                           return @_; }
.Ve
.PP
The inspection subroutine defined by the \f(CW\*(C`warp_message\*(C'\fR 
property will receive the list of message chunks, like they were
passed to the logger and is expected to return a corrected list.
The example above simply limits the argument list to a maximum of
three by cutting off excess elements and returning the shortened list.
.PP
Also, the warp function can be specified by name like in
.PP
.Vb 2
\&    log4perl.appender.SomeApp.layout=NoopLayout
\&    log4perl.appender.SomeApp.warp_message = main::filter_my_message
.Ve
.PP
In this example,
\&\f(CW\*(C`filter_my_message\*(C'\fR is a function in the \f(CW\*(C`main\*(C'\fR package, 
defined like this:
.PP
.Vb 1
\&    my $COUNTER = 0;
\&
\&    sub filter_my_message {
\&        my @chunks = @_;
\&        unshift @chunks, ++$COUNTER;
\&        return @chunks;
\&    }
.Ve
.PP
The subroutine above will add an ever increasing counter
as an additional first field to 
every message passed to the \f(CW\*(C`SomeApp\*(C'\fR appender \*(-- but not to
any other appender in the system.
.SS "Composite Appenders"
.IX Subsection "Composite Appenders"
Composite appenders relay their messages to sub-appenders after providing
some filtering or synchronizing functionality on incoming messages. 
Examples are 
Log::Log4perl::Appender::Synchronized,
Log::Log4perl::Appender::Limit, and
Log::Log4perl::Appender::Buffer. Check their manual pages for details.
.PP
Composite appender objects are regular Log::Log4perl::Appender objects, 
but they have the composite flag set:
.PP
.Vb 1
\&    $app\->composite(1);
.Ve
.PP
and they define a \fIpost_init()\fR method, which sets the appender it relays
its messages to:
.PP
.Vb 4
\&    ###########################################
\&    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;
\&    }
.Ve
.PP
The reason for this post-processing step is that the relay appender
might 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), because
appenders spring into existence in unpredictable order.
.PP
For example, if you define a Synchronized appender like
.PP
.Vb 2
\&    log4perl.appender.Syncer            = Log::Log4perl::Appender::Synchronized
\&    log4perl.appender.Syncer.appender   = Logfile
.Ve
.PP
then Log4perl will set the appender's \f(CW\*(C`appender\*(C'\fR attribute to the
\&\fIname\fR of the appender to finally relay messages to. After the
Log4perl configuration file has been processed, Log4perl will remember to 
call the composite appender's \fIpost_init()\fR method, which will grab
the relay appender instance referred to by the name (Logfile) 
and set it in its \f(CW\*(C`app\*(C'\fR attribute. This is exactly what the
code snippet above does.
.PP
But if you initialize Log4perl by its \s-1API,\s0 you need to remember to
perform these steps. Here's the lineup:
.PP
.Vb 1
\&    use Log::Log4perl qw(get_logger :levels);
\&    
\&    my $fileApp = Log::Log4perl::Appender\->new(
\&                \*(AqLog::Log4perl::Appender::File\*(Aq,
\&                name     => \*(AqMyFileApp\*(Aq,
\&                filename => \*(Aqmylog\*(Aq,
\&                mode     => \*(Aqappend\*(Aq,
\&                );
\&    $fileApp\->layout(
\&                Log::Log4perl::Layout::PatternLayout::Multiline\->new(
\&                        \*(Aq%d{yyyy\-MM\-dd HH:mm:ss} %p [%c] #%P> %m%n\*(Aq)
\&                );
\&      # Make the appender known to the system (without assigning it to
\&      # any logger
\&    Log::Log4perl\->add_appender( $fileApp );
\&    
\&    my $syncApp = Log::Log4perl::Appender\->new(
\&                \*(AqLog::Log4perl::Appender::Synchronized\*(Aq,
\&                name       => \*(AqMySyncApp\*(Aq,
\&                appender   => \*(AqMyFileApp\*(Aq,
\&                key        => \*(Aqnem\*(Aq,
\&                );
\&    $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!");
.Ve
.PP
The composite appender's \fIlog()\fR function will typically cache incoming 
messages until a certain trigger condition is met and then forward a bulk
of messages to the relay appender.
.PP
Caching messages is surprisingly tricky, because you want them to look
like they came from the code location they were originally issued from
and not from the location that triggers the flush. Luckily, Log4perl
offers a cache mechanism for messages, all you need to do is call the
base class' \fIlog()\fR function with an additional reference to a scalar,
and then save its content to your composite appender's message buffer
afterwards:
.PP
.Vb 4
\&    ###########################################
\&    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(\e%params,
\&                             $params{log4p_category},
\&                             $params{log4p_level}, \emy $cache);
\&
\&            # Save it in the appender\*(Aqs message buffer
\&        push @{ $self\->{buffer} }, $cache;
\&    }
.Ve
.PP
Note that before calling the \fIlog()\fR method of the relay appender's base class
(and thus introducing two additional levels on the call stack), we need to
adjust the call stack to allow Log4perl to render cspecs like the \f(CW%M\fR or \f(CW%L\fR
correctly.  The cache will then contain a correctly rendered message, according
to the layout of the target appender.
.PP
Later, when the time comes to flush the cached messages, a call to the relay
appender's base class' \fIlog_cached()\fR method with the cached message as 
an argument will forward the correctly rendered message:
.PP
.Vb 4
\&    ###########################################
\&    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);
\&        }
\&    }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Log::Dispatch
.SH "LICENSE"
.IX Header "LICENSE"
Copyright 2002\-2013 by Mike Schilli <m@perlmeister.com> 
and Kevin Goess <cpan@goess.org>.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Please contribute patches to the project on Github:
.PP
.Vb 1
\&    http://github.com/mschilli/log4perl
.Ve
.PP
Send bug reports or requests for enhancements to the authors via our
.PP
\&\s-1MAILING LIST \s0(questions, bug reports, suggestions/patches): 
log4perl\-devel@lists.sourceforge.net
.PP
Authors (please contact them via the list above, not directly):
Mike Schilli <m@perlmeister.com>,
Kevin Goess <cpan@goess.org>
.PP
Contributors (in alphabetical order):
Ateeq Altaf, Cory Bennett, Jens Berthold, Jeremy Bopp, Hutton
Davidson, Chris R. Donnelly, Matisse Enzer, Hugh Esco, Anthony
Foiani, James FitzGibbon, Carl Franks, Dennis Gregorovic, Andy
Grundman, 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.