| |
man : Log::Log4perl::Appender(3p)
Appender(3p) User Contributed Perl Documentation Appender(3p)
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"
perl v5.12.2 2009-05-02 1
Appender(3p) User Contributed Perl Documentation Appender(3p)
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
perl v5.12.2 2009-05-02 2
Appender(3p) User Contributed Perl Documentation Appender(3p)
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 behaviour 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
behaviour. If no setting for the appender property
# *** Not defined ***
# log4perl.appender.SomeApp.warp_message
is defined in the Log4perl configuration file, the appender referenced
perl v5.12.2 2009-05-02 3
Appender(3p) User Contributed Perl Documentation Appender(3p)
by "SomeApp" will fall back to the standard behaviour 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
perl v5.12.2 2009-05-02 4
Appender(3p) User Contributed Perl Documentation Appender(3p)
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 existance 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
perl v5.12.2 2009-05-02 5
Appender(3p) User Contributed Perl Documentation Appender(3p)
"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!");
SEE ALSO
Log::Dispatch
AUTHOR
Mike Schilli, <log4perlATperlmeister.com>
perl v5.12.2 2009-05-02 6
|
