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

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

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

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

Composite Appenders

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