# Log::Log4perl::Appender - phpMan

## 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. 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::Log4perl::Appender]->new($dispatcher_class_name, ...);
    The constructor "new()" takes the name of the appender class 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 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 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 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::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 are guaranteed 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, effectively with
    "[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
    fields as 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 it in 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: An appender like "[Log::Log4perl::Appender::DBI]" might take
    the three arguments passed to the logger and put them in three separate
    rows 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, the appender referenced
    by "SomeApp" will fall back to the standard behavior and 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 an
    array reference. Please note that you need to set the appender's layout
    to "[Log::Log4perl::Layout::NoopLayout]" which just leaves the messages
    chunks alone instead of formatting them or replacing conversion
    specifiers.

    Please 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 "warp_message = 0" (or the function name syntax defined
    below) on them. Only special appenders like [Log::Log4perl::Appender::DBI]
    can deal with this.

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

    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 counter as an
    additional first field to every message passed to the "SomeApp" appender
    -- but not to any other appender in the system.

  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.

    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 relays
    its 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 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.

    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 the *name*
    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 post_init() method, which will grab the relay
    appender instance referred to by the name (Logfile) and set it in its
    "app" attribute. This is exactly what the code snippet above does.

    But if you initialize Log4perl by its API, you need to remember to
    perform 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
    bulk of messages to the relay appender.

    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' log() function with an additional reference to a scalar, and
    then save its content to your composite appender's message buffer
    afterwards:

        ###########################################
        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 to adjust the call stack to allow Log4perl to render cspecs like
    the %M or %L correctly. The cache will then contain a correctly rendered
    message, according to the layout of the target appender.

    Later, when the time comes to flush the cached messages, a call to the
    relay appender'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
    <<cpan@goess.org>>.

    This library is free software; you can redistribute it and/or modify it
    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-devel@lists.sourceforge.net>

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

    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.