Appender(3)

📦

version 1.57 · 9 versions

1.57 · opensuse-leap 16.0 (latest)
1.54 · epel 9
1.57 · epel 10
1.57 · alpine 3.24
1.58 · arch rolling
1.57 · fedora 43
1.54 · ubuntu jammy
1.57 · fedora 44
1.57 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ Appender(3) — the manual page, but make it make sense ✨

okay so bestie, you know how Log::Log4perl needs somewhere to actually put all those log messages? yeah. that's this. it's the Log::Log4perl::Appender class and honestly it's the plug that connects your logger to the world 💅

🌸 NAME 🌸

Log::Log4perl::Appender — the log appender class, periodt.

🦋 SYNOPSIS 🦋

okay so here's the whole vibe in one go, no cap:

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

like, that's it. that's the whole thing. you make a logger, you make a layout, you make an appender, you slap the layout on the appender, you add the appender to the logger. iconic behavior honestly 🎀

💖 DESCRIPTION 💖

so basically this class is a cute little wrapper around the whole Log::Log4perl::Appender appender set. she's giving middle management but make it fashion.

and listen — it ALSO supports all those <Log::Dispatch::*> collections of appenders. like, the module hides all the Log::Dispatch idiosyncrasies from Log::Log4perl (you know, the way every dispatcher gotta have a name but there's literally no accessor to retrieve it?? messy) while still re-using the extremely useful variety of dispatchers that were already created and tested in Log::Dispatch. we love reusing code. we love not reinventing the wheel. slay ✨

🔥 FUNCTIONS 🔥

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

okay so the constructor new() takes the name of the appender class you wanna create as a string (!) argument — yes bestie, a string — 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');

now, in the case of Log::Dispatch appenders, if you don't specify a name parameter, the appender object will just create a unique one for you (format is appNNN), which you can retrieve later via the name() method:

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

other parameters are specific to whatever appender class you're using. in the case above, the filename parameter specifies the name of the Log::Log4perl::Appender::File dispatcher used. iykyk.

BUT — and this is the important part — if, for instance, you're using a Log::Dispatch::Email dispatcher to send yourself email (valid), you'll have to specify from and to email addresses. every dispatcher is different, bestie. they all have their own little quirks. please check the Log::Dispatch::* documentation for whatever appender you're using for the deets on specific requirements.

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

and when it comes to logging, the Log::Log4perl::Appender will transparently relay all messages to the Log::Dispatch::* object it carries in its womb. her womb. her little dispatcher baby. anyway 💀

💖 `$appender->layout($layout);`

the layout() method sets the log layout used by the appender to the format specified by the Log::Log4perl::Layout::* object that gets 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. go read them. they're right there. 🫶

🌈 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, bestie — they're all handled in the same way via the Log::Log4perl::Appender interface. equal opportunity appending. please check the well-written manual pages of the Log::Dispatch hierarchy on how to use each one of them. they ate, honestly. 👑

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

when calling the appender's log()-Funktion (yes, Funktion, we're being cute), Log::Log4perl will submit a list of key/value pairs. entries to the following keys are guaranteed to be present, no cap:

message — text of the rendered message. the actual content, the main character of the log line 💅
log4p_category — name of the category of the logger that triggered the event.
log4p_level — Log::Log4perl level of the event.

like, these three are always gonna show up. they're reliable. they're the ride-or-die keys. ✨

💀 Pitfalls 💀

okay so listen. Log::Dispatch::File appender truncates log files by default, and most of the time that is NOT what you want. like, not me losing all my logs because of a default setting 😭. so we've instructed Log::Log4perl to change this behavior by slipping it the mode => append parameter behind the scenes. sneaky. effective. she works hard but she works smart.

so effectively, with Log::Log4perl 0.23, a configuration like this:

    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 (preserving your precious logs, thank you very much) — while if you specifically request clobbering, like in this config here:

    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. like a clean slate. a fresh start. bye bye old logs, hope you didn't need those 🙈

so yeah — default = append (we fixed it for you), but mode = write = full clobber mode. choose wisely bestie. 💀

🧩 Appenders Expecting Message Chunks

So here's the thing, bestie — some appenders don't want a plain string, they want multiple fields as their log message. 💅

Like, if a statement like

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

makes a regular off-the-shelf Log::Log4perl::Appender::Screen appender fire, that appender is just gonna concatenate the three message chunks you handed it, in order, to make one single string. And those chunks get separated by a string defined in $Log::Log4perl::JOIN_MSG_ARRAY_CHAR (which defaults to the empty string ""), no cap.

But other appenders might interpret that message totally differently. An appender like Log::Log4perl::Appender::DBI, for example, might take those three arguments passed to the logger and drop them into three separate rows in the DB. Iconic behavior, honestly. ✨

The warp_message appender option is what you use to specify the behavior you actually want. If there's no setting for the appender property

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

defined in the Log4perl configuration file, then the appender referenced by SomeApp falls back to the standard behavior and joins all the message chunks together, separating them by $Log::Log4perl::JOIN_MSG_ARRAY_CHAR.

If, on the other hand, it's set to a false value — like this:

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

then the message chunks get passed unmodified to the appender as an array reference. 🫶 But heads up: you need to set the appender's layout to Log::Log4perl::Layout::NoopLayout, which just leaves the message chunks alone instead of formatting them or replacing conversion specifiers.

⚠️ Okay so this part matters: 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. 💀

Now it gets fancy ✨ — if an appender expects message chunks, but you wanna pre-inspect them and probably modify them before they're actually passed to the appender's log method, you can define an inspection subroutine 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 receives the list of message chunks, just like they were passed to the logger, and it's 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. Slay. 🎀

Also, the warp function can be specified by name, like this:

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

That subroutine 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. Very main character energy, honestly. 👑

🧚 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 the details, bestie. 📖

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. Chaos, but make it logging. 🌈

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 yourself. 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

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.

Okay that's the whole thing, bestie, we ate and left no crumbs 🍓✨ — this page is from perl v5.42.0, dated 2022-10-22, and it's Appender(3). Go forth and append responsibly, ily 💜🫶

📦 where this page comes from

opensuse-leap 16.0: perl-Log-Log4perl 1.57-160000.2.2 · Artistic-1.0 OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms