1FAQ(3) User Contributed Perl Documentation FAQ(3)
2
6 Log::Log4perl::FAQ - Frequently Asked Questions on Log::Log4perl
7
9 This FAQ shows a wide variety of commonly encountered logging tasks and
10 how to solve them in the most elegant way with Log::Log4perl. Most of
11 the time, this will be just a matter of smartly configuring your
12 Log::Log4perl configuration files.
13 Why use Log::Log4perl instead of any other logging module on CPAN?
15 That's a good question. There's dozens of logging modules on CPAN.
16 When it comes to logging, people typically think: "Aha. Writing out
17 debug and error messages. Debug is lower than error. Easy. I'm gonna
18 write my own." Writing a logging module is like a rite of passage for
19 every Perl programmer, just like writing your own templating system.
20 Of course, after getting the basics right, features need to be added.
22 You'd like to write a timestamp with every message. Then timestamps
23 with microseconds. Then messages need to be written to both the screen
24 and a log file.
25 And, as your application grows in size you might wonder: Why doesn't my
27 logging system scale along with it? You would like to switch on logging
28 in selected parts of the application, and not all across the board,
29 because this kills performance. This is when people turn to
30 Log::Log4perl, because it handles all of that.
31 Avoid this costly switch.
33 Use "Log::Log4perl" right from the start. "Log::Log4perl"'s ":easy"
35 mode supports easy logging in simple scripts:
36 use Log::Log4perl qw(:easy);
38 Log::Log4perl->easy_init($DEBUG);
39 DEBUG "A low-level message";
41 ERROR "Won't make it until level gets increased to ERROR";
42 And when your application inevitably grows, your logging system grows
44 with it without you having to change any code.
45 Please, don't re-invent logging. "Log::Log4perl" is here, it's easy to
47 use, it scales, and covers many areas you haven't thought of yet, but
48 will enter soon.
49 What's the easiest way to use Log4perl?
51 If you just want to get all the comfort of logging, without much
52 overhead, use Stealth Loggers. If you use Log::Log4perl in ":easy" mode
53 like
54 use Log::Log4perl qw(:easy);
56 you'll have the following functions available in the current package:
58 DEBUG("message");
60 INFO("message");
61 WARN("message");
62 ERROR("message");
63 FATAL("message");
64 Just make sure that every package of your code where you're using them
66 in pulls in "use Log::Log4perl qw(:easy)" first, then you're set.
67 Every stealth logger's category will be equivalent to the name of the
68 package it's located in.
69 These stealth loggers will be absolutely silent until you initialize
71 Log::Log4perl in your main program with either
72 # Define any Log4perl behaviour
74 Log::Log4perl->init("foo.conf");
75 (using a full-blown Log4perl config file) or the super-easy method
77 # Just log to STDERR
79 Log::Log4perl->easy_init($DEBUG);
80 or the parameter-style method with a complexity somewhat in between:
82 # Append to a log file
84 Log::Log4perl->easy_init( { level => $DEBUG,
85 file => ">>test.log" } );
86 For more info, please check out "Stealth Loggers" in Log::Log4perl.
88 How can I simply log all my ERROR messages to a file?
90 After pulling in the "Log::Log4perl" module, just initialize its
91 behaviour by passing in a configuration to its "init" method as a
92 string reference. Then, obtain a logger instance and write out a
93 message with its "error()" method:
94 use Log::Log4perl qw(get_logger);
96 # Define configuration
98 my $conf = q(
99 log4perl.logger = ERROR, FileApp
100 log4perl.appender.FileApp = Log::Log4perl::Appender::File
101 log4perl.appender.FileApp.filename = test.log
102 log4perl.appender.FileApp.layout = PatternLayout
103 log4perl.appender.FileApp.layout.ConversionPattern = %d> %m%n
104 );
105 # Initialize logging behaviour
107 Log::Log4perl->init( \$conf );
108 # Obtain a logger instance
110 my $logger = get_logger("Bar::Twix");
111 $logger->error("Oh my, a dreadful error!");
112 $logger->warn("Oh my, a dreadful warning!");
113 This will append something like
115 2002/10/29 20:11:55> Oh my, a dreadful error!
117 to the log file "test.log". How does this all work?
119 While the Log::Log4perl "init()" method typically takes the name of a
121 configuration file as its input parameter like in
122 Log::Log4perl->init( "/path/mylog.conf" );
124 the example above shows how to pass in a configuration as text in a
126 scalar reference.
127 The configuration as shown defines a logger of the root category, which
129 has an appender of type "Log::Log4perl::Appender::File" attached. The
130 line
131 log4perl.logger = ERROR, FileApp
133 doesn't list a category, defining a root logger. Compare that with
135 log4perl.logger.Bar.Twix = ERROR, FileApp
137 which would define a logger for the category "Bar::Twix", showing
139 probably different behaviour. "FileApp" on the right side of the
140 assignment is an arbitrarily defined variable name, which is only used
141 to somehow reference an appender defined later on.
142 Appender settings in the configuration are defined as follows:
144 log4perl.appender.FileApp = Log::Log4perl::Appender::File
146 log4perl.appender.FileApp.filename = test.log
147 It selects the file appender of the "Log::Log4perl::Appender"
149 hierarchy, which will append to the file "test.log" if it already
150 exists. If we wanted to overwrite a potentially existing file, we would
151 have to explicitly set the appropriate "Log::Log4perl::Appender::File"
152 parameter "mode":
153 log4perl.appender.FileApp = Log::Log4perl::Appender::File
155 log4perl.appender.FileApp.filename = test.log
156 log4perl.appender.FileApp.mode = write
157 Also, the configuration defines a PatternLayout format, adding the
159 nicely formatted current date and time, an arrow (>) and a space before
160 the messages, which is then followed by a newline:
161 log4perl.appender.FileApp.layout = PatternLayout
163 log4perl.appender.FileApp.layout.ConversionPattern = %d> %m%n
164 Obtaining a logger instance and actually logging something is typically
166 done in a different system part as the Log::Log4perl initialisation
167 section, but in this example, it's just done right after init for the
168 sake of compactness:
169 # Obtain a logger instance
171 my $logger = get_logger("Bar::Twix");
172 $logger->error("Oh my, a dreadful error!");
173 This retrieves an instance of the logger of the category "Bar::Twix",
175 which, as all other categories, inherits behaviour from the root logger
176 if no other loggers are defined in the initialization section.
177 The "error()" method fires up a message, which the root logger catches.
179 Its priority is equal to or higher than the root logger's priority
180 (ERROR), which causes the root logger to forward it to its attached
181 appender. By contrast, the following
182 $logger->warn("Oh my, a dreadful warning!");
184 doesn't make it through, because the root logger sports a higher
186 setting (ERROR and up) than the WARN priority of the message.
187 How can I install Log::Log4perl on Microsoft Windows?
189 Log::Log4perl is fully supported on the Win32 platform. It has been
190 tested with Activestate perl 5.6.1 under Windows 98 and rumor has it
191 that it also runs smoothly on all other major flavors (Windows NT,
192 2000, XP, etc.).
193 It also runs nicely with ActiveState 5.8.0, and, believe me, we had to
195 jump through some major hoops for that.
196 Typically, Win32 systems don't have the "make" utility installed, so
198 the standard "perl Makefile.PL; make install" on the downloadable
199 distribution won't work. But don't despair, there's a very easy
200 solution!
201 The "Log::Log4perl" homepage provides a so-called PPD file for
203 ActiveState's "ppm" installer, which comes with ActiveState perl by
204 default.
205 Install on ActiveState 5.6.*
207 The DOS command line
208 ppm install "http://log4perl.sourceforge.net/ppm/Log-Log4perl.ppd"
210 will contact the Log4perl homepage, download the latest
212 "Log::Log4perl" distribution and install it. If your ActiveState
213 installation lacks any of the modules "Log::Log4perl" depends upon,
214 "ppm" will automatically contact ActivateState and download them
215 from their CPAN-like repository.
216 Install on ActiveState 5.8.*
218 ActiveState's "Programmer's Package Manager" can be called from
219 Window's Start Menu: Start->Programs->>ActiveState ActivePerl
220 5.8>Perl Package Manager will invoke ppm. Since Log::Log4perl
221 hasn't made it yet into the standard ActiveState repository (and
222 you probably don't want their outdated packages anyway), just tell
223 ppm the first time you call it to add the Log4perl repository
224 ppm> repository add http://log4perl.sourceforge.net/ppm
226 Then, just tell it to install Log::Log4perl and it will resolve all
228 dependencies automatically and fetch them from
229 log4perl.sourceforge.net if it can't find them in the main
230 archives:
231 ppm> install Log-Log4perl
233 That's it! Afterwards, just create a Perl script like
235 use Log::Log4perl qw(:easy);
237 Log::Log4perl->easy_init($DEBUG);
238 my $logger = get_logger("Twix::Bar");
240 $logger->debug("Watch me!");
241 and run it. It should print something like
243 2002/11/06 01:22:05 Watch me!
245 If you find that something doesn't work, please let us know at
247 log4perl-devel@lists.sourceforge.net -- we'll apprechiate it. Have fun!
248 How can I include global (thread-specific) data in my log messages?
250 Say, you're writing a web application and want all your log messages to
251 include the current client's IP address. Most certainly, you don't want
252 to include it in each and every log message like in
253 $logger->debug( $r->connection->remote_ip,
255 " Retrieving user data from DB" );
256 do you? Instead, you want to set it in a global data structure and have
258 Log::Log4perl include it automatically via a PatternLayout setting in
259 the configuration file:
260 log4perl.appender.FileApp.layout.ConversionPattern = %X{ip} %m%n
262 The conversion specifier %X{ip} references an entry under the key "ip"
264 in the global "MDC" (mapped diagnostic context) table, which you've set
265 once via
266 Log::Log4perl::MDC->put("ip", $r->connection->remote_ip);
268 at the start of the request handler. Note that this is a static (class)
270 method, there's no logger object involved. You can use this method
271 with as many key/value pairs as you like as long as you reference them
272 under different names.
273 The mappings are stored in a global hash table within Log::Log4perl.
275 Luckily, because the thread model in 5.8.0 doesn't share global
276 variables between threads unless they're explicitly marked as such,
277 there's no problem with multi-threaded environments.
278 For more details on the MDC, please refer to "Mapped Diagnostic Context
280 (MDC)" in Log::Log4perl and Log::Log4perl::MDC.
281 My application is already logging to a file. How can I duplicate all
283 messages to also go to the screen?
284 Assuming that you already have a Log4perl configuration file like
285 log4perl.logger = DEBUG, FileApp
287 log4perl.appender.FileApp = Log::Log4perl::Appender::File
289 log4perl.appender.FileApp.filename = test.log
290 log4perl.appender.FileApp.layout = PatternLayout
291 log4perl.appender.FileApp.layout.ConversionPattern = %d> %m%n
292 and log statements all over your code, it's very easy with Log4perl to
294 have the same messages both printed to the logfile and the screen. No
295 reason to change your code, of course, just add another appender to the
296 configuration file and you're done:
297 log4perl.logger = DEBUG, FileApp, ScreenApp
299 log4perl.appender.FileApp = Log::Log4perl::Appender::File
301 log4perl.appender.FileApp.filename = test.log
302 log4perl.appender.FileApp.layout = PatternLayout
303 log4perl.appender.FileApp.layout.ConversionPattern = %d> %m%n
304 log4perl.appender.ScreenApp = Log::Log4perl::Appender::Screen
306 log4perl.appender.ScreenApp.stderr = 0
307 log4perl.appender.ScreenApp.layout = PatternLayout
308 log4perl.appender.ScreenApp.layout.ConversionPattern = %d> %m%n
309 The configuration file above is assuming that both appenders are active
311 in the same logger hierarchy, in this case the "root" category. But
312 even if you've got file loggers defined in several parts of your
313 system, belonging to different logger categories, each logging to
314 different files, you can gobble up all logged messages by defining a
315 root logger with a screen appender, which would duplicate messages from
316 all your file loggers to the screen due to Log4perl's appender
317 inheritance. Check
318 http://www.perl.com/pub/a/2002/09/11/log4perl.html
320 for details. Have fun!
322 How can I make sure my application logs a message when it dies
324 unexpectedly?
325 Whenever you encounter a fatal error in your application, instead of
326 saying something like
327 open FILE, "<blah" or die "Can't open blah -- bailing out!";
329 just use Log::Log4perl's fatal functions instead:
331 my $log = get_logger("Some::Package");
333 open FILE, "<blah" or $log->logdie("Can't open blah -- bailing out!");
334 This will both log the message with priority FATAL according to your
336 current Log::Log4perl configuration and then call Perl's "die()"
337 afterwards to terminate the program. It works the same with stealth
338 loggers (see "Stealth Loggers" in Log::Log4perl), all you need to do is
339 call
340 use Log::Log4perl qw(:easy);
342 open FILE, "<blah" or LOGDIE "Can't open blah -- bailing out!";
343 What can you do if you're using some library which doesn't use
345 Log::Log4perl and calls "die()" internally if something goes wrong? Use
346 a $SIG{__DIE__} pseudo signal handler
347 use Log::Log4perl qw(get_logger);
349 $SIG{__DIE__} = sub {
351 if($^S) {
352 # We're in an eval {} and don't want log
353 # this message but catch it later
354 return;
355 }
356 local $Log::Log4perl::caller_depth =
357 $Log::Log4perl::caller_depth + 1;
358 my $logger = get_logger("");
359 $logger->fatal(@_);
360 die @_; # Now terminate really
361 };
362 This will catch every "die()"-Exception of your application or the
364 modules it uses. In case you want to It will fetch a root logger and
365 pass on the "die()"-Message to it. If you make sure you've configured
366 with a root logger like this:
367 Log::Log4perl->init(\q{
369 log4perl.category = FATAL, Logfile
370 log4perl.appender.Logfile = Log::Log4perl::Appender::File
371 log4perl.appender.Logfile.filename = fatal_errors.log
372 log4perl.appender.Logfile.layout = \
373 Log::Log4perl::Layout::PatternLayout
374 log4perl.appender.Logfile.layout.ConversionPattern = %F{1}-%L (%M)> %m%n
375 });
376 then all "die()" messages will be routed to a file properly. The line
378 local $Log::Log4perl::caller_depth =
380 $Log::Log4perl::caller_depth + 1;
381 in the pseudo signal handler above merits a more detailed explanation.
383 With the setup above, if a module calls "die()" in one of its
384 functions, the fatal message will be logged in the signal handler and
385 not in the original function -- which will cause the %F, %L and %M
386 placeholders in the pattern layout to be replaced by the filename, the
387 line number and the function/method name of the signal handler, not the
388 error-throwing module. To adjust this, Log::Log4perl has the
389 $caller_depth variable, which defaults to 0, but can be set to positive
390 integer values to offset the caller level. Increasing it by one will
391 cause it to log the calling function's parameters, not the ones of the
392 signal handler. See "Using Log::Log4perl from wrapper classes" in
393 Log::Log4perl for more details.
394 How can I hook up the LWP library with Log::Log4perl?
396 Or, to put it more generally: How can you utilize a third-party
397 library's embedded logging and debug statements in Log::Log4perl? How
398 can you make them print to configurable appenders, turn them on and
399 off, just as if they were regular Log::Log4perl logging statements?
400 The easiest solution is to map the third-party library logging
402 statements to Log::Log4perl's stealth loggers via a typeglob
403 assignment.
404 As an example, let's take LWP, one of the most popular Perl modules,
406 which makes handling WWW requests and responses a breeze. Internally,
407 LWP uses its own logging and debugging system, utilizing the following
408 calls inside the LWP code (from the LWP::Debug man page):
409 # Function tracing
411 LWP::Debug::trace('send()');
412 # High-granular state in functions
414 LWP::Debug::debug('url ok');
415 # Data going over the wire
417 LWP::Debug::conns("read $n bytes: $data");
418 First, let's assign Log::Log4perl priorities to these functions: I'd
420 suggest that "debug()" messages have priority "INFO", "trace()" uses
421 "DEBUG" and "conns()" also logs with "DEBUG" -- although your mileage
422 may certainly vary.
423 Now, in order to transpartently hook up LWP::Debug with Log::Log4perl,
425 all we have to do is say
426 package LWP::Debug;
428 use Log::Log4perl qw(:easy);
429 *trace = *INFO;
431 *conns = *DEBUG;
432 *debug = *DEBUG;
433 package main;
435 # ... go on with your regular program ...
436 at the beginning of our program. In this way, every time the, say,
438 "LWP::UserAgent" module calls "LWP::Debug::trace()", it will
439 implicitely call INFO(), which is the "info()" method of a stealth
440 logger defined for the Log::Log4perl category "LWP::Debug". Is this
441 cool or what?
442 Here's a complete program:
444 use LWP::UserAgent;
446 use HTTP::Request::Common;
447 use Log::Log4perl qw(:easy);
448 Log::Log4perl->easy_init(
450 { category => "LWP::Debug",
451 level => $DEBUG,
452 layout => "%r %p %M-%L %m%n",
453 });
454 package LWP::Debug;
456 use Log::Log4perl qw(:easy);
457 *trace = *INFO;
458 *conns = *DEBUG;
459 *debug = *DEBUG;
460 package main;
462 my $ua = LWP::UserAgent->new();
463 my $resp = $ua->request(GET "http://amazon.com");
464 if($resp->is_success()) {
466 print "Success: Received ",
467 length($resp->content()), "\n";
468 } else {
469 print "Error: ", $resp->code(), "\n";
470 }
471 This will generate the following output on STDERR:
473 174 INFO LWP::UserAgent::new-164 ()
475 208 INFO LWP::UserAgent::request-436 ()
476 211 INFO LWP::UserAgent::send_request-294 GET http://amazon.com
477 212 DEBUG LWP::UserAgent::_need_proxy-1123 Not proxied
478 405 INFO LWP::Protocol::http::request-122 ()
479 859 DEBUG LWP::Protocol::collect-206 read 233 bytes
480 863 DEBUG LWP::UserAgent::request-443 Simple response: Found
481 869 INFO LWP::UserAgent::request-436 ()
482 871 INFO LWP::UserAgent::send_request-294
483 GET http://www.amazon.com:80/exec/obidos/gateway_redirect
484 872 DEBUG LWP::UserAgent::_need_proxy-1123 Not proxied
485 873 INFO LWP::Protocol::http::request-122 ()
486 1016 DEBUG LWP::UserAgent::request-443 Simple response: Found
487 1020 INFO LWP::UserAgent::request-436 ()
488 1022 INFO LWP::UserAgent::send_request-294
489 GET http://www.amazon.com/exec/obidos/subst/home/home.html/
490 1023 DEBUG LWP::UserAgent::_need_proxy-1123 Not proxied
491 1024 INFO LWP::Protocol::http::request-122 ()
492 1382 DEBUG LWP::Protocol::collect-206 read 632 bytes
493 ...
494 2605 DEBUG LWP::Protocol::collect-206 read 77 bytes
495 2607 DEBUG LWP::UserAgent::request-443 Simple response: OK
496 Success: Received 42584
497 Of course, in this way, the embedded logging and debug statements
499 within LWP can be utilized in any Log::Log4perl way you can think of.
500 You can have them sent to different appenders, block them based on the
501 category and everything else Log::Log4perl has to offer.
502 Only drawback of this method: Steering logging behaviour via category
504 is always based on the "LWP::Debug" package. Although the logging
505 statements reflect the package name of the issuing module properly, the
506 stealth loggers in "LWP::Debug" are all of the category "LWP::Debug".
507 This implies that you can't control the logging behaviour based on the
508 package that's initiating a log request (e.g. LWP::UserAgent) but only
509 based on the package that's actually executing the logging statement,
510 "LWP::Debug" in this case.
511 To work around this conundrum, we need to write a wrapper function and
513 plant it into the "LWP::Debug" package. It will determine the caller
514 and create a logger bound to a category with the same name as the
515 caller's package:
516 package LWP::Debug;
518 use Log::Log4perl qw(:levels get_logger);
520 sub l4p_wrapper {
522 my($prio, @message) = @_;
523 $Log::Log4perl::caller_depth += 2;
524 get_logger(scalar caller(1))->log($prio, @message);
525 $Log::Log4perl::caller_depth -= 2;
526 }
527 no warnings 'redefine';
529 *trace = sub { l4p_wrapper($INFO, @_); };
530 *debug = *conns = sub { l4p_wrapper($DEBUG, @_); };
531 package main;
533 # ... go on with your main program ...
534 This is less performant than the previous approach, because every log
536 request will request a reference to a logger first, then call the
537 wrapper, which will in turn call the appropriate log function.
538 This hierarchy shift has to be compensated for by increasing
540 $Log::Log4perl::caller_depth by 2 before calling the log function and
541 decreasing it by 2 right afterwards. Also, the "l4p_wrapper" function
542 shown above calls caller(1) which determines the name of the package
543 two levels down the calling hierarchy (and therefore compensates for
544 both the wrapper function and the anonymous subroutine calling it).
545 "no warnings 'redefine'" suppresses a warning Perl would generate
547 otherwise upon redefining "LWP::Debug"'s "trace()", "debug()" and
548 "conns()" functions. In case you use a perl prior to 5.6.x, you need to
549 manipulate $^W instead.
550 To make things easy for you when dealing with LWP, Log::Log4perl 0.47
552 introduces "Log::Log4perl->infiltrate_lwp()" which does exactly the
553 above.
554 What if I need dynamic values in a static Log4perl configuration file?
556 Say, your application uses Log::Log4perl for logging and therefore
557 comes with a Log4perl configuration file, specifying the logging
558 behaviour. But, you also want it to take command line parameters to
559 set values like the name of the log file. How can you have both a
560 static Log4perl configuration file and a dynamic command line
561 interface?
562 As of Log::Log4perl 0.28, every value in the configuration file can be
564 specified as a Perl hook. So, instead of saying
565 log4perl.appender.Logfile.filename = test.log
567 you could just as well have a Perl subroutine deliver the value
569 dynamically:
570 log4perl.appender.Logfile.filename = sub { logfile(); };
572 given that "logfile()" is a valid function in your "main" package
574 returning a string containing the path to the log file.
575 Or, think about using the value of an environment variable:
577 log4perl.appender.DBI.user = sub { $ENV{USERNAME} };
579 When "Log::Log4perl->init()" parses the configuration file, it will
581 notice the assignment above because of its "sub {...}" pattern and
582 treat it in a special way: It will evaluate the subroutine (which can
583 contain arbitrary Perl code) and take its return value as the right
584 side of the assignment.
585 A typical application would be called like this on the command line:
587 app # log file is "test.log"
589 app -l mylog.txt # log file is "mylog.txt"
590 Here's some sample code implementing the command line interface above:
592 use Log::Log4perl qw(get_logger);
594 use Getopt::Std;
595 getopt('l:', \our %OPTS);
597 my $conf = q(
599 log4perl.category.Bar.Twix = WARN, Logfile
600 log4perl.appender.Logfile = Log::Log4perl::Appender::File
601 log4perl.appender.Logfile.filename = sub { logfile(); };
602 log4perl.appender.Logfile.layout = SimpleLayout
603 );
604 Log::Log4perl::init(\$conf);
606 my $logger = get_logger("Bar::Twix");
608 $logger->error("Blah");
609 ###########################################
611 sub logfile {
612 ###########################################
613 if(exists $OPTS{l}) {
614 return $OPTS{l};
615 } else {
616 return "test.log";
617 }
618 }
619 Every Perl hook may contain arbitrary perl code, just make sure to
621 fully qualify eventual variable names (e.g. %main::OPTS instead of
622 %OPTS).
623 SECURITY NOTE: this feature means arbitrary perl code can be embedded
625 in the config file. In the rare case where the people who have access
626 to your config file are different from the people who write your code
627 and shouldn't have execute rights, you might want to call
628 $Log::Log4perl::Config->allow_code(0);
630 before you call init(). This will prevent Log::Log4perl from executing
632 any Perl code in the config file (including code for custom conversion
633 specifiers (see "Custom cspecs" in
634 Log::Log4perl::Layout::PatternLayout).
635 How can I roll over my logfiles automatically at midnight?
637 Long-running applications tend to produce ever-increasing logfiles.
638 For backup and cleanup purposes, however, it is often desirable to move
639 the current logfile to a different location from time to time and start
640 writing a new one.
641 This is a non-trivial task, because it has to happen in sync with the
643 logging system in order not to lose any messages in the process.
644 Luckily, Mark Pfeiffer's "Log::Dispatch::FileRotate" appender works
646 well with Log::Log4perl to rotate your logfiles in a variety of ways.
647 Note, however, that having the application deal with rotating a log
649 file is not cheap. Among other things, it requires locking the log file
650 with every write to avoid race conditions. There are good reasons to
651 use external rotators like "newsyslog" instead. See the entry "How can
652 I rotate a logfile with newsyslog?" in the FAQ for more information on
653 how to configure it.
654 When using "Log::Dispatch::FileRotate", all you have to do is specify
656 it in your Log::Log4perl configuration file and your logfiles will be
657 rotated automatically.
658 You can choose between rolling based on a maximum size ("roll if
660 greater than 10 MB") or based on a date pattern ("roll everyday at
661 midnight"). In both cases, "Log::Dispatch::FileRotate" allows you to
662 define a number "max" of saved files to keep around until it starts
663 overwriting the oldest ones. If you set the "max" parameter to 2 and
664 the name of your logfile is "test.log", "Log::Dispatch::FileRotate"
665 will move "test.log" to "test.log.1" on the first rollover. On the
666 second rollover, it will move "test.log.1" to "test.log.2" and then
667 "test.log" to "test.log.1". On the third rollover, it will move
668 "test.log.1" to "test.log.2" (therefore discarding the old
669 "test.log.2") and "test.log" to "test.log.1". And so forth. This way,
670 there's always going to be a maximum of 2 saved log files around.
671 Here's an example of a Log::Log4perl configuration file, defining a
673 daily rollover at midnight (date pattern "yyyy-MM-dd"), keeping a
674 maximum of 5 saved logfiles around:
675 log4perl.category = WARN, Logfile
677 log4perl.appender.Logfile = Log::Dispatch::FileRotate
678 log4perl.appender.Logfile.filename = test.log
679 log4perl.appender.Logfile.max = 5
680 log4perl.appender.Logfile.DatePattern = yyyy-MM-dd
681 log4perl.appender.Logfile.TZ = PST
682 log4perl.appender.Logfile.layout = \
683 Log::Log4perl::Layout::PatternLayout
684 log4perl.appender.Logfile.layout.ConversionPattern = %d %m %n
685 Please see the "Log::Dispatch::FileRotate" documentation for details.
687 "Log::Dispatch::FileRotate" is available on CPAN.
688 What's the easiest way to turn off all logging, even with a lengthy
690 Log4perl configuration file?
691 In addition to category-based levels and appender thresholds,
692 Log::Log4perl supports system-wide logging thresholds. This is the
693 minimum level the system will require of any logging events in order
694 for them to make it through to any configured appenders.
695 For example, putting the line
697 log4perl.threshold = ERROR
699 anywhere in your configuration file will limit any output to any
701 appender to events with priority of ERROR or higher (ERROR or FATAL
702 that is).
703 However, in order to suppress all logging entirely, you need to use a
705 priority that's higher than FATAL: It is simply called "OFF", and it is
706 never used by any logger. By definition, it is higher than the highest
707 defined logger level.
708 Therefore, if you keep the line
710 log4perl.threshold = OFF
712 somewhere in your Log::Log4perl configuration, the system will be quiet
714 as a graveyard. If you deactivate the line (e.g. by commenting it out),
715 the system will, upon config reload, snap back to normal operation,
716 providing logging messages according to the rest of the configuration
717 file again.
718 I keep getting duplicate log messages! What's wrong?
720 Having several settings for related categories in the Log4perl
721 configuration file sometimes leads to a phenomenon called "message
722 duplication". It can be very confusing at first, but if thought through
723 properly, it turns out that Log4perl behaves as advertised. But, don't
724 despair, of course there's a number of ways to avoid message
725 duplication in your logs.
726 Here's a sample Log4perl configuration file that produces the
728 phenomenon:
729 log4perl.logger.Cat = ERROR, Screen
731 log4perl.logger.Cat.Subcat = WARN, Screen
732 log4perl.appender.Screen = Log::Log4perl::Appender::Screen
734 log4perl.appender.Screen.layout = SimpleLayout
735 It defines two loggers, one for category "Cat" and one for
737 "Cat::Subcat", which is obviously a subcategory of "Cat". The parent
738 logger has a priority setting of ERROR, the child is set to the lower
739 "WARN" level.
740 Now imagine the following code in your program:
742 my $logger = get_logger("Cat.Subcat");
744 $logger->warn("Warning!");
745 What do you think will happen? An unexperienced Log4perl user might
747 think: "Well, the message is being sent with level WARN, so the
748 "Cat::Subcat" logger will accept it and forward it to the attached
749 "Screen" appender. Then, the message will percolate up the logger
750 hierarchy, find the "Cat" logger, which will suppress the message
751 because of its ERROR setting." But, perhaps surprisingly, what you'll
752 get with the code snippet above is not one but two log messages written
753 to the screen:
754 WARN - Warning!
756 WARN - Warning!
757 What happened? The culprit is that once the logger "Cat::Subcat"
759 decides to fire, it will forward the message unconditionally to all
760 directly or indirectly attached appenders. The "Cat" logger will never
761 be asked if it wants the message or not -- the message will just be
762 pushed through to the appender attached to "Cat".
763 One way to prevent the message from bubbling up the logger hierarchy is
765 to set the "additivity" flag of the subordinate logger to 0:
766 log4perl.logger.Cat = ERROR, Screen
768 log4perl.logger.Cat.Subcat = WARN, Screen
769 log4perl.additivity.Cat.Subcat = 0
770 log4perl.appender.Screen = Log::Log4perl::Appender::Screen
772 log4perl.appender.Screen.layout = SimpleLayout
773 The message will now be accepted by the "Cat::Subcat" logger, forwarded
775 to its appender, but then "Cat::Subcat" will suppress any further
776 action. While this setting avoids duplicate messages as seen before, it
777 is often not the desired behaviour. Messages percolating up the
778 hierarchy are a useful Log4perl feature.
779 If you're defining different appenders for the two loggers, one other
781 option is to define an appender threshold for the higher-level
782 appender. Typically it is set to be equal to the logger's level
783 setting:
784 log4perl.logger.Cat = ERROR, Screen1
786 log4perl.logger.Cat.Subcat = WARN, Screen2
787 log4perl.appender.Screen1 = Log::Log4perl::Appender::Screen
789 log4perl.appender.Screen1.layout = SimpleLayout
790 log4perl.appender.Screen1.Threshold = ERROR
791 log4perl.appender.Screen2 = Log::Log4perl::Appender::Screen
793 log4perl.appender.Screen2.layout = SimpleLayout
794 Since the "Screen1" appender now blocks every message with a priority
796 less than ERROR, even if the logger in charge lets it through, the
797 message percolating up the hierarchy is being blocked at the last
798 minute and not appended to "Screen1".
799 So far, we've been operating well within the boundaries of the Log4j
801 standard, which Log4perl adheres to. However, if you would really,
802 really like to use a single appender and keep the message percolation
803 intact without having to deal with message duplication, there's a non-
804 standard solution for you:
805 log4perl.logger.Cat = ERROR, Screen
807 log4perl.logger.Cat.Subcat = WARN, Screen
808 log4perl.appender.Screen = Log::Log4perl::Appender::Screen
810 log4perl.appender.Screen.layout = SimpleLayout
811 log4perl.oneMessagePerAppender = 1
813 The "oneMessagePerAppender" flag will suppress duplicate messages to
815 the same appender. Again, that's non-standard. But way cool :).
816 How can I configure Log::Log4perl to send me email if something happens?
818 Some incidents require immediate action. You can't wait until someone
819 checks the log files, you need to get notified on your pager right
820 away.
821 The easiest way to do that is by using the
823 "Log::Dispatch::Email::MailSend" module as an appender. It comes with
824 the "Log::Dispatch" bundle and allows you to specify recipient and
825 subject of outgoing emails in the Log4perl configuration file:
826 log4perl.category = FATAL, Mailer
828 log4perl.appender.Mailer = Log::Dispatch::Email::MailSend
829 log4perl.appender.Mailer.to = drone@pageme.net
830 log4perl.appender.Mailer.subject = Something's broken!
831 log4perl.appender.Mailer.layout = SimpleLayout
832 The message of every log incident this appender gets will then be
834 forwarded to the given email address. Check the
835 "Log::Dispatch::Email::MailSend" documentation for details. And please
836 make sure there's not a flood of email messages sent out by your
837 application, filling up the receipient's inbox.
838 There's one caveat you need to know about: The "Log::Dispatch::Email"
840 hierarchy of appenders turns on buffering by default. This means that
841 the appender will not send out messages right away but wait until a
842 certain threshold has been reached. If you'd rather have your alerts
843 sent out immeditately, use
844 log4perl.appender.Mailer.buffered = 0
846 to turn buffering off.
848 How can I write my own appender?
850 First off, Log::Log4perl comes with a set of standard appenders. Then,
851 there's a lot of Log4perl-compatible appenders already available on
852 CPAN: Just run a search for "Log::Dispatch" on http://search.cpan.org
853 and chances are that what you're looking for has already been
854 developed, debugged and been used successfully in production -- no need
855 for you to reinvent the wheel.
856 Also, Log::Log4perl ships with a nifty database appender named
858 Log::Log4perl::Appender::DBI -- check it out if talking to databases is
859 your desire.
860 But if you're up for a truly exotic task, you might have to write an
862 appender yourself. That's very easy -- it takes no longer than a couple
863 of minutes.
864 Say, we wanted to create an appender of the class
866 "ColorScreenAppender", which logs messages to the screen in a
867 configurable color. Just create a new class in
868 "ColorScreenAppender.pm":
869 package ColorScreenAppender;
871 Now let's assume that your Log::Log4perl configuration file "test.conf"
873 looks like this:
874 log4perl.logger = INFO, ColorApp
876 log4perl.appender.ColorApp=ColorScreenAppender
878 log4perl.appender.ColorApp.color=blue
879 log4perl.appender.ColorApp.layout = PatternLayout
881 log4perl.appender.ColorApp.layout.ConversionPattern=%d %m %n
882 This will cause Log::Log4perl on "init()" to look for a class
884 ColorScreenAppender and call its constructor new(). Let's add new() to
885 ColorScreenAppender.pm:
886 sub new {
888 my($class, %options) = @_;
889 my $self = { %options };
891 bless $self, $class;
892 return $self;
894 }
895 To initialize this appender, Log::Log4perl will call and pass all
897 attributes of the appender as defined in the configuration file to the
898 constructor as name/value pairs (in this case just one):
899 ColorScreenAppender->new(color => "blue");
901 The new() method listed above stores the contents of the %options hash
903 in the object's instance data hash (referred to by $self). That's all
904 for initializing a new appender with Log::Log4perl.
905 Second, ColorScreenAppender needs to expose a "log()" method, which
907 will be called by Log::Log4perl every time it thinks the appender
908 should fire. Along with the object reference (as usual in Perl's object
909 world), log() will receive a list of name/value pairs, of which only
910 the one under the key "message" shall be of interest for now since it
911 is the message string to be logged. At this point, Log::Log4perl has
912 already taken care of joining the message to be a single string.
913 For our special appender ColorScreenAppender, we're using the
915 Term::ANSIColor module to colorize the output:
916 use Term::ANSIColor;
918 sub log {
920 my($self, %params) = @_;
921 print colored($params{message},
923 $self->{color});
924 }
925 The color (as configured in the Log::Log4perl configuration file) is
927 available as $self->{color} in the appender object. Don't forget to
928 return
929 1;
931 at the end of ColorScreenAppender.pm and you're done. Install the new
933 appender somewhere where perl can find it and try it with a test script
934 like
935 use Log::Log4perl qw(:easy);
937 Log::Log4perl->init("test.conf");
938 ERROR("blah");
939 to see the new colored output. Is this cool or what?
941 And it gets even better: You can write dynamically generated appender
943 classes using the "Class::Prototyped" module. Here's an example of an
944 appender prepending every outgoing message with a configurable number
945 of bullets:
946 use Class::Prototyped;
948 my $class = Class::Prototyped->newPackage(
950 "MyAppenders::Bulletizer",
951 bullets => 1,
952 log => sub {
953 my($self, %params) = @_;
954 print "*" x $self->bullets(),
955 $params{message};
956 },
957 );
958 use Log::Log4perl qw(:easy);
960 Log::Log4perl->init(\ q{
962 log4perl.logger = INFO, Bully
963 log4perl.appender.Bully=MyAppenders::Bulletizer
965 log4perl.appender.Bully.bullets=3
966 log4perl.appender.Bully.layout = PatternLayout
968 log4perl.appender.Bully.layout.ConversionPattern=%m %n
969 });
970 # ... prints: "***Boo!\n";
972 INFO "Boo!";
973 How can I drill down on references before logging them?
975 If you've got a reference to a nested structure or object, then you
976 probably don't want to log it as "HASH(0x81141d4)" but rather dump it
977 as something like
978 $VAR1 = {
980 'a' => 'b',
981 'd' => 'e'
982 };
983 via a module like Data::Dumper. While it's syntactically correct to say
985 $logger->debug(Data::Dumper::Dumper($ref));
987 this call imposes a huge performance penalty on your application if the
989 message is suppressed by Log::Log4perl, because Data::Dumper will
990 perform its expensive operations in any case, because it doesn't know
991 that its output will be thrown away immediately.
992 As of Log::Log4perl 0.28, there's a better way: Use the message output
994 filter format as in
995 $logger->debug( {filter => \&Data::Dumper::Dumper,
997 value => $ref} );
998 and Log::Log4perl won't call the filter function unless the message
1000 really gets written out to an appender. Just make sure to pass the
1001 whole slew as a reference to a hash specifying a filter function (as a
1002 sub reference) under the key "filter" and the value to be passed to the
1003 filter function in "value"). When it comes to logging, Log::Log4perl
1004 will call the filter function, pass the "value" as an argument and log
1005 the return value. Saves you serious cycles.
1006 How can I collect all FATAL messages in an extra log file?
1008 Suppose you have employed Log4perl all over your system and you've
1009 already activated logging in various subsystems. On top of that,
1010 without disrupting any other settings, how can you collect all FATAL
1011 messages all over the system and send them to a separate log file?
1012 If you define a root logger like this:
1014 log4perl.logger = FATAL, File
1016 log4perl.appender.File = Log::Log4perl::Appender::File
1017 log4perl.appender.File.filename = /tmp/fatal.txt
1018 log4perl.appender.File.layout = PatternLayout
1019 log4perl.appender.File.layout.ConversionPattern= %d %m %n
1020 # !!! Something's missing ...
1021 you'll be surprised to not only receive all FATAL messages issued
1023 anywhere in the system, but also everything else -- gazillions of
1024 ERROR, WARN, INFO and even DEBUG messages will end up in your fatal.txt
1025 logfile! Reason for this is Log4perl's (or better: Log4j's) appender
1026 additivity. Once a lower-level logger decides to fire, the message is
1027 going to be forwarded to all appenders upstream -- without further
1028 priority checks with their attached loggers.
1029 There's a way to prevent this, however: If your appender defines a
1031 minimum threshold, only messages of this priority or higher are going
1032 to be logged. So, just add
1033 log4perl.appender.File.Threshold = FATAL
1035 to the configuration above, and you'll get what you wanted in the first
1037 place: An overall system FATAL message collector.
1038 How can I bundle several log messages into one?
1040 Would you like to tally the messages arriving at your appender and dump
1041 out a summary once they're exceeding a certain threshold? So that
1042 something like
1043 $logger->error("Blah");
1045 $logger->error("Blah");
1046 $logger->error("Blah");
1047 won't be logged as
1049 Blah
1051 Blah
1052 Blah
1053 but as
1055 [3] Blah
1057 instead? If you'd like to hold off on logging a message until it has
1059 been sent a couple of times, you can roll that out by creating a
1060 buffered appender.
1061 Let's define a new appender like
1063 package TallyAppender;
1065 sub new {
1067 my($class, %options) = @_;
1068 my $self = { maxcount => 5,
1070 %options
1071 };
1072 bless $self, $class;
1074 $self->{last_message} = "";
1076 $self->{last_message_count} = 0;
1077 return $self;
1079 }
1080 with two additional instance variables "last_message" and
1082 "last_message_count", storing the content of the last message sent and
1083 a counter of how many times this has happened. Also, it features a
1084 configuration parameter "maxcount" which defaults to 5 in the snippet
1085 above but can be set in the Log4perl configuration file like this:
1086 log4perl.logger = INFO, A
1088 log4perl.appender.A=TallyAppender
1089 log4perl.appender.A.maxcount = 3
1090 The main tallying logic lies in the appender's "log" method, which is
1092 called every time Log4perl thinks a message needs to get logged by our
1093 appender:
1094 sub log {
1096 my($self, %params) = @_;
1097 # Message changed? Print buffer.
1099 if($self->{last_message} and
1100 $params{message} ne $self->{last_message}) {
1101 print "[$self->{last_message_count}]: " .
1102 "$self->{last_message}";
1103 $self->{last_message_count} = 1;
1104 $self->{last_message} = $params{message};
1105 return;
1106 }
1107 $self->{last_message_count}++;
1109 $self->{last_message} = $params{message};
1110 # Threshold exceeded? Print, reset counter
1112 if($self->{last_message_count} >=
1113 $self->{maxcount}) {
1114 print "[$self->{last_message_count}]: " .
1115 "$params{message}";
1116 $self->{last_message_count} = 0;
1117 $self->{last_message} = "";
1118 return;
1119 }
1120 }
1121 We basically just check if the oncoming message in $param{message} is
1123 equal to what we've saved before in the "last_message" instance
1124 variable. If so, we're increasing "last_message_count". We print the
1125 message in two cases: If the new message is different than the buffered
1126 one, because then we need to dump the old stuff and store the new. Or,
1127 if the counter exceeds the threshold, as defined by the "maxcount"
1128 configuration parameter.
1129 Please note that the appender always gets the fully rendered message
1131 and just compares it as a whole -- so if there's a date/timestamp in
1132 there, that might confuse your logic. You can work around this by
1133 specifying %m %n as a layout and add the date later on in the appender.
1134 Or, make the comparison smart enough to omit the date.
1135 At last, don't forget what happens if the program is being shut down.
1137 If there's still messages in the buffer, they should be printed out at
1138 that point. That's easy to do in the appender's DESTROY method, which
1139 gets called at object destruction time:
1140 sub DESTROY {
1142 my($self) = @_;
1143 if($self->{last_message_count}) {
1145 print "[$self->{last_message_count}]: " .
1146 "$self->{last_message}";
1147 return;
1148 }
1149 }
1150 This will ensure that none of the buffered messages are lost. Happy
1152 buffering!
1153 I want to log ERROR and WARN messages to different files! How can I do
1155 that?
1156 Let's assume you wanted to have each logging statement written to a
1157 different file, based on the statement's priority. Messages with
1158 priority "WARN" are supposed to go to "/tmp/app.warn", events
1159 prioritized as "ERROR" should end up in "/tmp/app.error".
1160 Now, if you define two appenders "AppWarn" and "AppError" and assign
1162 them both to the root logger, messages bubbling up from any loggers
1163 below will be logged by both appenders because of Log4perl's message
1164 propagation feature. If you limit their exposure via the appender
1165 threshold mechanism and set "AppWarn"'s threshold to "WARN" and
1166 "AppError"'s to "ERROR", you'll still get "ERROR" messages in
1167 "AppWarn", because "AppWarn"'s "WARN" setting will just filter out
1168 messages with a lower priority than "WARN" -- "ERROR" is higher and
1169 will be allowed to pass through.
1170 What we need for this is a Log4perl Custom Filter, available with
1172 Log::Log4perl 0.30.
1173 Both appenders need to verify that the priority of the oncoming
1175 messages exactly matches the priority the appender is supposed to log
1176 messages of. To accomplish this task, let's define two custom filters,
1177 "MatchError" and "MatchWarn", which, when attached to their appenders,
1178 will limit messages passed on to them to those matching a given
1179 priority:
1180 log4perl.logger = WARN, AppWarn, AppError
1182 # Filter to match level ERROR
1184 log4perl.filter.MatchError = Log::Log4perl::Filter::LevelMatch
1185 log4perl.filter.MatchError.LevelToMatch = ERROR
1186 log4perl.filter.MatchError.AcceptOnMatch = true
1187 # Filter to match level WARN
1189 log4perl.filter.MatchWarn = Log::Log4perl::Filter::LevelMatch
1190 log4perl.filter.MatchWarn.LevelToMatch = WARN
1191 log4perl.filter.MatchWarn.AcceptOnMatch = true
1192 # Error appender
1194 log4perl.appender.AppError = Log::Log4perl::Appender::File
1195 log4perl.appender.AppError.filename = /tmp/app.err
1196 log4perl.appender.AppError.layout = SimpleLayout
1197 log4perl.appender.AppError.Filter = MatchError
1198 # Warning appender
1200 log4perl.appender.AppWarn = Log::Log4perl::Appender::File
1201 log4perl.appender.AppWarn.filename = /tmp/app.warn
1202 log4perl.appender.AppWarn.layout = SimpleLayout
1203 log4perl.appender.AppWarn.Filter = MatchWarn
1204 The appenders "AppWarn" and "AppError" defined above are logging to
1206 "/tmp/app.warn" and "/tmp/app.err" respectively and have the custom
1207 filters "MatchWarn" and "MatchError" attached. This setup will direct
1208 all WARN messages, issued anywhere in the system, to /tmp/app.warn (and
1209 ERROR messages to /tmp/app.error) -- without any overlaps.
1210 On our server farm, Log::Log4perl configuration files differ slightly from
1212 host to host. Can I roll them all into one?
1213 You sure can, because Log::Log4perl allows you to specify attribute
1214 values dynamically. Let's say that one of your appenders expects the
1215 host's IP address as one of its attributes. Now, you could certainly
1216 roll out different configuration files for every host and specify the
1217 value like
1218 log4perl.appender.MyAppender = Log::Log4perl::Appender::SomeAppender
1220 log4perl.appender.MyAppender.ip = 10.0.0.127
1221 but that's a maintenance nightmare. Instead, you can have Log::Log4perl
1223 figure out the IP address at configuration time and set the appender's
1224 value correctly:
1225 # Set the IP address dynamically
1227 log4perl.appender.MyAppender = Log::Log4perl::Appender::SomeAppender
1228 log4perl.appender.MyAppender.ip = sub { \
1229 use Sys::Hostname; \
1230 use Socket; \
1231 return inet_ntoa(scalar gethostbyname hostname); \
1232 }
1233 If Log::Log4perl detects that an attribute value starts with something
1235 like "sub {...", it will interpret it as a perl subroutine which is to
1236 be executed once at configuration time (not runtime!) and its return
1237 value is to be used as the attribute value. This comes in handy for
1238 rolling out applications whichs Log::Log4perl configuration files show
1239 small host-specific differences, because you can deploy the unmodified
1240 application distribution on all instances of the server farm.
1241 Log4perl doesn't interpret my backslashes correctly!
1243 If you're using Log4perl's feature to specify the configuration as a
1244 string in your program (as opposed to a separate configuration file),
1245 chances are that you've written it like this:
1246 # *** WRONG! ***
1248 Log::Log4perl->init( \ <<END_HERE);
1250 log4perl.logger = WARN, A1
1251 log4perl.appender.A1 = Log::Log4perl::Appender::Screen
1252 log4perl.appender.A1.layout = \
1253 Log::Log4perl::Layout::PatternLayout
1254 log4perl.appender.A1.layout.ConversionPattern = %m%n
1255 END_HERE
1256 # *** WRONG! ***
1258 and you're getting the following error message:
1260 Layout not specified for appender A1 at .../Config.pm line 342.
1262 What's wrong? The problem is that you're using a here-document with
1264 substitution enabled ("<<END_HERE") and that Perl won't interpret
1265 backslashes at line-ends as continuation characters but will
1266 essentially throw them out. So, in the code above, the layout line will
1267 look like
1268 log4perl.appender.A1.layout =
1270 to Log::Log4perl which causes it to report an error. To interpret the
1272 backslash at the end of the line correctly as a line-continuation
1273 character, use the non-interpreting mode of the here-document like in
1274 # *** RIGHT! ***
1276 Log::Log4perl->init( \ <<'END_HERE');
1278 log4perl.logger = WARN, A1
1279 log4perl.appender.A1 = Log::Log4perl::Appender::Screen
1280 log4perl.appender.A1.layout = \
1281 Log::Log4perl::Layout::PatternLayout
1282 log4perl.appender.A1.layout.ConversionPattern = %m%n
1283 END_HERE
1284 # *** RIGHT! ***
1286 (note the single quotes around 'END_HERE') or use "q{...}" instead of a
1288 here-document and Perl will treat the backslashes at line-end as
1289 intended.
1290 I want to suppress certain messages based on their content!
1292 Let's assume you've plastered all your functions with Log4perl
1293 statements like
1294 sub some_func {
1296 INFO("Begin of function");
1298 # ... Stuff happens here ...
1300 INFO("End of function");
1302 }
1303 to issue two log messages, one at the beginning and one at the end of
1305 each function. Now you want to suppress the message at the beginning
1306 and only keep the one at the end, what can you do? You can't use the
1307 category mechanism, because both messages are issued from the same
1308 package.
1309 Log::Log4perl's custom filters (0.30 or better) provide an interface
1311 for the Log4perl user to step in right before a message gets logged and
1312 decide if it should be written out or suppressed, based on the message
1313 content or other parameters:
1314 use Log::Log4perl qw(:easy);
1316 Log::Log4perl::init( \ <<'EOT' );
1318 log4perl.logger = INFO, A1
1319 log4perl.appender.A1 = Log::Log4perl::Appender::Screen
1320 log4perl.appender.A1.layout = \
1321 Log::Log4perl::Layout::PatternLayout
1322 log4perl.appender.A1.layout.ConversionPattern = %m%n
1323 log4perl.filter.M1 = Log::Log4perl::Filter::StringMatch
1325 log4perl.filter.M1.StringToMatch = Begin
1326 log4perl.filter.M1.AcceptOnMatch = false
1327 log4perl.appender.A1.Filter = M1
1329 EOT
1330 The last four statements in the configuration above are defining a
1332 custom filter "M1" of type "Log::Log4perl::Filter::StringMatch", which
1333 comes with Log4perl right out of the box and allows you to define a
1334 text pattern to match (as a perl regular expression) and a flag
1335 "AcceptOnMatch" indicating if a match is supposed to suppress the
1336 message or let it pass through.
1337 The last line then assigns this filter to the "A1" appender, which will
1339 call it every time it receives a message to be logged and throw all
1340 messages out not matching the regular expression "Begin".
1341 Instead of using the standard "Log::Log4perl::Filter::StringMatch"
1343 filter, you can define your own, simply using a perl subroutine:
1344 log4perl.filter.ExcludeBegin = sub { !/Begin/ }
1346 log4perl.appender.A1.Filter = ExcludeBegin
1347 For details on custom filters, check Log::Log4perl::Filter.
1349 My new module uses Log4perl -- but what happens if the calling program
1351 didn't configure it?
1352 If a Perl module uses Log::Log4perl, it will typically rely on the
1353 calling program to initialize it. If it is using Log::Log4perl in
1354 ":easy" mode, like in
1355 package MyMod;
1357 use Log::Log4perl qw(:easy);
1358 sub foo {
1360 DEBUG("In foo");
1361 }
1362 1;
1364 and the calling program doesn't initialize Log::Log4perl at all (e.g.
1366 because it has no clue that it's available), Log::Log4perl will
1367 silently ignore all logging messages. However, if the module is using
1368 Log::Log4perl in regular mode like in
1369 package MyMod;
1371 use Log::Log4perl qw(get_logger);
1372 sub foo {
1374 my $logger = get_logger("");
1375 $logger->debug("blah");
1376 }
1377 1;
1379 and the main program is just using the module like in
1381 use MyMode;
1383 MyMode::foo();
1384 then Log::Log4perl will also ignore all logging messages but issue a
1386 warning like
1387 Log4perl: Seems like no initialization happened.
1389 Forgot to call init()?
1390 (only once!) to remind novice users to not forget to initialize the
1392 logging system before using it. However, if you want to suppress this
1393 message, just add the ":nowarn" target to the module's "use
1394 Log::Log4perl" call:
1395 use Log::Log4perl qw(get_logger :nowarn);
1397 This will have Log::Log4perl silently ignore all logging statements if
1399 no initialization has taken place. If, instead of using init(), you're
1400 using Log4perl's API to define loggers and appenders, the same
1401 notification happens if no call to add_appenders() is made, i.e. no
1402 appenders are defined.
1403 If the module wants to figure out if some other program part has
1405 already initialized Log::Log4perl, it can do so by calling
1406 Log::Log4perl::initialized()
1408 which will return a true value in case Log::Log4perl has been
1410 initialized and a false value if not.
1411 How can I synchronize access to an appender?
1413 If you're using the same instance of an appender in multiple processes,
1414 and each process is passing on messages to the appender in parallel,
1415 you might end up with overlapping log entries.
1416 Typical scenarios include a file appender that you create in the main
1418 program, and which will then be shared between the parent and a forked
1419 child process. Or two separate processes, each initializing a Log4perl
1420 file appender on the same logfile.
1421 Log::Log4perl won't synchronize access to the shared logfile by
1423 default. Depending on your operating system's flush mechanism, buffer
1424 size and the size of your messages, there's a small chance of an
1425 overlap.
1426 The easiest way to prevent overlapping messages in logfiles written to
1428 by multiple processes is setting the file appender's "syswrite" flag
1429 along with a file write mode of "append". This makes sure that
1430 "Log::Log4perl::Appender::File" uses "syswrite()" (which is guaranteed
1431 to run uninterrupted) instead of "print()" which might buffer the
1432 message or get interrupted by the OS while it is writing. And in
1433 "append" mode, the OS kernel ensures that multiple processes share one
1434 end-of-file marker, ensuring that each process writes to the real end
1435 of the file. (The value of "append" for the "mode" parameter is the
1436 default setting in Log4perl's file appender so you don't have to set it
1437 explicitely.)
1438 # Guarantees atomic writes
1440 log4perl.category.Bar.Twix = WARN, Logfile
1442 log4perl.appender.Logfile = Log::Log4perl::Appender::File
1444 log4perl.appender.Logfile.mode = append
1445 log4perl.appender.Logfile.syswrite = 1
1446 log4perl.appender.Logfile.filename = test.log
1447 log4perl.appender.Logfile.layout = SimpleLayout
1448 Another guaranteed way of having messages separated with any kind of
1450 appender is putting a Log::Log4perl::Appender::Synchronized composite
1451 appender in between Log::Log4perl and the real appender. It will make
1452 sure to let messages pass through this virtual gate one by one only.
1453 Here's a sample configuration to synchronize access to a file appender:
1455 log4perl.category.Bar.Twix = WARN, Syncer
1457 log4perl.appender.Logfile = Log::Log4perl::Appender::File
1459 log4perl.appender.Logfile.autoflush = 1
1460 log4perl.appender.Logfile.filename = test.log
1461 log4perl.appender.Logfile.layout = SimpleLayout
1462 log4perl.appender.Syncer = Log::Log4perl::Appender::Synchronized
1464 log4perl.appender.Syncer.appender = Logfile
1465 "Log::Log4perl::Appender::Synchronized" uses the "IPC::Shareable"
1467 module and its semaphores, which will slow down writing the log
1468 messages, but ensures sequential access featuring atomic checks. Check
1469 Log::Log4perl::Appender::Synchronized for details.
1470 Can I use Log::Log4perl with log4j's Chainsaw?
1472 Yes, Log::Log4perl can be configured to send its events to log4j's
1473 graphical log UI Chainsaw.
1474 Here's how it works:
1476 · Get Guido Carls' <gcarls@cpan.org> Log::Log4perl extension
1478 "Log::Log4perl::Layout::XMLLayout" from CPAN and install it:
1479 perl -MCPAN -eshell
1481 cpan> install Log::Log4perl::Layout::XMLLayout
1482 · Install and start Chainsaw, which is part of the "log4j"
1484 distribution now (see http://jakarta.apache.org/log4j ). Create a
1485 configuration file like
1486 <log4j:configuration debug="true">
1488 <plugin name="XMLSocketReceiver"
1489 class="org.apache.log4j.net.XMLSocketReceiver">
1490 <param name="decoder" value="org.apache.log4j.xml.XMLDecoder"/>
1491 <param name="Port" value="4445"/>
1492 </plugin>
1493 <root> <level value="debug"/> </root>
1494 </log4j:configuration>
1495 and name it e.g. "config.xml". Then start Chainsaw like
1497 java -Dlog4j.debug=true -Dlog4j.configuration=config.xml \
1499 -classpath ".:log4j-1.3alpha.jar:log4j-chainsaw-1.3alpha.jar" \
1500 org.apache.log4j.chainsaw.LogUI
1501 and watch the GUI coming up.
1503 · Configure Log::Log4perl to use a socket appender with an XMLLayout,
1505 pointing to the host/port where Chainsaw (as configured above) is
1506 waiting with its XMLSocketReceiver:
1507 use Log::Log4perl qw(get_logger);
1509 use Log::Log4perl::Layout::XMLLayout;
1510 my $conf = q(
1512 log4perl.category.Bar.Twix = WARN, Appender
1513 log4perl.appender.Appender = Log::Log4perl::Appender::Socket
1514 log4perl.appender.Appender.PeerAddr = localhost
1515 log4perl.appender.Appender.PeerPort = 4445
1516 log4perl.appender.Appender.layout = Log::Log4perl::Layout::XMLLayout
1517 );
1518 Log::Log4perl::init(\$conf);
1520 # Nasty hack to suppress encoding header
1522 my $app = Log::Log4perl::appenders->{"Appender"};
1523 $app->layout()->{enc_set} = 1;
1524 my $logger = get_logger("Bar.Twix");
1526 $logger->error("One");
1527 The nasty hack shown in the code snippet above is currently
1529 (October 2003) necessary, because Chainsaw expects XML messages to
1530 arrive in a format like
1531 <log4j:event logger="Bar.Twix"
1533 timestamp="1066794904310"
1534 level="ERROR"
1535 thread="10567">
1536 <log4j:message><![CDATA[Two]]></log4j:message>
1537 <log4j:NDC><![CDATA[undef]]></log4j:NDC>
1538 <log4j:locationInfo class="main"
1539 method="main"
1540 file="./t"
1541 line="32">
1542 </log4j:locationInfo>
1543 </log4j:event>
1544 without a preceding
1546 <?xml version = "1.0" encoding = "iso8859-1"?>
1548 which Log::Log4perl::Layout::XMLLayout applies to the first event
1550 sent over the socket.
1551 See figure 1 for a screenshot of Chainsaw in action, receiving events
1553 from the Perl script shown above.
1554 Many thanks to Chainsaw's Scott Deboy <sdeboy@comotivsystems.com> for
1556 his support!
1557 How can I run Log::Log4perl under mod_perl?
1559 In persistent environments it's important to play by the rules outlined
1560 in section "Initialize once and only once" in Log::Log4perl. If you
1561 haven't read this yet, please go ahead and read it right now. It's very
1562 important.
1563 And no matter if you use a startup handler to init() Log::Log4perl or
1565 use the init_once() strategy (added in 0.42), either way you're very
1566 likely to have unsynchronized writes to logfiles.
1567 If Log::Log4perl is configured with a log file appender, and it is
1569 initialized via the Apache startup handler, the file handle created
1570 initially will be shared among all Apache processes. Similarly, with
1571 the init_once() approach: although every process has a separate L4p
1572 configuration, processes are gonna share the appender file names
1573 instead, effectively opening several different file handles on the same
1574 file.
1575 Now, having several appenders using the same file handle or having
1577 several appenders logging to the same file unsynchronized, this might
1578 result in overlapping messages. Sometimes, this is acceptable. If it's
1579 not, here's two strategies:
1580 · Use the Log::Log4perl::Appender::Synchronized appender to connect
1582 to your file appenders. Here's the writeup:
1583 http://log4perl.sourceforge.net/releases/Log-Log4perl/docs/html/Log/Log4perl/FAQ.html#23804
1584 · Use a different logfile for every process like in
1586 #log4perl.conf
1588 ...
1589 log4perl.appender.A1.filename = sub { "mylog.$$.log" }
1590 My program already uses warn() and die(). How can I switch to Log4perl?
1592 If your program already uses Perl's "warn()" function to spew out error
1593 messages and you'd like to channel those into the Log4perl world, just
1594 define a "__WARN__" handler where your program or module resides:
1595 use Log::Log4perl qw(:easy);
1597 $SIG{__WARN__} = sub {
1599 local $Log::Log4perl::caller_depth =
1600 $Log::Log4perl::caller_depth + 1;
1601 WARN @_;
1602 };
1603 Why the "local" setting of $Log::Log4perl::caller_depth? If you leave
1605 that out, "PatternLayout" conversion specifiers like %M or %F (printing
1606 the current function/method and source filename) will refer to where
1607 the __WARN__ handler resides, not the environment Perl's "warn()"
1608 function was issued from. Increasing "caller_depth" adjusts for this
1609 offset. Having it "local", makes sure the level gets set back after the
1610 handler exits.
1611 Once done, if your program does something like
1613 sub some_func {
1615 warn "Here's a warning";
1616 }
1617 you'll get (depending on your Log::Log4perl configuration) something
1619 like
1620 2004/02/19 20:41:02-main::some_func: Here's a warning at ./t line 25.
1622 in the appropriate appender instead of having a screen full of STDERR
1624 messages. It also works with the "Carp" module and its "carp()" and
1625 "cluck()" functions.
1626 If, on the other hand, catching "die()" and friends is required, a
1628 "__DIE__" handler is appropriate:
1629 $SIG{__DIE__} = sub {
1631 if($^S) {
1632 # We're in an eval {} and don't want log
1633 # this message but catch it later
1634 return;
1635 }
1636 local $Log::Log4perl::caller_depth =
1637 $Log::Log4perl::caller_depth + 1;
1638 LOGDIE @_;
1639 };
1640 This will call Log4perl's "LOGDIE()" function, which will log a fatal
1642 error and then call die() internally, causing the program to exit.
1643 Works equally well with "Carp"'s "croak()" and "confess()" functions.
1644 Some module prints messages to STDERR. How can I funnel them to
1646 Log::Log4perl?
1647 If a module you're using doesn't use Log::Log4perl but prints logging
1648 messages to STDERR instead, like
1649 ########################################
1651 package IgnorantModule;
1652 ########################################
1653 sub some_method {
1655 print STDERR "Parbleu! An error!\n";
1656 }
1657 1;
1659 there's still a way to capture these messages and funnel them into
1661 Log::Log4perl, even without touching the module. What you need is a
1662 trapper module like
1663 ########################################
1665 package Trapper;
1666 ########################################
1667 use Log::Log4perl qw(:easy);
1669 sub TIEHANDLE {
1671 my $class = shift;
1672 bless [], $class;
1673 }
1674 sub PRINT {
1676 my $self = shift;
1677 $Log::Log4perl::caller_depth++;
1678 DEBUG @_;
1679 $Log::Log4perl::caller_depth--;
1680 }
1681 1;
1683 and a "tie" command in the main program to tie STDERR to the trapper
1685 module along with regular Log::Log4perl initialization:
1686 ########################################
1688 package main;
1689 ########################################
1690 use Log::Log4perl qw(:easy);
1692 Log::Log4perl->easy_init(
1694 {level => $DEBUG,
1695 file => 'stdout', # make sure not to use stderr here!
1696 layout => "%d %M: %m%n",
1697 });
1698 tie *STDERR, "Trapper";
1700 Make sure not to use STDERR as Log::Log4perl's file appender here
1702 (which would be the default in ":easy" mode), because it would end up
1703 in an endless recursion.
1704 Now, calling
1706 IgnorantModule::some_method();
1708 will result in the desired output
1710 2004/05/06 11:13:04 IgnorantModule::some_method: Parbleu! An error!
1712 How come PAR (Perl Archive Toolkit) creates executables which then can't
1714 find their Log::Log4perl appenders?
1715 If not instructed otherwise, "Log::Log4perl" dynamically pulls in
1716 appender classes found in its configuration. If you specify
1717 #!/usr/bin/perl
1719 # mytest.pl
1720 use Log::Log4perl qw(get_logger);
1722 my $conf = q(
1724 log4perl.category.Bar.Twix = WARN, Logfile
1725 log4perl.appender.Logfile = Log::Log4perl::Appender::Screen
1726 log4perl.appender.Logfile.layout = SimpleLayout
1727 );
1728 Log::Log4perl::init(\$conf);
1730 my $logger = get_logger("Bar::Twix");
1731 $logger->error("Blah");
1732 then "Log::Log4perl::Appender::Screen" will be pulled in while the
1734 program runs, not at compile time. If you have PAR compile the script
1735 above to an executable binary via
1736 pp -o mytest mytest.pl
1738 and then run "mytest" on a machine without having Log::Log4perl
1740 installed, you'll get an error message like
1741 ERROR: can't load appenderclass 'Log::Log4perl::Appender::Screen'
1743 Can't locate Log/Log4perl/Appender/Screen.pm in @INC ...
1744 Why? At compile time, "pp" didn't realize that
1746 "Log::Log4perl::Appender::Screen" would be needed later on and didn't
1747 wrap it into the executable created. To avoid this, either say "use
1748 Log::Log4perl::Appender::Screen" in the script explicitely or compile
1749 it with
1750 pp -o mytest -M Log::Log4perl::Appender::Screen mytest.pl
1752 to make sure the appender class gets included.
1754 How can I access a custom appender defined in the configuration?
1756 Any appender defined in the configuration file or somewhere in the code
1757 can be accessed later via
1758 "Log::Log4perl->appender_by_name("appender_name")", which returns a
1759 reference the the appender object.
1760 Once you've got a hold of the object, it can be queried or modified to
1762 your liking. For example, see the custom "IndentAppender" defined
1763 below: After calling "init()" to define the Log4perl settings, the
1764 appender object is retrieved to call its "indent_more()" and
1765 "indent_less()" methods to control indentation of messages:
1766 package IndentAppender;
1768 sub new {
1770 bless { indent => 0 }, $_[0];
1771 }
1772 sub indent_more { $_[0]->{indent}++ }
1774 sub indent_less { $_[0]->{indent}-- }
1775 sub log {
1777 my($self, %params) = @_;
1778 print " " x $self->{indent}, $params{message};
1779 }
1780 package main;
1782 use Log::Log4perl qw(:easy);
1784 my $conf = q(
1786 log4perl.category = DEBUG, Indented
1787 log4perl.appender.Indented = IndentAppender
1788 log4perl.appender.Indented.layout = Log::Log4perl::Layout::SimpleLayout
1789 );
1790 Log::Log4perl::init(\$conf);
1792 my $appender = Log::Log4perl->appender_by_name("Indented");
1794 DEBUG "No identation";
1796 $appender->indent_more();
1797 DEBUG "One more";
1798 $appender->indent_more();
1799 DEBUG "Two more";
1800 $appender->indent_less();
1801 DEBUG "One less";
1802 As you would expect, this will print
1804 DEBUG - No identation
1806 DEBUG - One more
1807 DEBUG - Two more
1808 DEBUG - One less
1809 because the very appender used by Log4perl is modified dynamically at
1811 runtime.
1812 I don't know if Log::Log4perl is installed. How can I prepare my script?
1814 In case your script needs to be prepared for environments that may or
1815 may not have Log::Log4perl installed, there's a trick.
1816 If you put the following BEGIN blocks at the top of the program, you'll
1818 be able to use the DEBUG(), INFO(), etc. macros in Log::Log4perl's
1819 ":easy" mode. If Log::Log4perl is installed in the target environment,
1820 the regular Log::Log4perl rules apply. If not, all of DEBUG(), INFO(),
1821 etc. are "stubbed" out, i.e. they turn into no-ops:
1822 use warnings;
1824 use strict;
1825 BEGIN {
1827 eval { require Log::Log4perl; };
1828 if($@) {
1830 print "Log::Log4perl not installed - stubbing.\n";
1831 no strict qw(refs);
1832 *{"main::$_"} = sub { } for qw(DEBUG INFO WARN ERROR FATAL);
1833 } else {
1834 no warnings;
1835 print "Log::Log4perl installed - life is good.\n";
1836 require Log::Log4perl::Level;
1837 Log::Log4perl::Level->import(__PACKAGE__);
1838 Log::Log4perl->import(qw(:easy));
1839 Log::Log4perl->easy_init($main::DEBUG);
1840 }
1841 }
1842 # The regular script begins ...
1844 DEBUG "Hey now!";
1845 This snippet will first probe for Log::Log4perl, and if it can't be
1847 found, it will alias DEBUG(), INFO(), with empty subroutines via
1848 typeglobs. If Log::Log4perl is available, its level constants are
1849 first imported ($DEBUG, $INFO, etc.) and then "easy_init()" gets called
1850 to initialize the logging system.
1851 Can file appenders create files with different permissions?
1853 Typically, when "Log::Log4perl::Appender::File" creates a new file, its
1854 permissions are set to "rw-r--r--". Why? Because your environment's
1855 umask most likely defaults to 0022, that's the standard setting.
1856 What's a umask, you're asking? It's a template that's applied to the
1858 permissions of all newly created files. While calls like "open(FILE,
1859 ">foo")" will always try to create files in "rw-rw-rw- " mode, the
1860 system will apply the current umask template to determine the final
1861 permission setting. umask is a bit mask that's inverted and then
1862 applied to the requested permission setting, using a bitwise AND:
1863 $request_permission &~ $umask
1865 So, a umask setting of 0000 (the leading 0 simply indicates an octal
1867 value) will create files in "rw-rw-rw-" mode, a setting of 0277 will
1868 use "r--------", and the standard 0022 will use "rw-r--r--".
1869 As an example, if you want your log files to be created with
1871 "rw-r--rw-" permissions, use a umask of 0020 before calling
1872 Log::Log4perl->init():
1873 use Log::Log4perl;
1875 umask 0020;
1877 # Creates log.out in rw-r--rw mode
1878 Log::Log4perl->init(\ q{
1879 log4perl.logger = WARN, File
1880 log4perl.appender.File = Log::Log4perl::Appender::File
1881 log4perl.appender.File.filename = log.out
1882 log4perl.appender.File.layout = SimpleLayout
1883 });
1884 Using Log4perl in an END block causes a problem!
1886 It's not easy to get to this error, but if you write something like
1887 END { Log::Log4perl::get_logger()->debug("Hey there."); }
1889 use Log::Log4perl qw(:easy);
1891 Log::Log4perl->easy_init($DEBUG);
1892 it won't work. The reason is that "Log::Log4perl" defines an END block
1894 that cleans up all loggers. And perl will run END blocks in the reverse
1895 order as they're encountered in the compile phase, so in the scenario
1896 above, the END block will run after Log4perl has cleaned up its
1897 loggers.
1898 Placing END blocks using Log4perl after a "use Log::Log4perl" statement
1900 fixes the problem:
1901 use Log::Log4perl qw(:easy);
1903 Log::Log4perl->easy_init($DEBUG);
1904 END { Log::Log4perl::get_logger()->debug("Hey there."); }
1906 In this scenario, the shown END block is executed before Log4perl
1908 cleans up and the debug message will be processed properly.
1909 Help! My appender is throwing a "Wide character in print" warning!
1911 This warning shows up when Unicode strings are printed without
1912 precautions. The warning goes away if the complaining appender is set
1913 to utf-8 mode:
1914 # Either in the log4perl configuration file:
1916 log4perl.appender.Logfile.filename = test.log
1917 log4perl.appender.Logfile.utf8 = 1
1918 # Or, in easy mode:
1920 Log::Log4perl->easy_init( {
1921 level => $DEBUG,
1922 file => ":utf8> test.log"
1923 } );
1924 If the complaining appender is a screen appender, set its "utf8"
1926 option:
1927 log4perl.appender.Screen.stderr = 1
1929 log4perl.appender.Screen.utf8 = 1
1930 Alternatively, "binmode" does the trick:
1932 # Either STDOUT ...
1934 binmode(STDOUT, ":utf8);
1935 # ... or STDERR.
1937 binmode(STDERR, ":utf8);
1938 Some background on this: Perl's strings are either byte strings or
1940 Unicode strings. "Mike" is a byte string. "\x{30DE}\x{30A4}\x{30AF}"
1941 is a Unicode string. Unicode strings are marked specially and are UTF-8
1942 encoded internally.
1943 If you print a byte string to STDOUT, all is well, because STDOUT is by
1945 default set to byte mode. However, if you print a Unicode string to
1946 STDOUT without precautions, "perl" will try to transform the Unicode
1947 string back to a byte string before printing it out. This is
1948 troublesome if the Unicode string contains 'wide' characters which
1949 can't be represented in Latin-1.
1950 For example, if you create a Unicode string with three japanese
1952 Katakana characters as in
1953 perl -le 'print "\x{30DE}\x{30A4}\x{30AF}"'
1955 (coincidentally pronounced Ma-i-ku, the japanese pronounciation of
1957 "Mike"), STDOUT is in byte mode and the warning
1958 Wide character in print at ./script.pl line 14.
1960 appears. Setting STDOUT to UTF-8 mode as in
1962 perl -le 'binmode(STDOUT, ":utf8"); print "\x{30DE}\x{30A4}\x{30AF}"'
1964 will silently print the Unicode string to STDOUT in UTF-8. To see the
1966 characters printed, you'll need a UTF-8 terminal with a font including
1967 japanese Katakana characters.
1968 How can I send errors to the screen, and debug messages to a file?
1970 Let's assume you want to maintain a detailed DEBUG output in a file and
1971 only messages of level ERROR and higher should be printed on the
1972 screen. Often times, developers come up with something like this:
1973 # Wrong!!!
1975 log4perl.logger = DEBUG, FileApp
1976 log4perl.logger = ERROR, ScreenApp
1977 # Wrong!!!
1978 This won't work, however. Logger definitions aren't additive, and the
1980 second statement will overwrite the first one. Log4perl versions below
1981 1.04 were silently accepting this, leaving people confused why it
1982 wouldn't work as expected. As of 1.04, this will throw a fatal error
1983 to notify the user of the problem.
1984 What you want to do instead, is this:
1986 log4perl.logger = DEBUG, FileApp, ScreenApp
1988 log4perl.appender.FileApp = Log::Log4perl::Appender::File
1990 log4perl.appender.FileApp.filename = test.log
1991 log4perl.appender.FileApp.layout = SimpleLayout
1992 log4perl.appender.ScreenApp = Log::Log4perl::Appender::Screen
1994 log4perl.appender.ScreenApp.stderr = 0
1995 log4perl.appender.ScreenApp.layout = SimpleLayout
1996 ### limiting output to ERROR messages
1997 log4perl.appender.ScreenApp.Threshold = ERROR
1998 ###
1999 Note that without the second appender's "Threshold" setting, both
2001 appenders would receive all messages prioritized DEBUG and higher. With
2002 the threshold set to ERROR, the second appender will filter the
2003 messages as required.
2004 Where should I put my logfiles?
2006 Your log files may go anywhere you want them, but the effective user id
2007 of the calling process must have write access.
2008 If the log file doesn't exist at program start, Log4perl's file
2010 appender will create it. For this, it needs write access to the
2011 directory where the new file will be located in. If the log file
2012 already exists at startup, the process simply needs write access to the
2013 file. Note that it will need write access to the file's directory if
2014 you're encountering situations where the logfile gets recreated, e.g.
2015 during log rotation.
2016 If Log::Log4perl is used by a web server application (e.g. in a CGI
2018 script or mod_perl), then the webserver's user (usually "nobody" or
2019 "www") must have the permissions mentioned above.
2020 To prepare your web server to use log4perl, we'd recommend:
2022 webserver:~$ su -
2024 webserver:~# mkdir /var/log/cgiapps
2025 webserver:~# chown nobody:root /var/log/cgiapps/
2026 webserver:~# chown nobody:root -R /var/log/cgiapps/
2027 webserver:~# chmod 02755 -R /var/log/cgiapps/
2028 Then set your /etc/log4perl.conf file to include:
2030 log4perl.appender.FileAppndr1.filename =
2032 /var/log/cgiapps/<app-name>.log
2033 How can my file appender deal with disappearing log files?
2035 The file appender that comes with Log4perl,
2036 Log::Log4perl::Appender::File, will open a specified log file at
2037 initialization time and will keep writing to it via a file handle.
2038 In case the associated file goes way, messages written by a long-
2040 running process will still be written to the file handle. In case the
2041 file has been moved to a different location on the same file system,
2042 the writer will keep writing to it under the new filename. In case the
2043 file has been removed from the file system, the log messages will end
2044 up in nowhere land. This is not a bug in Log4perl, this is how Unix
2045 works. There is no error message in this case, because the writer has
2046 no idea that the file handle is not associated with a visible file.
2047 To prevent the loss of log messages when log files disappear, the file
2049 appender's "recreate" option needs to be set to a true value:
2050 log4perl.appender.Logfile.recreate = 1
2052 This will instruct the file appender to check in regular intervals
2054 (default: 30 seconds) if the log file is still there. If it finds out
2055 that the file is missing, it will recreate it.
2056 Continuously checking if the log file still exists is fairly expensive.
2058 For this reason it is only performed every 30 seconds. To change this
2059 interval, the option "recreate_check_interval" can be set to the number
2060 of seconds between checks. In the extreme case where the check should
2061 be performed before every write, it can even be set to 0:
2062 log4perl.appender.Logfile.recreate = 1
2064 log4perl.appender.Logfile.recreate_check_interval = 0
2065 To avoid having to check the file system so frequently, a signal
2067 handler can be set up:
2068 log4perl.appender.Logfile.recreate = 1
2070 log4perl.appender.Logfile.recreate_check_signal = USR1
2071 This will install a signal handler which will recreate a missing log
2073 file immediatly when it receives the defined signal.
2074 Note that the init_and_watch() method for Log4perl's initialization can
2076 also be instructed to install a signal handler, usually using the HUP
2077 signal. Make sure to use a different signal if you're using both of
2078 them at the same time.
2079 How can I rotate a logfile with newsyslog?
2081 Here's a few things that need to be taken care of when using the
2082 popular log file rotating utilty "newsyslog"
2083 (http://www.courtesan.com/newsyslog) with Log4perl's file appender in
2084 long-running processes.
2085 For example, with a newsyslog configuration like
2087 # newsyslog.conf
2089 /tmp/test.log 666 12 5 * B
2090 and a call to
2092 # newsyslog -f /path/to/newsyslog.conf
2094 "newsyslog" will take action if "/tmp/test.log" is larger than the
2096 specified 5K in size. It will move the current log file "/tmp/test.log"
2097 to "/tmp/test.log.0" and create a new and empty "/tmp/test.log" with
2098 the specified permissions (this is why "newsyslog" needs to run as
2099 root). An already existing "/tmp/test.log.0" would be moved to
2100 "/tmp/test.log.1", "/tmp/test.log.1" to "/tmp/test.log.2", and so
2101 forth, for every one of a max number of 12 archived logfiles that have
2102 been configured in "newsyslog.conf".
2103 Although a new file has been created, from Log4perl's appender's point
2105 of view, this situation is identical to the one described in the
2106 previous FAQ entry, labeled "How can my file appender deal with
2107 disappearing log files".
2108 To make sure that log messages are written to the new log file and not
2110 to an archived one or end up in nowhere land, the appender's "recreate"
2111 and "recreate_check_interval" have to be configured to deal with the
2112 'disappearing' log file.
2113 The situation gets interesting when "newsyslog"'s option to compress
2115 archived log files is enabled. This causes the original log file not to
2116 be moved, but to disappear. If the file appender isn't configured to
2117 recreate the logfile in this situation, log messages will actually be
2118 lost without warning. This also applies for the short time frame of
2119 "recreate_check_interval" seconds in between the recreator's file
2120 checks.
2121 To make sure that no messages get lost, one option is to set the
2123 interval to
2124 log4perl.appender.Logfile.recreate_check_interval = 0
2126 However, this is fairly expensive. A better approach is to define a
2128 signal handler:
2129 log4perl.appender.Logfile.recreate = 1
2131 log4perl.appender.Logfile.recreate_check_signal = USR1
2132 log4perl.appender.Logfile.recreate_pid_write = /tmp/myappid
2133 As a service for "newsyslog" users, Log4perl's file appender writes the
2135 current process ID to a PID file specified by the "recreate_pid_write"
2136 option. "newsyslog" then needs to be configured as in
2137 # newsyslog.conf configuration for compressing archive files and
2139 # sending a signal to the Log4perl-enabled application
2140 /tmp/test.log 666 12 5 * B /tmp/myappid 30
2141 to send the defined signal (30, which is USR1 on FreeBSD) to the
2143 application process at rotation time. Note that the signal number is
2144 different on Linux, where USR1 denotes as 10. Check "man signal" for
2145 details.
2146 How can a process under user id A log to a file under user id B?
2148 This scenario often occurs in configurations where processes run under
2149 various user IDs but need to write to a log file under a fixed, but
2150 different user id.
2151 With a traditional file appender, the log file will probably be created
2153 under one user's id and appended to under a different user's id. With a
2154 typical umask of 0002, the file will be created with -rw-rw-r--
2155 permissions. If a user who's not in the first user's group subsequently
2156 appends to the log file, it will fail because of a permission problem.
2157 Two potential solutions come to mind:
2159 · Creating the file with a umask of 0000 will allow all users to
2161 append to the log file. Log4perl's file appender
2162 "Log::Log4perl::Appender::File" has an "umask" option that can be
2163 set to support this:
2164 log4perl.appender.File = Log::Log4perl::Appender::File
2166 log4perl.appender.File.umask = sub { 0000 };
2167 This way, the log file will be created with -rw-rw-rw- permissions
2169 and therefore has world write permissions. This might open up the
2170 logfile for unwanted manipulations by arbitrary users, though.
2171 · Running the process under an effective user id of "root" will allow
2173 it to write to the log file, no matter who started the process.
2174 However, this is not a good idea, because of security concerns.
2175 Luckily, under Unix, there's the syslog daemon which runs as root and
2177 takes log requests from user processes over a socket and writes them to
2178 log files as configured in "/etc/syslog.conf".
2179 By modifying "/etc/syslog.conf" and HUPing the syslog daemon, you can
2181 configure new log files:
2182 # /etc/syslog.conf
2184 ...
2185 user.* /some/path/file.log
2186 Using the "Log::Dispatch::Syslog" appender, which comes with the
2188 "Log::Log4perl" distribution, you can then send messages via syslog:
2189 use Log::Log4perl qw(:easy);
2191 Log::Log4perl->init(\<<EOT);
2193 log4perl.logger = DEBUG, app
2194 log4perl.appender.app=Log::Dispatch::Syslog
2195 log4perl.appender.app.Facility=user
2196 log4perl.appender.app.layout=SimpleLayout
2197 EOT
2198 # Writes to /some/path/file.log
2200 ERROR "Message!";
2201 This way, the syslog daemon will solve the permission problem.
2203 Note that while it is possible to use syslog() without Log4perl (syslog
2205 supports log levels, too), traditional syslog setups have a significant
2206 drawback.
2207 Without Log4perl's ability to activate logging in only specific parts
2209 of a system, complex systems will trigger log events all over the place
2210 and slow down execution to a crawl at high debug levels.
2211 Remote-controlling logging in the hierarchical parts of an application
2213 via Log4perl's categories is one of its most distinguished features.
2214 It allows for enabling high debug levels in specified areas without
2215 noticable performance impact.
2216 I want to use UTC instead of the local time!
2218 If a layout defines a date, Log::Log4perl uses local time to populate
2219 it. If you want UTC instead, set
2220 $Log::Log4perl::DateFormat::GMTIME = 1;
2222 in your program before the first log statement.
2224 Can Log4perl intercept messages written to a filehandle?
2226 You have a function that prints to a filehandle. You want to tie into
2227 that filehandle and forward all arriving messages to a Log4perl logger.
2228 First, let's write a package that ties a file handle and forwards it to
2230 a Log4perl logger:
2231 package FileHandleLogger;
2233 use Log::Log4perl qw(:levels get_logger);
2234 sub TIEHANDLE {
2236 my($class, %options) = @_;
2237 my $self = {
2239 level => $DEBUG,
2240 category => '',
2241 %options
2242 };
2243 $self->{logger} = get_logger($self->{category}),
2245 bless $self, $class;
2246 }
2247 sub PRINT {
2249 my($self, @rest) = @_;
2250 $Log::Log4perl::caller_depth++;
2251 $self->{logger}->log($self->{level}, @rest);
2252 $Log::Log4perl::caller_depth--;
2253 }
2254 sub PRINTF {
2256 my($self, $fmt, @rest) = @_;
2257 $Log::Log4perl::caller_depth++;
2258 $self->PRINT(sprintf($fmt, @rest));
2259 $Log::Log4perl::caller_depth--;
2260 }
2261 1;
2263 Now, if you have a function like
2265 sub function_printing_to_fh {
2267 my($fh) = @_;
2268 printf $fh "Hi there!\n";
2269 }
2270 which takes a filehandle and prints something to it, it can be used
2272 with Log4perl:
2273 use Log::Log4perl qw(:easy);
2275 usa FileHandleLogger;
2276 Log::Log4perl->easy_init($DEBUG);
2278 tie *SOMEHANDLE, 'FileHandleLogger' or
2280 die "tie failed ($!)";
2281 function_printing_to_fh(*SOMEHANDLE);
2283 # prints "2007/03/22 21:43:30 Hi there!"
2284 If you want, you can even specify a different log level or category:
2286 tie *SOMEHANDLE, 'FileHandleLogger',
2288 level => $INFO, category => "Foo::Bar" or die "tie failed ($!)";
2289 I want multiline messages rendered line-by-line!
2291 With the standard "PatternLayout", if you send a multiline message to
2292 an appender as in
2293 use Log::Log4perl qw(:easy);
2295 Log
2296 it gets rendered this way:
2298 2007/04/04 23:23:39 multi
2300 line
2301 message
2302 If you want each line to be rendered separately according to the layout
2304 use "Log::Log4perl::Layout::PatternLayout::Multiline":
2305 use Log::Log4perl qw(:easy);
2307 Log::Log4perl->init(\<<EOT);
2309 log4perl.category = DEBUG, Screen
2310 log4perl.appender.Screen = Log::Log4perl::Appender::Screen
2311 log4perl.appender.Screen.layout = \\
2312 Log::Log4perl::Layout::PatternLayout::Multiline
2313 log4perl.appender.Screen.layout.ConversionPattern = %d %m %n
2314 EOT
2315 DEBUG "some\nmultiline\nmessage";
2317 and you'll get
2319 2007/04/04 23:23:39 some
2321 2007/04/04 23:23:39 multiline
2322 2007/04/04 23:23:39 message
2323 instead.
2325 I'm on Windows and I'm getting all these 'redefined' messages!
2327 If you're on Windows and are getting warning messages like
2328 Constant subroutine Log::Log4perl::_INTERNAL_DEBUG redefined at
2330 C:/Programme/Perl/lib/constant.pm line 103.
2331 Subroutine import redefined at
2332 C:/Programme/Perl/site/lib/Log/Log4Perl.pm line 69.
2333 Subroutine initialized redefined at
2334 C:/Programme/Perl/site/lib/Log/Log4Perl.pm line 207.
2335 then chances are that you're using 'Log::Log4Perl' (wrong uppercase P)
2337 instead of the correct 'Log::Log4perl'. Perl on Windows doesn't handle
2338 this error well and spits out a slew of confusing warning messages. But
2339 now you know, just use the correct module name and you'll be fine.
2340 Log4perl complains that no initialization happened during shutdown!
2342 If you're using Log4perl log commands in DESTROY methods of your
2343 objects, you might see confusing messages like
2344 Log4perl: Seems like no initialization happened. Forgot to call init()?
2346 Use of uninitialized value in subroutine entry at
2347 /home/y/lib/perl5/site_perl/5.6.1/Log/Log4perl.pm line 134 during global
2348 destruction. (in cleanup) Undefined subroutine &main:: called at
2349 /home/y/lib/perl5/site_perl/5.6.1/Log/Log4perl.pm line 134 during global
2350 destruction.
2351 when the program shuts down. What's going on?
2353 This phenomenon happens if you have circular references in your
2355 objects, which perl can't clean up when an object goes out of scope but
2356 waits until global destruction instead. At this time, however, Log4perl
2357 has already shut down, so you can't use it anymore.
2358 For example, here's a simple class which uses a logger in its DESTROY
2360 method:
2361 package A;
2363 use Log::Log4perl qw(:easy);
2364 sub new { bless {}, shift }
2365 sub DESTROY { DEBUG "Waaah!"; }
2366 Now, if the main program creates a self-referencing object, like in
2368 package main;
2370 use Log::Log4perl qw(:easy);
2371 Log::Log4perl->easy_init($DEBUG);
2372 my $a = A->new();
2374 $a->{selfref} = $a;
2375 then you'll see the error message shown above during global
2377 destruction. How to tackle this problem?
2378 First, you should clean up your circular references before global
2380 destruction. They will not only cause objects to be destroyed in an
2381 order that's hard to predict, but also eat up memory until the program
2382 shuts down.
2383 So, the program above could easily be fixed by putting
2385 $a->{selfref} = undef;
2387 at the end or in an END handler. If that's hard to do, use weak
2389 references:
2390 package main;
2392 use Scalar::Util qw(weaken);
2393 use Log::Log4perl qw(:easy);
2394 Log::Log4perl->easy_init($DEBUG);
2395 my $a = A->new();
2397 $a->{selfref} = weaken $a;
2398 This allows perl to clean up the circular reference when the object
2400 goes out of scope, and doesn't wait until global destruction.
2401 How can I access POE heap values from Log4perl's layout?
2403 POE is a framework for creating multitasked applications running in a
2404 single process and a single thread. POE's threads equivalents are
2405 'sessions' and since they run quasi-simultaneously, you can't use
2406 Log4perl's global NDC/MDC to hold session-specific data.
2407 However, POE already maintains a data store for every session. It is
2409 called 'heap' and is just a hash storing session-specific data in key-
2410 value pairs. To access this per-session heap data from a Log4perl
2411 layout, define a custom cspec and reference it with the newly defined
2412 pattern in the layout:
2413 use strict;
2415 use POE;
2416 use Log::Log4perl qw(:easy);
2417 Log::Log4perl->init( \ q{
2419 log4perl.logger = DEBUG, Screen
2420 log4perl.appender.Screen = Log::Log4perl::Appender::Screen
2421 log4perl.appender.Screen.layout = PatternLayout
2422 log4perl.appender.Screen.layout.ConversionPattern = %U %m%n
2423 log4perl.PatternLayout.cspec.U = \
2424 sub { POE::Kernel->get_active_session->get_heap()->{ user } }
2425 } );
2426 for (qw( Huey Lewey Dewey )) {
2428 POE::Session->create(
2429 inline_states => {
2430 _start => sub {
2431 $_[HEAP]->{user} = $_;
2432 POE::Kernel->yield('hello');
2433 },
2434 hello => sub {
2435 DEBUG "I'm here now";
2436 }
2437 }
2438 );
2439 }
2440 POE::Kernel->run();
2442 exit;
2443 The code snippet above defines a new layout placeholder (called 'cspec'
2445 in Log4perl) %U which calls a subroutine, retrieves the active session,
2446 gets its heap and looks up the entry specified ('user').
2447 Starting with Log::Log4perl 1.20, cspecs also support parameters in
2449 curly braces, so you can say
2450 log4perl.appender.Screen.layout.ConversionPattern = %U{user} %U{id} %m%n
2452 log4perl.PatternLayout.cspec.U = \
2453 sub { POE::Kernel->get_active_session-> \
2454 get_heap()->{ $_[0]->{curlies} } }
2455 and print the POE session heap entries 'user' and 'id' with every
2457 logged message. For more details on cpecs, read the PatternLayout
2458 manual.
2459 I want to print something unconditionally!
2461 Sometimes it's a script that's supposed to log messages regardless if
2462 Log4perl has been initialized or not. Or there's a logging statement
2463 that's not going to be suppressed under any circumstances -- many
2464 people want to have the final word, make the executive decision,
2465 because it seems like the only logical choice.
2466 But think about it: First off, if a messages is supposed to be printed,
2468 where is it supposed to end up at? STDOUT? STDERR? And are you sure you
2469 want to set in stone that this message needs to be printed, while
2470 someone else might find it annoying and wants to get rid of it?
2471 The truth is, there's always going to be someone who wants to log a
2473 messages at all cost, but also another person who wants to suppress it
2474 with equal vigilance. There's no good way to serve these two
2475 conflicting desires, someone will always want to win at the cost of
2476 leaving the other party dissappointed.
2477 So, the best Log4perl offers is the ALWAYS level for a message that
2479 even fires if the system log level is set to $OFF:
2480 use Log::Log4perl qw(:easy);
2482 Log::Log4perl->easy_init( $OFF );
2484 ALWAYS "This gets logged always. Well, almost always";
2485 The logger won't fire, though, if Log4perl hasn't been initialized or
2487 if someone defines a custom log hurdle that's higher than $OFF.
2488 Bottom line: Leave the setting of the logging level to the initial Perl
2490 script -- let their owners decided what they want, no matter how
2491 tempting it may be to decide it for them.
2492
2494 Log::Log4perl
2495
2497 Copyright 2002-2009 by Mike Schilli <m@perlmeister.com> and Kevin Goess
2498 <cpan@goess.org>.
2499 This library is free software; you can redistribute it and/or modify it
2501 under the same terms as Perl itself.
2502perl v5.12.2 2010-08-31 FAQ(3)