1Appender(3)           User Contributed Perl Documentation          Appender(3)
2
3
4

NAME

6       Log::Log4perl::Appender - Log appender class
7

SYNOPSIS

9         use Log::Log4perl;
10
11             # Define a logger
12         my $logger = Log::Log4perl->get_logger("abc.def.ghi");
13
14             # Define a layout
15         my $layout = Log::Log4perl::Layout::PatternLayout->new(
16                          "%d (%F:%L)> %m");
17
18             # Define an appender
19         my $appender = Log::Log4perl::Appender->new(
20                          "Log::Log4perl::Appender::Screen",
21                          name => 'dumpy');
22
23             # Set the appender's layout
24         $appender->layout($layout);
25         $logger->add_appender($appender);
26

DESCRIPTION

28       This class is a wrapper around the "Log::Log4perl::Appender" appender
29       set.
30
31       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

FUNCTIONS

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
43             # Define an appender
44         my $appender = Log::Log4perl::Appender->new(
45             "Log::Log4perl::Appender::File"
46             filename => 'out.log');
47
48       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
52         print "The appender's name is ", $appender->name(), "\n";
53
54       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
58       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
64       The "new()" method will just pass these parameters on to a newly
65       created "Log::Dispatch::*" object of the specified type.
66
67       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
71   $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
76           Log::Log4perl::Layout::SimpleLayout
77           Log::Log4perl::Layout::PatternLayout
78
79       Please check the Log::Log4perl::Layout::SimpleLayout and
80       Log::Log4perl::Layout::PatternLayout manual pages for details.
81

Supported Appenders

83       Here's the list of appender modules currently available via
84       "Log::Dispatch", if not noted otherwise, written by Dave Rolsky:
85
86              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
99       "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

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

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
109       message
110           Text of the rendered message
111
112       log4p_category
113           Name of the category of the logger that triggered the event.
114
115       log4p_level
116           Log::Log4perl level of the event
117

Pitfalls

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
125           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
130       will always append to an existing logfile "test.log" while if you
131       specifically request clobbering like in
132
133           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
139       it will overwrite an existing log file "test.log" and start from
140       scratch.
141

Appenders Expecting Message Chunks

143       Instead of simple strings, certain appenders are expecting multiple
144       fields as log messages. If a statement like
145
146           $logger->debug($ip, $user, "signed in");
147
148       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
154       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
159       The  "warp_message" appender option is used to specify the desired
160       behavior.  If no setting for the appender property
161
162           # *** Not defined ***
163           # log4perl.appender.SomeApp.warp_message
164
165       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
170       If, on the other hand, it is set to a false value, like in
171
172           log4perl.appender.SomeApp.layout=NoopLayout
173           log4perl.appender.SomeApp.warp_message = 0
174
175       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
181       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
187       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
192           log4perl.appender.SomeApp.layout=NoopLayout
193           log4perl.appender.SomeApp.warp_message = sub { \
194                                                  $#_ = 2 if @_ > 3; \
195                                                  return @_; }
196
197       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
203       Also, the warp function can be specified by name like in
204
205           log4perl.appender.SomeApp.layout=NoopLayout
206           log4perl.appender.SomeApp.warp_message = main::filter_my_message
207
208       In this example, "filter_my_message" is a function in the "main"
209       package, defined like this:
210
211           my $COUNTER = 0;
212
213           sub filter_my_message {
214               my @chunks = @_;
215               unshift @chunks, ++$COUNTER;
216               return @chunks;
217           }
218
219       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
223   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
230       Composite appender objects are regular Log::Log4perl::Appender objects,
231       but they have the composite flag set:
232
233           $app->composite(1);
234
235       and they define a post_init() method, which sets the appender it relays
236       its messages to:
237
238           ###########################################
239           sub post_init {
240           ############################################
241               my($self) = @_;
242
243               if(! exists $self->{appender}) {
244                   die "No appender defined for " . __PACKAGE__;
245               }
246
247               my $appenders = Log::Log4perl->appenders();
248               my $appender = Log::Log4perl->appenders()->{$self->{appender}};
249
250               if(! defined $appender) {
251                   die "Appender $self->{appender} not defined (yet) when " .
252                       __PACKAGE__ . " needed it";
253               }
254
255               $self->{app} = $appender;
256           }
257
258       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
264       For example, if you define a Synchronized appender like
265
266           log4perl.appender.Syncer            = Log::Log4perl::Appender::Synchronized
267           log4perl.appender.Syncer.appender   = Logfile
268
269       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
276       But if you initialize Log4perl by its API, you need to remember to
277       perform these steps. Here's the lineup:
278
279           use Log::Log4perl qw(get_logger :levels);
280
281           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
295           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
304             # The Synchronized appender is now ready, assign it to a logger
305             # and start logging.
306           get_logger("")->add_appender($syncApp);
307
308           get_logger("")->level($DEBUG);
309           get_logger("wonk")->debug("waah!");
310
311       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
315       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
323           ###########################################
324           sub log {
325           ###########################################
326               my($self, %params) = @_;
327
328               # ... some logic to decide whether to cache or flush
329
330                   # Adjust the caller stack
331               local $Log::Log4perl::caller_depth =
332                     $Log::Log4perl::caller_depth + 2;
333
334                   # 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
340                   # Save it in the appender's message buffer
341               push @{ $self->{buffer} }, $cache;
342           }
343
344       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
350       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
354           ###########################################
355           sub log {
356           ###########################################
357               my($self, %params) = @_;
358
359               # ... some logic to decide whether to cache or flush
360
361                   # Flush pending messages if we have any
362               for my $cache (@{$self->{buffer}}) {
363                   $self->{relay_app}->SUPER::log_cached($cache);
364               }
365           }
366

SEE ALSO

368       Log::Dispatch
369

LICENSE

371       Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess
372       <cpan@goess.org>.
373
374       This library is free software; you can redistribute it and/or modify it
375       under the same terms as Perl itself.
376

AUTHOR

378       Please contribute patches to the project on Github:
379
380           http://github.com/mschilli/log4perl
381
382       Send bug reports or requests for enhancements to the authors via our
383
384       MAILING LIST (questions, bug reports, suggestions/patches):
385       log4perl-devel@lists.sourceforge.net
386
387       Authors (please contact them via the list above, not directly): Mike
388       Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
389
390       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.
397
398
399
400perl v5.32.1                      2021-02-08                       Appender(3)
Impressum