1Appender(3) User Contributed Perl Documentation Appender(3)
2
6 Log::Log4perl::Appender - Log appender class
7
9 use Log::Log4perl;
10 # Define a logger
12 my $logger = Log::Log4perl->get_logger("abc.def.ghi");
13 # Define a layout
15 my $layout = Log::Log4perl::Layout::PatternLayout->new(
16 "%d (%F:%L)> %m");
17 # Define an appender
19 my $appender = Log::Log4perl::Appender->new(
20 "Log::Log4perl::Appender::Screen",
21 name => 'dumpy');
22 # Set the appender's layout
24 $appender->layout($layout);
25 $logger->add_appender($appender);
26
28 This class is a wrapper around the "Log::Log4perl::Appender" appender
29 set.
30 It also supports the <Log::Dispatch::*> collections of appenders. The
32 module hides the idiosyncrasies of "Log::Dispatch" (e.g. every
33 dispatcher gotta have a name, but there's no accessor to retrieve it)
34 from "Log::Log4perl" and yet re-uses the extremely useful variety of
35 dispatchers already created and tested in "Log::Dispatch".
36
38 Log::Log4perl::Appender->new($dispatcher_class_name, ...);
39 The constructor "new()" takes the name of the appender class to be
40 created as a string (!) argument, optionally followed by a number of
41 appender-specific parameters, for example:
42 # Define an appender
44 my $appender = Log::Log4perl::Appender->new(
45 "Log::Log4perl::Appender::File"
46 filename => 'out.log');
47 In case of "Log::Dispatch" appenders, if no "name" parameter is
49 specified, the appender object will create a unique one (format
50 "appNNN"), which can be retrieved later via the "name()" method:
51 print "The appender's name is ", $appender->name(), "\n";
53 Other parameters are specific to the appender class being used. In the
55 case above, the "filename" parameter specifies the name of the
56 "Log::Log4perl::Appender::File" dispatcher used.
57 However, if, for instance, you're using a "Log::Dispatch::Email"
59 dispatcher to send you email, you'll have to specify "from" and "to"
60 email addresses. Every dispatcher is different. Please check the
61 "Log::Dispatch::*" documentation for the appender used for details on
62 specific requirements.
63 The "new()" method will just pass these parameters on to a newly
65 created "Log::Dispatch::*" object of the specified type.
66 When it comes to logging, the "Log::Log4perl::Appender" will
68 transparently relay all messages to the "Log::Dispatch::*" object it
69 carries in its womb.
70 $appender->layout($layout);
72 The "layout()" method sets the log layout used by the appender to the
73 format specified by the "Log::Log4perl::Layout::*" object which is
74 passed to it as a reference. Currently there's two layouts available:
75 Log::Log4perl::Layout::SimpleLayout
77 Log::Log4perl::Layout::PatternLayout
78 Please check the Log::Log4perl::Layout::SimpleLayout and
80 Log::Log4perl::Layout::PatternLayout manual pages for details.
81
83 Here's the list of appender modules currently available via
84 "Log::Dispatch", if not noted otherwise, written by Dave Rolsky:
85 Log::Dispatch::ApacheLog
87 Log::Dispatch::DBI (by Tatsuhiko Miyagawa)
88 Log::Dispatch::Email,
89 Log::Dispatch::Email::MailSend,
90 Log::Dispatch::Email::MailSendmail,
91 Log::Dispatch::Email::MIMELite
92 Log::Dispatch::File
93 Log::Dispatch::FileRotate (by Mark Pfeiffer)
94 Log::Dispatch::Handle
95 Log::Dispatch::Screen
96 Log::Dispatch::Syslog
97 Log::Dispatch::Tk (by Dominique Dumont)
98 "Log4perl" doesn't care which ones you use, they're all handled in the
100 same way via the "Log::Log4perl::Appender" interface. Please check the
101 well-written manual pages of the "Log::Dispatch" hierarchy on how to
102 use each one of them.
103
105 When calling the appender's log()-Funktion, Log::Log4perl will submit a
106 list of key/value pairs. Entries to the following keys are guaranteed
107 to be present:
108 message
110 Text of the rendered message
111 log4p_category
113 Name of the category of the logger that triggered the event.
114 log4p_level
116 Log::Log4perl level of the event
117
119 Since the "Log::Dispatch::File" appender truncates log files by
120 default, and most of the time this is not what you want, we've
121 instructed "Log::Log4perl" to change this behavior by slipping it the
122 "mode => append" parameter behind the scenes. So, effectively with
123 "Log::Log4perl" 0.23, a configuration like
124 log4perl.category = INFO, FileAppndr
126 log4perl.appender.FileAppndr = Log::Dispatch::File
127 log4perl.appender.FileAppndr.filename = test.log
128 log4perl.appender.FileAppndr.layout = Log::Log4perl::Layout::SimpleLayout
129 will always append to an existing logfile "test.log" while if you
131 specifically request clobbering like in
132 log4perl.category = INFO, FileAppndr
134 log4perl.appender.FileAppndr = Log::Dispatch::File
135 log4perl.appender.FileAppndr.filename = test.log
136 log4perl.appender.FileAppndr.mode = write
137 log4perl.appender.FileAppndr.layout = Log::Log4perl::Layout::SimpleLayout
138 it will overwrite an existing log file "test.log" and start from
140 scratch.
141
143 Instead of simple strings, certain appenders are expecting multiple
144 fields as log messages. If a statement like
145 $logger->debug($ip, $user, "signed in");
147 causes an off-the-shelf "Log::Log4perl::Appender::Screen" appender to
149 fire, the appender will just concatenate the three message chunks
150 passed to it in order to form a single string. The chunks will be
151 separated by a string defined in $Log::Log4perl::JOIN_MSG_ARRAY_CHAR
152 (defaults to the empty string "").
153 However, different appenders might choose to interpret the message
155 above differently: An appender like "Log::Log4perl::Appender::DBI"
156 might take the three arguments passed to the logger and put them in
157 three separate rows into the DB.
158 The "warp_message" appender option is used to specify the desired
160 behavior. If no setting for the appender property
161 # *** Not defined ***
163 # log4perl.appender.SomeApp.warp_message
164 is defined in the Log4perl configuration file, the appender referenced
166 by "SomeApp" will fall back to the standard behavior and join all
167 message chunks together, separating them by
168 $Log::Log4perl::JOIN_MSG_ARRAY_CHAR.
169 If, on the other hand, it is set to a false value, like in
171 log4perl.appender.SomeApp.layout=NoopLayout
173 log4perl.appender.SomeApp.warp_message = 0
174 then the message chunks are passed unmodified to the appender as an
176 array reference. Please note that you need to set the appender's layout
177 to "Log::Log4perl::Layout::NoopLayout" which just leaves the messages
178 chunks alone instead of formatting them or replacing conversion
179 specifiers.
180 Please note that the standard appenders in the Log::Dispatch hierarchy
182 will choke on a bunch of messages passed to them as an array reference.
183 You can't use "warp_message = 0" (or the function name syntax defined
184 below) on them. Only special appenders like
185 Log::Log4perl::Appender::DBI can deal with this.
186 If (and now we're getting fancy) an appender expects message chunks,
188 but we would like to pre-inspect and probably modify them before
189 they're actually passed to the appender's "log" method, an inspection
190 subroutine can be defined with the appender's "warp_message" property:
191 log4perl.appender.SomeApp.layout=NoopLayout
193 log4perl.appender.SomeApp.warp_message = sub { \
194 $#_ = 2 if @_ > 3; \
195 return @_; }
196 The inspection subroutine defined by the "warp_message" property will
198 receive the list of message chunks, like they were passed to the logger
199 and is expected to return a corrected list. The example above simply
200 limits the argument list to a maximum of three by cutting off excess
201 elements and returning the shortened list.
202 Also, the warp function can be specified by name like in
204 log4perl.appender.SomeApp.layout=NoopLayout
206 log4perl.appender.SomeApp.warp_message = main::filter_my_message
207 In this example, "filter_my_message" is a function in the "main"
209 package, defined like this:
210 my $COUNTER = 0;
212 sub filter_my_message {
214 my @chunks = @_;
215 unshift @chunks, ++$COUNTER;
216 return @chunks;
217 }
218 The subroutine above will add an ever increasing counter as an
220 additional first field to every message passed to the "SomeApp"
221 appender -- but not to any other appender in the system.
222 Composite Appenders
224 Composite appenders relay their messages to sub-appenders after
225 providing some filtering or synchronizing functionality on incoming
226 messages. Examples are Log::Log4perl::Appender::Synchronized,
227 Log::Log4perl::Appender::Limit, and Log::Log4perl::Appender::Buffer.
228 Check their manual pages for details.
229 Composite appender objects are regular Log::Log4perl::Appender objects,
231 but they have the composite flag set:
232 $app->composite(1);
234 and they define a post_init() method, which sets the appender it relays
236 its messages to:
237 ###########################################
239 sub post_init {
240 ############################################
241 my($self) = @_;
242 if(! exists $self->{appender}) {
244 die "No appender defined for " . __PACKAGE__;
245 }
246 my $appenders = Log::Log4perl->appenders();
248 my $appender = Log::Log4perl->appenders()->{$self->{appender}};
249 if(! defined $appender) {
251 die "Appender $self->{appender} not defined (yet) when " .
252 __PACKAGE__ . " needed it";
253 }
254 $self->{app} = $appender;
256 }
257 The reason for this post-processing step is that the relay appender
259 might not be defined yet when the composite appender gets defined.
260 This can happen if Log4perl is initialized with a configuration file
261 (which is the most common way to initialize Log4perl), because
262 appenders spring into existence in unpredictable order.
263 For example, if you define a Synchronized appender like
265 log4perl.appender.Syncer = Log::Log4perl::Appender::Synchronized
267 log4perl.appender.Syncer.appender = Logfile
268 then Log4perl will set the appender's "appender" attribute to the name
270 of the appender to finally relay messages to. After the Log4perl
271 configuration file has been processed, Log4perl will remember to call
272 the composite appender's post_init() method, which will grab the relay
273 appender instance referred to by the name (Logfile) and set it in its
274 "app" attribute. This is exactly what the code snippet above does.
275 But if you initialize Log4perl by its API, you need to remember to
277 perform these steps. Here's the lineup:
278 use Log::Log4perl qw(get_logger :levels);
280 my $fileApp = Log::Log4perl::Appender->new(
282 'Log::Log4perl::Appender::File',
283 name => 'MyFileApp',
284 filename => 'mylog',
285 mode => 'append',
286 );
287 $fileApp->layout(
288 Log::Log4perl::Layout::PatternLayout::Multiline->new(
289 '%d{yyyy-MM-dd HH:mm:ss} %p [%c] #%P> %m%n')
290 );
291 # Make the appender known to the system (without assigning it to
292 # any logger
293 Log::Log4perl->add_appender( $fileApp );
294 my $syncApp = Log::Log4perl::Appender->new(
296 'Log::Log4perl::Appender::Synchronized',
297 name => 'MySyncApp',
298 appender => 'MyFileApp',
299 key => 'nem',
300 );
301 $syncApp->post_init();
302 $syncApp->composite(1);
303 # The Synchronized appender is now ready, assign it to a logger
305 # and start logging.
306 get_logger("")->add_appender($syncApp);
307 get_logger("")->level($DEBUG);
309 get_logger("wonk")->debug("waah!");
310 The composite appender's log() function will typically cache incoming
312 messages until a certain trigger condition is met and then forward a
313 bulk of messages to the relay appender.
314 Caching messages is surprisingly tricky, because you want them to look
316 like they came from the code location they were originally issued from
317 and not from the location that triggers the flush. Luckily, Log4perl
318 offers a cache mechanism for messages, all you need to do is call the
319 base class' log() function with an additional reference to a scalar,
320 and then save its content to your composite appender's message buffer
321 afterwards:
322 ###########################################
324 sub log {
325 ###########################################
326 my($self, %params) = @_;
327 # ... some logic to decide whether to cache or flush
329 # Adjust the caller stack
331 local $Log::Log4perl::caller_depth =
332 $Log::Log4perl::caller_depth + 2;
333 # We need to cache.
335 # Ask the appender to save a cached message in $cache
336 $self->{relay_app}->SUPER::log(\%params,
337 $params{log4p_category},
338 $params{log4p_level}, \my $cache);
339 # Save it in the appender's message buffer
341 push @{ $self->{buffer} }, $cache;
342 }
343 Note that before calling the log() method of the relay appender's base
345 class (and thus introducing two additional levels on the call stack),
346 we need to adjust the call stack to allow Log4perl to render cspecs
347 like the %M or %L correctly. The cache will then contain a correctly
348 rendered message, according to the layout of the target appender.
349 Later, when the time comes to flush the cached messages, a call to the
351 relay appender's base class' log_cached() method with the cached
352 message as an argument will forward the correctly rendered message:
353 ###########################################
355 sub log {
356 ###########################################
357 my($self, %params) = @_;
358 # ... some logic to decide whether to cache or flush
360 # Flush pending messages if we have any
362 for my $cache (@{$self->{buffer}}) {
363 $self->{relay_app}->SUPER::log_cached($cache);
364 }
365 }
366
368 Log::Dispatch
369
371 Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess
372 <cpan@goess.org>.
373 This library is free software; you can redistribute it and/or modify it
375 under the same terms as Perl itself.
376
378 Please contribute patches to the project on Github:
379 http://github.com/mschilli/log4perl
381 Send bug reports or requests for enhancements to the authors via our
383 MAILING LIST (questions, bug reports, suggestions/patches):
385 log4perl-devel@lists.sourceforge.net
386 Authors (please contact them via the list above, not directly): Mike
388 Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
389 Contributors (in alphabetical order): Ateeq Altaf, Cory Bennett, Jens
391 Berthold, Jeremy Bopp, Hutton Davidson, Chris R. Donnelly, Matisse
392 Enzer, Hugh Esco, Anthony Foiani, James FitzGibbon, Carl Franks, Dennis
393 Gregorovic, Andy Grundman, Paul Harrington, Alexander Hartmaier David
394 Hull, Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter,
395 Brett Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope, Lars
396 Thegler, David Viner, Mac Yang.
397perl v5.32.1 2021-02-08 Appender(3)