1###################################################################### 2 Log::Log4perl 1.15 3###################################################################### 4 5NAME 6 Log::Log4perl - Log4j implementation for Perl 7 8SYNOPSIS 9 # Easy mode if you like it simple ... 10 11 use Log::Log4perl qw(:easy); 12 Log::Log4perl->easy_init($ERROR); 13 14 DEBUG "This doesn't go anywhere"; 15 ERROR "This gets logged"; 16 17 # ... or standard mode for more features: 18 19 Log::Log4perl::init('/etc/log4perl.conf'); 20 21 --or-- 22 23 # Check config every 10 secs 24 Log::Log4perl::init_and_watch('/etc/log4perl.conf',10); 25 26 --then-- 27 28 $logger = Log::Log4perl->get_logger('house.bedrm.desk.topdrwr'); 29 30 $logger->debug('this is a debug message'); 31 $logger->info('this is an info message'); 32 $logger->warn('etc'); 33 $logger->error('..'); 34 $logger->fatal('..'); 35 36 #####/etc/log4perl.conf############################### 37 log4perl.logger.house = WARN, FileAppndr1 38 log4perl.logger.house.bedroom.desk = DEBUG, FileAppndr1 39 40 log4perl.appender.FileAppndr1 = Log::Log4perl::Appender::File 41 log4perl.appender.FileAppndr1.filename = desk.log 42 log4perl.appender.FileAppndr1.layout = \ 43 Log::Log4perl::Layout::SimpleLayout 44 ###################################################### 45 46ABSTRACT 47 Log::Log4perl provides a powerful logging API for your application 48 49DESCRIPTION 50 Log::Log4perl lets you remote-control and fine-tune the logging 51 behaviour of your system from the outside. It implements the widely 52 popular (Java-based) Log4j logging package in pure Perl. 53 54 For a detailed tutorial on Log::Log4perl usage, please read 55 56 http://www.perl.com/pub/a/2002/09/11/log4perl.html 57 58 Logging beats a debugger if you want to know what's going on in your 59 code during runtime. However, traditional logging packages are too 60 static and generate a flood of log messages in your log files that won't 61 help you. 62 63 "Log::Log4perl" is different. It allows you to control the number of 64 logging messages generated at three different levels: 65 66 * At a central location in your system (either in a configuration file 67 or in the startup code) you specify *which components* (classes, 68 functions) of your system should generate logs. 69 70 * You specify how detailed the logging of these components should be 71 by specifying logging *levels*. 72 73 * You also specify which so-called *appenders* you want to feed your 74 log messages to ("Print it to the screen and also append it to 75 /tmp/my.log") and which format ("Write the date first, then the file 76 name and line number, and then the log message") they should be in. 77 78 This is a very powerful and flexible mechanism. You can turn on and off 79 your logs at any time, specify the level of detail and make that 80 dependent on the subsystem that's currently executed. 81 82 Let me give you an example: You might find out that your system has a 83 problem in the "MySystem::Helpers::ScanDir" component. Turning on 84 detailed debugging logs all over the system would generate a flood of 85 useless log messages and bog your system down beyond recognition. With 86 "Log::Log4perl", however, you can tell the system: "Continue to log only 87 severe errors to the log file. Open a second log file, turn on full 88 debug logs in the "MySystem::Helpers::ScanDir" component and dump all 89 messages originating from there into the new log file". And all this is 90 possible by just changing the parameters in a configuration file, which 91 your system can re-read even while it's running! 92 93How to use it 94 The "Log::Log4perl" package can be initialized in two ways: Either via 95 Perl commands or via a "log4j"-style configuration file. 96 97 Initialize via a configuration file 98 This is the easiest way to prepare your system for using 99 "Log::Log4perl". Use a configuration file like this: 100 101 ############################################################ 102 # A simple root logger with a Log::Log4perl::Appender::File 103 # file appender in Perl. 104 ############################################################ 105 log4perl.rootLogger=ERROR, LOGFILE 106 107 log4perl.appender.LOGFILE=Log::Log4perl::Appender::File 108 log4perl.appender.LOGFILE.filename=/var/log/myerrs.log 109 log4perl.appender.LOGFILE.mode=append 110 111 log4perl.appender.LOGFILE.layout=PatternLayout 112 log4perl.appender.LOGFILE.layout.ConversionPattern=[%r] %F %L %c - %m%n 113 114 These lines define your standard logger that's appending severe errors 115 to "/var/log/myerrs.log", using the format 116 117 [millisecs] source-filename line-number class - message newline 118 119 Assuming that this configuration file is saved as "log.conf", you need 120 to read it in in the startup section of your code, using the following 121 commands: 122 123 use Log::Log4perl; 124 Log::Log4perl->init("log.conf"); 125 126 After that's done *somewhere* in the code, you can retrieve logger 127 objects *anywhere* in the code. Note that there's no need to carry any 128 logger references around with your functions and methods. You can get a 129 logger anytime via a singleton mechanism: 130 131 package My::MegaPackage; 132 use Log::Log4perl; 133 134 sub some_method { 135 my($param) = @_; 136 137 my $log = Log::Log4perl->get_logger("My::MegaPackage"); 138 139 $log->debug("Debug message"); 140 $log->info("Info message"); 141 $log->error("Error message"); 142 143 ... 144 } 145 146 With the configuration file above, "Log::Log4perl" will write "Error 147 message" to the specified log file, but won't do anything for the 148 "debug()" and "info()" calls, because the log level has been set to 149 "ERROR" for all components in the first line of configuration file shown 150 above. 151 152 Why "Log::Log4perl->get_logger" and not "Log::Log4perl->new"? We don't 153 want to create a new object every time. Usually in OO-Programming, you 154 create an object once and use the reference to it to call its methods. 155 However, this requires that you pass around the object to all functions 156 and the last thing we want is pollute each and every function/method 157 we're using with a handle to the "Logger": 158 159 sub function { # Brrrr!! 160 my($logger, $some, $other, $parameters) = @_; 161 } 162 163 Instead, if a function/method wants a reference to the logger, it just 164 calls the Logger's static "get_logger($category)" method to obtain a 165 reference to the *one and only* possible logger object of a certain 166 category. That's called a *singleton* if you're a Gamma fan. 167 168 How does the logger know which messages it is supposed to log and which 169 ones to suppress? "Log::Log4perl" works with inheritance: The config 170 file above didn't specify anything about "My::MegaPackage". And yet, 171 we've defined a logger of the category "My::MegaPackage". In this case, 172 "Log::Log4perl" will walk up the class hierarchy ("My" and then the 173 we're at the root) to figure out if a log level is defined somewhere. In 174 the case above, the log level at the root (root *always* defines a log 175 level, but not necessarily an appender) defines that the log level is 176 supposed to be "ERROR" -- meaning that *DEBUG* and *INFO* messages are 177 suppressed. 178 179 Log Levels 180 There are six predefined log levels: "FATAL", "ERROR", "WARN", "INFO", 181 "DEBUG", and "TRACE" (in descending priority). Your configured logging 182 level has to at least match the priority of the logging message. 183 184 If your configured logging level is "WARN", then messages logged with 185 "info()", "debug()", and "trace()" will be suppressed. "fatal()", 186 "error()" and "warn()" will make their way through, because their 187 priority is higher or equal than the configured setting. 188 189 Instead of calling the methods 190 191 $logger->trace("..."); # Log a trace message 192 $logger->debug("..."); # Log a debug message 193 $logger->info("..."); # Log a info message 194 $logger->warn("..."); # Log a warn message 195 $logger->error("..."); # Log a error message 196 $logger->fatal("..."); # Log a fatal message 197 198 you could also call the "log()" method with the appropriate level using 199 the constants defined in "Log::Log4perl::Level": 200 201 use Log::Log4perl::Level; 202 203 $logger->log($TRACE, "..."); 204 $logger->log($DEBUG, "..."); 205 $logger->log($INFO, "..."); 206 $logger->log($WARN, "..."); 207 $logger->log($ERROR, "..."); 208 $logger->log($FATAL, "..."); 209 210 But nobody does that, really. Neither does anyone need more logging 211 levels than these predefined ones. If you think you do, I would suggest 212 you look into steering your logging behaviour via the category 213 mechanism. 214 215 If you need to find out if the currently configured logging level would 216 allow a logger's logging statement to go through, use the logger's 217 "is_*level*()" methods: 218 219 $logger->is_trace() # True if trace messages would go through 220 $logger->is_debug() # True if debug messages would go through 221 $logger->is_info() # True if info messages would go through 222 $logger->is_warn() # True if warn messages would go through 223 $logger->is_error() # True if error messages would go through 224 $logger->is_fatal() # True if fatal messages would go through 225 226 Example: "$logger->is_warn()" returns true if the logger's current 227 level, as derived from either the logger's category (or, in absence of 228 that, one of the logger's parent's level setting) is $WARN, $ERROR or 229 $FATAL. 230 231 Also available are a series of more Java-esque functions which return 232 the same values. These are of the format "is*Level*Enabled()", so 233 "$logger->isDebugEnabled()" is synonymous to "$logger->is_debug()". 234 235 These level checking functions will come in handy later, when we want to 236 block unnecessary expensive parameter construction in case the logging 237 level is too low to log the statement anyway, like in: 238 239 if($logger->is_error()) { 240 $logger->error("Erroneous array: @super_long_array"); 241 } 242 243 If we had just written 244 245 $logger->error("Erroneous array: @super_long_array"); 246 247 then Perl would have interpolated @super_long_array into the string via 248 an expensive operation only to figure out shortly after that the string 249 can be ignored entirely because the configured logging level is lower 250 than $ERROR. 251 252 The to-be-logged message passed to all of the functions described above 253 can consist of an arbitrary number of arguments, which the logging 254 functions just chain together to a single string. Therefore 255 256 $logger->debug("Hello ", "World", "!"); # and 257 $logger->debug("Hello World!"); 258 259 are identical. 260 261 Log and die or warn 262 Often, when you croak / carp / warn / die, you want to log those 263 messages. Rather than doing the following: 264 265 $logger->fatal($err) && die($err); 266 267 you can use the following: 268 269 $logger->logwarn(); 270 $logger->logdie(); 271 272 These print out log messages in the WARN and FATAL level, respectively, 273 and then call the built-in warn() and die() functions. Since there is an 274 ERROR level between WARN and FATAL, there are two additional helper 275 functions in case you'd like to use ERROR for either warn() or die(): 276 277 $logger->error_warn(); 278 $logger->error_die(); 279 280 Finally, there's the Carp functions that do just what the Carp functions 281 do, but with logging: 282 283 $logger->logcarp(); # warn w/ 1-level stack trace 284 $logger->logcluck(); # warn w/ full stack trace 285 $logger->logcroak(); # die w/ 1-level stack trace 286 $logger->logconfess(); # die w/ full stack trace 287 288 Appenders 289 If you don't define any appenders, nothing will happen. Appenders will 290 be triggered whenever the configured logging level requires a message to 291 be logged and not suppressed. 292 293 "Log::Log4perl" doesn't define any appenders by default, not even the 294 root logger has one. 295 296 "Log::Log4perl" already comes with a standard set of appenders: 297 298 Log::Log4perl::Appender::Screen 299 Log::Log4perl::Appender::ScreenColoredLevels 300 Log::Log4perl::Appender::File 301 Log::Log4perl::Appender::Socket 302 Log::Log4perl::Appender::DBI 303 Log::Log4perl::Appender::Synchronized 304 Log::Log4perl::Appender::RRDs 305 306 to log to the screen, to files and to databases. 307 308 On CPAN, you can find additional appenders like 309 310 Log::Log4perl::Layout::XMLLayout 311 312 by Guido Carls <gcarls@cpan.org>. It allows for hooking up Log::Log4perl 313 with the graphical Log Analyzer Chainsaw (see "Can I use Log::Log4perl 314 with log4j's Chainsaw?" in Log::Log4perl::FAQ). 315 316 Additional Appenders via Log::Dispatch 317 "Log::Log4perl" also supports *Dave Rolskys* excellent "Log::Dispatch" 318 framework which implements a wide variety of different appenders. 319 320 Here's the list of appender modules currently available via 321 "Log::Dispatch": 322 323 Log::Dispatch::ApacheLog 324 Log::Dispatch::DBI (by Tatsuhiko Miyagawa) 325 Log::Dispatch::Email, 326 Log::Dispatch::Email::MailSend, 327 Log::Dispatch::Email::MailSendmail, 328 Log::Dispatch::Email::MIMELite 329 Log::Dispatch::File 330 Log::Dispatch::FileRotate (by Mark Pfeiffer) 331 Log::Dispatch::Handle 332 Log::Dispatch::Screen 333 Log::Dispatch::Syslog 334 Log::Dispatch::Tk (by Dominique Dumont) 335 336 Please note that in order to use any of these additional appenders, you 337 have to fetch Log::Dispatch from CPAN and install it. Also the 338 particular appender you're using might require installing the particular 339 module. 340 341 For additional information on appenders, please check the 342 Log::Log4perl::Appender manual page. 343 344 Appender Example 345 Now let's assume that we want to log "info()" or higher prioritized 346 messages in the "Foo::Bar" category to both STDOUT and to a log file, 347 say "test.log". In the initialization section of your system, just 348 define two appenders using the readily available 349 "Log::Log4perl::Appender::File" and "Log::Log4perl::Appender::Screen" 350 modules: 351 352 use Log::Log4perl; 353 354 # Configuration in a string ... 355 my $conf = q( 356 log4perl.category.Foo.Bar = INFO, Logfile, Screen 357 358 log4perl.appender.Logfile = Log::Log4perl::Appender::File 359 log4perl.appender.Logfile.filename = test.log 360 log4perl.appender.Logfile.layout = Log::Log4perl::Layout::PatternLayout 361 log4perl.appender.Logfile.layout.ConversionPattern = [%r] %F %L %m%n 362 363 log4perl.appender.Screen = Log::Log4perl::Appender::Screen 364 log4perl.appender.Screen.stderr = 0 365 log4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout 366 ); 367 368 # ... passed as a reference to init() 369 Log::Log4perl::init( \$conf ); 370 371 Once the initialization shown above has happened once, typically in the 372 startup code of your system, just use the defined logger anywhere in 373 your system: 374 375 ########################## 376 # ... in some function ... 377 ########################## 378 my $log = Log::Log4perl::get_logger("Foo::Bar"); 379 380 # Logs both to STDOUT and to the file test.log 381 $log->info("Important Info!"); 382 383 The "layout" settings specified in the configuration section define the 384 format in which the message is going to be logged by the specified 385 appender. The format shown for the file appender is logging not only the 386 message but also the number of milliseconds since the program has 387 started (%r), the name of the file the call to the logger has happened 388 and the line number there (%F and %L), the message itself (%m) and a 389 OS-specific newline character (%n): 390 391 [187] ./myscript.pl 27 Important Info! 392 393 The screen appender above, on the other hand, uses a "SimpleLayout", 394 which logs the debug level, a hyphen (-) and the log message: 395 396 INFO - Important Info! 397 398 For more detailed info on layout formats, see "Log Layouts". 399 400 In the configuration sample above, we chose to define a *category* 401 logger ("Foo::Bar"). This will cause only messages originating from this 402 specific category logger to be logged in the defined format and 403 locations. 404 405 Configuration files 406 As shown above, you can define "Log::Log4perl" loggers both from within 407 your Perl code or from configuration files. The latter have the 408 unbeatable advantage that you can modify your system's logging behaviour 409 without interfering with the code at all. So even if your code is being 410 run by somebody who's totally oblivious to Perl, they still can adapt 411 the module's logging behaviour to their needs. 412 413 "Log::Log4perl" has been designed to understand "Log4j" configuration 414 files -- as used by the original Java implementation. Instead of 415 reiterating the format description in [2], let me just list three 416 examples (also derived from [2]), which should also illustrate how it 417 works: 418 419 log4j.rootLogger=DEBUG, A1 420 log4j.appender.A1=org.apache.log4j.ConsoleAppender 421 log4j.appender.A1.layout=org.apache.log4j.PatternLayout 422 log4j.appender.A1.layout.ConversionPattern=%-4r %-5p %c %x - %m%n 423 424 This enables messages of priority "DEBUG" or higher in the root 425 hierarchy and has the system write them to the console. 426 "ConsoleAppender" is a Java appender, but "Log::Log4perl" jumps through 427 a significant number of hoops internally to map these to their 428 corresponding Perl classes, "Log::Log4perl::Appender::Screen" in this 429 case. 430 431 Second example: 432 433 log4perl.rootLogger=DEBUG, A1 434 log4perl.appender.A1=Log::Log4perl::Appender::Screen 435 log4perl.appender.A1.layout=PatternLayout 436 log4perl.appender.A1.layout.ConversionPattern=%d %-5p %c - %m%n 437 log4perl.logger.com.foo=WARN 438 439 This defines two loggers: The root logger and the "com.foo" logger. The 440 root logger is easily triggered by debug-messages, but the "com.foo" 441 logger makes sure that messages issued within the "Com::Foo" component 442 and below are only forwarded to the appender if they're of priority 443 *warning* or higher. 444 445 Note that the "com.foo" logger doesn't define an appender. Therefore, it 446 will just propagate the message up the hierarchy until the root logger 447 picks it up and forwards it to the one and only appender of the root 448 category, using the format defined for it. 449 450 Third example: 451 452 log4j.rootLogger=debug, stdout, R 453 log4j.appender.stdout=org.apache.log4j.ConsoleAppender 454 log4j.appender.stdout.layout=org.apache.log4j.PatternLayout 455 log4j.appender.stdout.layout.ConversionPattern=%5p (%F:%L) - %m%n 456 log4j.appender.R=org.apache.log4j.RollingFileAppender 457 log4j.appender.R.File=example.log 458 log4j.appender.R.layout=org.apache.log4j.PatternLayout 459 log4j.appender.R.layout.ConversionPattern=%p %c - %m%n 460 461 The root logger defines two appenders here: "stdout", which uses 462 "org.apache.log4j.ConsoleAppender" (ultimately mapped by "Log::Log4perl" 463 to "Log::Log4perl::Appender::Screen") to write to the screen. And "R", a 464 "org.apache.log4j.RollingFileAppender" (mapped by "Log::Log4perl" to 465 "Log::Dispatch::FileRotate" with the "File" attribute specifying the log 466 file. 467 468 See Log::Log4perl::Config for more examples and syntax explanations. 469 470 Log Layouts 471 If the logging engine passes a message to an appender, because it thinks 472 it should be logged, the appender doesn't just write it out haphazardly. 473 There's ways to tell the appender how to format the message and add all 474 sorts of interesting data to it: The date and time when the event 475 happened, the file, the line number, the debug level of the logger and 476 others. 477 478 There's currently two layouts defined in "Log::Log4perl": 479 "Log::Log4perl::Layout::SimpleLayout" and 480 "Log::Log4perl::Layout::PatternLayout": 481 482 "Log::Log4perl::SimpleLayout" 483 formats a message in a simple way and just prepends it by the debug 484 level and a hyphen: ""$level - $message", for example "FATAL - Can't 485 open password file". 486 487 "Log::Log4perl::Layout::PatternLayout" 488 on the other hand is very powerful and allows for a very flexible 489 format in "printf"-style. The format string can contain a number of 490 placeholders which will be replaced by the logging engine when it's 491 time to log the message: 492 493 %c Category of the logging event. 494 %C Fully qualified package (or class) name of the caller 495 %d Current date in yyyy/MM/dd hh:mm:ss format 496 %F File where the logging event occurred 497 %H Hostname 498 %l Fully qualified name of the calling method followed by the 499 callers source the file name and line number between 500 parentheses. 501 %L Line number within the file where the log statement was issued 502 %m The message to be logged 503 %M Method or function where the logging request was issued 504 %n Newline (OS-independent) 505 %p Priority of the logging event 506 %P pid of the current process 507 %r Number of milliseconds elapsed from program start to logging 508 event 509 %x The elements of the NDC stack (see below) 510 %X{key} The entry 'key' of the MDC (see below) 511 %% A literal percent (%) sign 512 513 NDC and MDC are explained in "Nested Diagnostic Context (NDC)" and 514 "Mapped Diagnostic Context (MDC)". 515 516 Also, %d can be fine-tuned to display only certain characteristics 517 of a date, according to the SimpleDateFormat in the Java World 518 (http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.ht 519 ml) 520 521 In this way, %d{HH:mm} displays only hours and minutes of the 522 current date, while %d{yy, EEEE} displays a two-digit year, followed 523 by a spelled-out (like "Wednesday"). 524 525 Similar options are available for shrinking the displayed category 526 or limit file/path components, %F{1} only displays the source file 527 *name* without any path components while %F logs the full path. 528 %c{2} only logs the last two components of the current category, 529 "Foo::Bar::Baz" becomes "Bar::Baz" and saves space. 530 531 If those placeholders aren't enough, then you can define your own 532 right in the config file like this: 533 534 log4perl.PatternLayout.cspec.U = sub { return "UID $<" } 535 536 See Log::Log4perl::Layout::PatternLayout for further details on 537 customized specifiers. 538 539 Please note that the subroutines you're defining in this way are 540 going to be run in the "main" namespace, so be sure to fully qualify 541 functions and variables if they're located in different packages. 542 543 SECURITY NOTE: this feature means arbitrary perl code can be 544 embedded in the config file. In the rare case where the people who 545 have access to your config file are different from the people who 546 write your code and shouldn't have execute rights, you might want to 547 call 548 549 Log::Log4perl::Config->allow_code(0); 550 551 before you call init(). Alternatively you can supply a restricted 552 set of Perl opcodes that can be embedded in the config file as 553 described in "Restricting what Opcodes can be in a Perl Hook". 554 555 All placeholders are quantifiable, just like in *printf*. Following this 556 tradition, "%-20c" will reserve 20 chars for the category and 557 left-justify it. 558 559 For more details on logging and how to use the flexible and the simple 560 format, check out the original "log4j" website under 561 562 http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/SimpleLayout.html 563 http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/PatternLayout.html 564 565 Penalties 566 Logging comes with a price tag. "Log::Log4perl" has been optimized to 567 allow for maximum performance, both with logging enabled and disabled. 568 569 But you need to be aware that there's a small hit every time your code 570 encounters a log statement -- no matter if logging is enabled or not. 571 "Log::Log4perl" has been designed to keep this so low that it will be 572 unnoticable to most applications. 573 574 Here's a couple of tricks which help "Log::Log4perl" to avoid 575 unnecessary delays: 576 577 You can save serious time if you're logging something like 578 579 # Expensive in non-debug mode! 580 for (@super_long_array) { 581 $logger->debug("Element: $_\n"); 582 } 583 584 and @super_long_array is fairly big, so looping through it is pretty 585 expensive. Only you, the programmer, knows that going through that "for" 586 loop can be skipped entirely if the current logging level for the actual 587 component is higher than "debug". In this case, use this instead: 588 589 # Cheap in non-debug mode! 590 if($logger->is_debug()) { 591 for (@super_long_array) { 592 $logger->debug("Element: $_\n"); 593 } 594 } 595 596 If you're afraid that the way you're generating the parameters to the of 597 the logging function is fairly expensive, use closures: 598 599 # Passed as subroutine ref 600 use Data::Dumper; 601 $logger->debug(sub { Dumper($data) } ); 602 603 This won't unravel $data via Dumper() unless it's actually needed 604 because it's logged. 605 606 Also, Log::Log4perl lets you specify arguments to logger functions in 607 *message output filter syntax*: 608 609 $logger->debug("Structure: ", 610 { filter => \&Dumper, 611 value => $someref }); 612 613 In this way, shortly before Log::Log4perl sending the message out to any 614 appenders, it will be searching all arguments for hash references and 615 treat them in a special way: 616 617 It will invoke the function given as a reference with the "filter" key 618 ("Data::Dumper::Dumper()") and pass it the value that came with the key 619 named "value" as an argument. The anonymous hash in the call above will 620 be replaced by the return value of the filter function. 621 622Categories 623 "Log::Log4perl" uses *categories* to determine if a log statement in a 624 component should be executed or suppressed at the current logging level. 625 Most of the time, these categories are just the classes the log 626 statements are located in: 627 628 package Candy::Twix; 629 630 sub new { 631 my $logger = Log::Log4perl->new("Candy::Twix"); 632 $logger->debug("Creating a new Twix bar"); 633 bless {}, shift; 634 } 635 636 # ... 637 638 package Candy::Snickers; 639 640 sub new { 641 my $logger = Log::Log4perl->new("Candy.Snickers"); 642 $logger->debug("Creating a new Snickers bar"); 643 bless {}, shift; 644 } 645 646 # ... 647 648 package main; 649 Log::Log4perl->init("mylogdefs.conf"); 650 651 # => "LOG> Creating a new Snickers bar" 652 my $first = Candy::Snickers->new(); 653 # => "LOG> Creating a new Twix bar" 654 my $second = Candy::Twix->new(); 655 656 Note that you can separate your category hierarchy levels using either 657 dots like in Java (.) or double-colons (::) like in Perl. Both notations 658 are equivalent and are handled the same way internally. 659 660 However, categories are just there to make use of inheritance: if you 661 invoke a logger in a sub-category, it will bubble up the hierarchy and 662 call the appropriate appenders. Internally, categories are not related 663 to the class hierarchy of the program at all -- they're purely virtual. 664 You can use arbitrary categories -- for example in the following 665 program, which isn't oo-style, but procedural: 666 667 sub print_portfolio { 668 669 my $log = Log::Log4perl->new("user.portfolio"); 670 $log->debug("Quotes requested: @_"); 671 672 for(@_) { 673 print "$_: ", get_quote($_), "\n"; 674 } 675 } 676 677 sub get_quote { 678 679 my $log = Log::Log4perl->new("internet.quotesystem"); 680 $log->debug("Fetching quote: $_[0]"); 681 682 return yahoo_quote($_[0]); 683 } 684 685 The logger in first function, "print_portfolio", is assigned the 686 (virtual) "user.portfolio" category. Depending on the "Log4perl" 687 configuration, this will either call a "user.portfolio" appender, a 688 "user" appender, or an appender assigned to root -- without 689 "user.portfolio" having any relevance to the class system used in the 690 program. The logger in the second function adheres to the 691 "internet.quotesystem" category -- again, maybe because it's bundled 692 with other Internet functions, but not because there would be a class of 693 this name somewhere. 694 695 However, be careful, don't go overboard: if you're developing a system 696 in object-oriented style, using the class hierarchy is usually your best 697 choice. Think about the people taking over your code one day: The class 698 hierarchy is probably what they know right up front, so it's easy for 699 them to tune the logging to their needs. 700 701 Turn off a component 702 "Log4perl" doesn't only allow you to selectively switch *on* a category 703 of log messages, you can also use the mechanism to selectively *disable* 704 logging in certain components whereas logging is kept turned on in 705 higher-level categories. This mechanism comes in handy if you find that 706 while bumping up the logging level of a high-level (i. e. close to root) 707 category, that one component logs more than it should, 708 709 Here's how it works: 710 711 ############################################################ 712 # Turn off logging in a lower-level category while keeping 713 # it active in higher-level categories. 714 ############################################################ 715 log4perl.rootLogger=DEBUG, LOGFILE 716 log4perl.logger.deep.down.the.hierarchy = ERROR, LOGFILE 717 718 # ... Define appenders ... 719 720 This way, log messages issued from within "Deep::Down::The::Hierarchy" 721 and below will be logged only if they're "ERROR" or worse, while in all 722 other system components even "DEBUG" messages will be logged. 723 724 Return Values 725 All logging methods return values indicating if their message actually 726 reached one or more appenders. If the message has been suppressed 727 because of level constraints, "undef" is returned. 728 729 For example, 730 731 my $ret = $logger->info("Message"); 732 733 will return "undef" if the system debug level for the current category 734 is not "INFO" or more permissive. If Log::Log4perl forwarded the message 735 to one or more appenders, the number of appenders is returned. 736 737 If appenders decide to veto on the message with an appender threshold, 738 the log method's return value will have them excluded. This means that 739 if you've got one appender holding an appender threshold and you're 740 logging a message which passes the system's log level hurdle but not the 741 appender threshold, 0 will be returned by the log function. 742 743 The bottom line is: Logging functions will return a *true* value if the 744 message made it through to one or more appenders and a *false* value if 745 it didn't. This allows for constructs like 746 747 $logger->fatal("@_") or print STDERR "@_\n"; 748 749 which will ensure that the fatal message isn't lost if the current level 750 is lower than FATAL or printed twice if the level is acceptable but an 751 appender already points to STDERR. 752 753 Pitfalls with Categories 754 Be careful with just blindly reusing the system's packages as 755 categories. If you do, you'll get into trouble with inherited methods. 756 Imagine the following class setup: 757 758 use Log::Log4perl; 759 760 ########################################### 761 package Bar; 762 ########################################### 763 sub new { 764 my($class) = @_; 765 my $logger = Log::Log4perl::get_logger(__PACKAGE__); 766 $logger->debug("Creating instance"); 767 bless {}, $class; 768 } 769 ########################################### 770 package Bar::Twix; 771 ########################################### 772 our @ISA = qw(Bar); 773 774 ########################################### 775 package main; 776 ########################################### 777 Log::Log4perl->init(\ qq{ 778 log4perl.category.Bar.Twix = DEBUG, Screen 779 log4perl.appender.Screen = Log::Log4perl::Appender::Screen 780 log4perl.appender.Screen.layout = SimpleLayout 781 }); 782 783 my $bar = Bar::Twix->new(); 784 785 "Bar::Twix" just inherits everything from "Bar", including the 786 constructor "new()". Contrary to what you might be thinking at first, 787 this won't log anything. Reason for this is the "get_logger()" call in 788 package "Bar", which will always get a logger of the "Bar" category, 789 even if we call "new()" via the "Bar::Twix" package, which will make 790 perl go up the inheritance tree to actually execute "Bar::new()". Since 791 we've only defined logging behaviour for "Bar::Twix" in the 792 configuration file, nothing will happen. 793 794 This can be fixed by changing the "get_logger()" method in "Bar::new()" 795 to obtain a logger of the category matching the *actual* class of the 796 object, like in 797 798 # ... in Bar::new() ... 799 my $logger = Log::Log4perl::get_logger($class); 800 801 This way, you'll make sure the logger logs appropriately, no matter if 802 the method is inherited or called directly. "new()" always gets the real 803 class name as an argument and all other methods can determine it via 804 "ref($self)"), so it shouldn't be a problem to get the right class every 805 time. 806 807 Initialize once and only once 808 It's important to realize that Log::Log4perl gets initialized once and 809 only once, typically at the start of a program or system. Calling 810 "init()" more than once will cause it to clobber the existing 811 configuration and *replace* it by the new one. 812 813 If you're in a traditional CGI environment, where every request is 814 handeled by a new process, calling "init()" every time is fine. In 815 persistent environments like "mod_perl", however, Log::Log4perl should 816 be initialized either at system startup time (Apache offers startup 817 handlers for that) or via 818 819 # Init or skip if already done 820 Log::Log4perl->init_once($conf_file); 821 822 "init_once()" is identical to "init()", just with the exception that it 823 will leave a potentially existing configuration alone and will only call 824 "init()" if Log::Log4perl hasn't been initialized yet. 825 826 If you're just curious if Log::Log4perl has been initialized yet, the 827 check 828 829 if(Log::Log4perl->initialized()) { 830 # Yes, Log::Log4perl has already been initialized 831 } else { 832 # No, not initialized yet ... 833 } 834 835 can be used. 836 837 If you're afraid that the components of your system are stepping on each 838 other's toes or if you are thinking that different components should 839 initialize Log::Log4perl seperately, try to consolidate your system to 840 use a centralized Log4perl configuration file and use Log4perl's 841 *categories* to separate your components. 842 843 Custom Filters 844 Log4perl allows the use of customized filters in its appenders to 845 control the output of messages. These filters might grep for certain 846 text chunks in a message, verify that its priority matches or exceeds a 847 certain level or that this is the 10th time the same message has been 848 submitted -- and come to a log/no log decision based upon these 849 circumstantial facts. 850 851 Check out Log::Log4perl::Filter for detailed instructions on how to use 852 them. 853 854 Performance 855 The performance of Log::Log4perl calls obviously depends on a lot of 856 things. But to give you a general idea, here's some rough numbers: 857 858 On a Pentium 4 Linux box at 2.4 GHz, you'll get through 859 860 * 500,000 suppressed log statements per second 861 862 * 30,000 logged messages per second (using an in-memory appender) 863 864 * init_and_watch delay mode: 300,000 suppressed, 30,000 logged. 865 init_and_watch signal mode: 450,000 suppressed, 30,000 logged. 866 867 Numbers depend on the complexity of the Log::Log4perl configuration. For 868 a more detailed benchmark test, check the "docs/benchmark.results.txt" 869 document in the Log::Log4perl distribution. 870 871Cool Tricks 872 Here's a collection of useful tricks for the advanced "Log::Log4perl" 873 user. For more, check the the FAQ, either in the distribution 874 (Log::Log4perl::FAQ) or on http://log4perl.sourceforge.net. 875 876 Shortcuts 877 When getting an instance of a logger, instead of saying 878 879 use Log::Log4perl; 880 my $logger = Log::Log4perl->get_logger(); 881 882 it's often more convenient to import the "get_logger" method from 883 "Log::Log4perl" into the current namespace: 884 885 use Log::Log4perl qw(get_logger); 886 my $logger = get_logger(); 887 888 Please note this difference: To obtain the root logger, please use 889 "get_logger("")", call it without parameters ("get_logger()"), you'll 890 get the logger of a category named after the current package. 891 "get_logger()" is equivalent to "get_logger(__PACKAGE__)". 892 893 Alternative initialization 894 Instead of having "init()" read in a configuration file by specifying a 895 file name or passing it a reference to an open filehandle 896 ("Log::Log4perl->init( \*FILE )"), you can also pass in a reference to a 897 string, containing the content of the file: 898 899 Log::Log4perl->init( \$config_text ); 900 901 Also, if you've got the "name=value" pairs of the configuration in a 902 hash, you can just as well initialize "Log::Log4perl" with a reference 903 to it: 904 905 my %key_value_pairs = ( 906 "log4perl.rootLogger" => "ERROR, LOGFILE", 907 "log4perl.appender.LOGFILE" => "Log::Log4perl::Appender::File", 908 ... 909 ); 910 911 Log::Log4perl->init( \%key_value_pairs ); 912 913 Or also you can use a URL, see below: 914 915 Using LWP to parse URLs 916 (This section borrowed from XML::DOM::Parser by T.J. Mather). 917 918 The init() function now also supports URLs, e.g. 919 *http://www.erols.com/enno/xsa.xml*. It uses LWP to download the file 920 and then calls parse() on the resulting string. By default it will use a 921 LWP::UserAgent that is created as follows: 922 923 use LWP::UserAgent; 924 $LWP_USER_AGENT = LWP::UserAgent->new; 925 $LWP_USER_AGENT->env_proxy; 926 927 Note that env_proxy reads proxy settings from environment variables, 928 which is what I need to do to get thru our firewall. If you want to use 929 a different LWP::UserAgent, you can set it with 930 931 Log::Log4perl::Config::set_LWP_UserAgent($my_agent); 932 933 Currently, LWP is used when the filename (passed to parsefile) starts 934 with one of the following URL schemes: http, https, ftp, wais, gopher, 935 or file (followed by a colon.) 936 937 Don't use this feature with init_and_watch(). 938 939 Automatic reloading of changed configuration files 940 Instead of just statically initializing Log::Log4perl via 941 942 Log::Log4perl->init($conf_file); 943 944 there's a way to have Log::Log4perl periodically check for changes in 945 the configuration and reload it if necessary: 946 947 Log::Log4perl->init_and_watch($conf_file, $delay); 948 949 In this mode, Log::Log4perl will examine the configuration file 950 $conf_file every $delay seconds for changes via the file's last 951 modification timestamp. If the file has been updated, it will be 952 reloaded and replace the current Log::Log4perl configuration. 953 954 The way this works is that with every logger function called (debug(), 955 is_debug(), etc.), Log::Log4perl will check if the delay interval has 956 expired. If so, it will run a -M file check on the configuration file. 957 If its timestamp has been modified, the current configuration will be 958 dumped and new content of the file will be loaded. 959 960 This convenience comes at a price, though: Calling time() with every 961 logging function call, especially the ones that are "suppressed" (!), 962 will slow down these Log4perl calls by about 40%. 963 964 To alleviate this performance hit a bit, "init_and_watch()" can be 965 configured to listen for a Unix signal to reload the configuration 966 instead: 967 968 Log::Log4perl->init_and_watch($conf_file, 'HUP'); 969 970 This will set up a signal handler for SIGHUP and reload the 971 configuration if the application receives this signal, e.g. via the 972 "kill" command: 973 974 kill -HUP pid 975 976 where "pid" is the process ID of the application. This will bring you 977 back to about 85% of Log::Log4perl's normal execution speed for 978 suppressed statements. For details, check out "Performance". For more 979 info on the signal handler, look for "SIGNAL MODE" in 980 Log::Log4perl::Config::Watch. 981 982 One thing to watch out for: If the configuration file contains a syntax 983 or other fatal error, a running application will stop with "die" if this 984 damaged configuration will be loaded during runtime, triggered either by 985 a signal or if the delay period expired and the change is detected. This 986 behaviour might change in the future. 987 988 Variable Substitution 989 To avoid having to retype the same expressions over and over again, 990 Log::Log4perl's configuration files support simple variable 991 substitution. New variables are defined simply by adding 992 993 varname = value 994 995 lines to the configuration file before using 996 997 ${varname} 998 999 afterwards to recall the assigned values. Here's an example: 1000 1001 layout_class = Log::Log4perl::Layout::PatternLayout 1002 layout_pattern = %d %F{1} %L> %m %n 1003 1004 log4perl.category.Bar.Twix = WARN, Logfile, Screen 1005 1006 log4perl.appender.Logfile = Log::Log4perl::Appender::File 1007 log4perl.appender.Logfile.filename = test.log 1008 log4perl.appender.Logfile.layout = ${layout_class} 1009 log4perl.appender.Logfile.layout.ConversionPattern = ${layout_pattern} 1010 1011 log4perl.appender.Screen = Log::Log4perl::Appender::Screen 1012 log4perl.appender.Screen.layout = ${layout_class} 1013 log4perl.appender.Screen.layout.ConversionPattern = ${layout_pattern} 1014 1015 This is a convenient way to define two appenders with the same layout 1016 without having to retype the pattern definitions. 1017 1018 Variable substitution via "${varname}" will first try to find an 1019 explicitely defined variable. If that fails, it will check your shell's 1020 environment for a variable of that name. If that also fails, the program 1021 will "die()". 1022 1023 Perl Hooks in the Configuration File 1024 If some of the values used in the Log4perl configuration file need to be 1025 dynamically modified by the program, use Perl hooks: 1026 1027 log4perl.appender.File.filename = \ 1028 sub { return getLogfileName(); } 1029 1030 Each value starting with the string "sub {..." is interpreted as Perl 1031 code to be executed at the time the application parses the configuration 1032 via "Log::Log4perl::init()". The return value of the subroutine is used 1033 by Log::Log4perl as the configuration value. 1034 1035 The Perl code is executed in the "main" package, functions in other 1036 packages have to be called in fully-qualified notation. 1037 1038 Here's another example, utilizing an environment variable as a username 1039 for a DBI appender: 1040 1041 log4perl.appender.DB.username = \ 1042 sub { $ENV{DB_USER_NAME } } 1043 1044 However, please note the difference between these code snippets and 1045 those used for user-defined conversion specifiers as discussed in 1046 Log::Log4perl::Layout::PatternLayout: While the snippets above are run 1047 *once* when "Log::Log4perl::init()" is called, the conversion specifier 1048 snippets are executed *each time* a message is rendered according to the 1049 PatternLayout. 1050 1051 SECURITY NOTE: this feature means arbitrary perl code can be embedded in 1052 the config file. In the rare case where the people who have access to 1053 your config file are different from the people who write your code and 1054 shouldn't have execute rights, you might want to set 1055 1056 Log::Log4perl::Config->allow_code(0); 1057 1058 before you call init(). Alternatively you can supply a restricted set of 1059 Perl opcodes that can be embedded in the config file as described in 1060 "Restricting what Opcodes can be in a Perl Hook". 1061 1062 Restricting what Opcodes can be in a Perl Hook 1063 The value you pass to Log::Log4perl::Config->allow_code() determines 1064 whether the code that is embedded in the config file is eval'd 1065 unrestricted, or eval'd in a Safe compartment. By default, a value of 1066 '1' is assumed, which does a normal 'eval' without any restrictions. A 1067 value of '0' however prevents any embedded code from being evaluated. 1068 1069 If you would like fine-grained control over what can and cannot be 1070 included in embedded code, then please utilize the following methods: 1071 1072 Log::Log4perl::Config->allow_code( $allow ); 1073 Log::Log4perl::Config->allowed_code_ops($op1, $op2, ... ); 1074 Log::Log4perl::Config->vars_shared_with_safe_compartment( [ \%vars | $package, \@vars ] ); 1075 Log::Log4perl::Config->allowed_code_ops_convenience_map( [ \%map | $name, \@mask ] ); 1076 1077 Log::Log4perl::Config->allowed_code_ops() takes a list of opcode masks 1078 that are allowed to run in the compartment. The opcode masks must be 1079 specified as described in Opcode: 1080 1081 Log::Log4perl::Config->allowed_code_ops(':subprocess'); 1082 1083 This example would allow Perl operations like backticks, system, fork, 1084 and waitpid to be executed in the compartment. Of course, you probably 1085 don't want to use this mask -- it would allow exactly what the Safe 1086 compartment is designed to prevent. 1087 1088 Log::Log4perl::Config->vars_shared_with_safe_compartment() takes the 1089 symbols which should be exported into the Safe compartment before the 1090 code is evaluated. The keys of this hash are the package names that the 1091 symbols are in, and the values are array references to the literal 1092 symbol names. For convenience, the default settings export the '%ENV' 1093 hash from the 'main' package into the compartment: 1094 1095 Log::Log4perl::Config->vars_shared_with_safe_compartment( 1096 main => [ '%ENV' ], 1097 ); 1098 1099 Log::Log4perl::Config->allowed_code_ops_convenience_map() is an accessor 1100 method to a map of convenience names to opcode masks. At present, the 1101 following convenience names are defined: 1102 1103 safe = [ ':browse' ] 1104 restrictive = [ ':default' ] 1105 1106 For convenience, if Log::Log4perl::Config->allow_code() is called with a 1107 value which is a key of the map previously defined with 1108 Log::Log4perl::Config->allowed_code_ops_convenience_map(), then the 1109 allowed opcodes are set according to the value defined in the map. If 1110 this is confusing, consider the following: 1111 1112 use Log::Log4perl; 1113 1114 my $config = <<'END'; 1115 log4perl.logger = INFO, Main 1116 log4perl.appender.Main = Log::Log4perl::Appender::File 1117 log4perl.appender.Main.filename = \ 1118 sub { "example" . getpwuid($<) . ".log" } 1119 log4perl.appender.Main.layout = Log::Log4perl::Layout::SimpleLayout 1120 END 1121 1122 $Log::Log4perl::Config->allow_code('restrictive'); 1123 Log::Log4perl->init( \$config ); # will fail 1124 $Log::Log4perl::Config->allow_code('safe'); 1125 Log::Log4perl->init( \$config ); # will succeed 1126 1127 The reason that the first call to ->init() fails is because the 1128 'restrictive' name maps to an opcode mask of ':default'. getpwuid() is 1129 not part of ':default', so ->init() fails. The 'safe' name maps to an 1130 opcode mask of ':browse', which allows getpwuid() to run, so ->init() 1131 succeeds. 1132 1133 allowed_code_ops_convenience_map() can be invoked in several ways: 1134 1135 allowed_code_ops_convenience_map() 1136 Returns the entire convenience name map as a hash reference in 1137 scalar context or a hash in list context. 1138 1139 allowed_code_ops_convenience_map( \%map ) 1140 Replaces the entire conveniece name map with the supplied hash 1141 reference. 1142 1143 allowed_code_ops_convenience_map( $name ) 1144 Returns the opcode mask for the given convenience name, or undef if 1145 no such name is defined in the map. 1146 1147 allowed_code_ops_convenience_map( $name, \@mask ) 1148 Adds the given name/mask pair to the convenience name map. If the 1149 name already exists in the map, it's value is replaced with the new 1150 mask. 1151 1152 as can vars_shared_with_safe_compartment(): 1153 1154 vars_shared_with_safe_compartment() 1155 Return the entire map of packages to variables as a hash reference 1156 in scalar context or a hash in list context. 1157 1158 vars_shared_with_safe_compartment( \%packages ) 1159 Replaces the entire map of packages to variables with the supplied 1160 hash reference. 1161 1162 vars_shared_with_safe_compartment( $package ) 1163 Returns the arrayref of variables to be shared for a specific 1164 package. 1165 1166 vars_shared_with_safe_compartment( $package, \@vars ) 1167 Adds the given package / varlist pair to the map. If the package 1168 already exists in the map, it's value is replaced with the new 1169 arrayref of variable names. 1170 1171 For more information on opcodes and Safe Compartments, see Opcode and 1172 Safe. 1173 1174 Changing the Log Level on a Logger 1175 Log4perl provides some internal functions for quickly adjusting the log 1176 level from within a running Perl program. 1177 1178 Now, some people might argue that you should adjust your levels from 1179 within an external Log4perl configuration file, but Log4perl is 1180 everybody's darling. 1181 1182 Typically run-time adjusting of levels is done at the beginning, or in 1183 response to some external input (like a "more logging" runtime command 1184 for diagnostics). 1185 1186 You get the log level from a logger object with: 1187 1188 $current_level = $logger->level(); 1189 1190 and you may set it with the same method, provided you first imported the 1191 log level constants, with: 1192 1193 use Log::Log4perl::Level; 1194 1195 Then you can set the level on a logger to one of the constants, 1196 1197 $logger->level($ERROR); # one of DEBUG, INFO, WARN, ERROR, FATAL 1198 1199 To increase the level of logging currently being done, use: 1200 1201 $logger->more_logging($delta); 1202 1203 and to decrease it, use: 1204 1205 $logger->less_logging($delta); 1206 1207 $delta must be a positive integer (for now, we may fix this later ;). 1208 1209 There are also two equivalent functions: 1210 1211 $logger->inc_level($delta); 1212 $logger->dec_level($delta); 1213 1214 They're included to allow you a choice in readability. Some folks will 1215 prefer more/less_logging, as they're fairly clear in what they do, and 1216 allow the programmer not to worry too much about what a Level is and 1217 whether a higher Level means more or less logging. However, other folks 1218 who do understand and have lots of code that deals with levels will 1219 probably prefer the inc_level() and dec_level() methods as they want to 1220 work with Levels and not worry about whether that means more or less 1221 logging. :) 1222 1223 That diatribe aside, typically you'll use more_logging() or inc_level() 1224 as such: 1225 1226 my $v = 0; # default level of verbosity. 1227 1228 GetOptions("v+" => \$v, ...); 1229 1230 $logger->more_logging($v); # inc logging level once for each -v in ARGV 1231 1232 Custom Log Levels 1233 First off, let me tell you that creating custom levels is heavily 1234 deprecated by the log4j folks. Indeed, instead of creating additional 1235 levels on top of the predefined DEBUG, INFO, WARN, ERROR and FATAL, you 1236 should use categories to control the amount of logging smartly, based on 1237 the location of the log-active code in the system. 1238 1239 Nevertheless, Log4perl provides a nice way to create custom levels via 1240 the create_custom_level() routine function. However, this must be done 1241 before the first call to init() or get_logger(). Say you want to create 1242 a NOTIFY logging level that comes after WARN (and thus before INFO). 1243 You'd do such as follows: 1244 1245 use Log::Log4perl; 1246 use Log::Log4perl::Level; 1247 1248 Log::Log4perl::Logger::create_custom_level("NOTIFY", "WARN"); 1249 1250 And that's it! create_custom_level() creates the following functions / 1251 variables for level FOO: 1252 1253 $FOO_INT # integer to use in toLevel() 1254 $logger->foo() # log function to log if level = FOO 1255 $logger->is_foo() # true if current level is >= FOO 1256 1257 These levels can also be used in your config file, but note that your 1258 config file probably won't be portable to another log4perl or log4j 1259 environment unless you've made the appropriate mods there too. 1260 1261 System-wide log levels 1262 As a fairly drastic measure to decrease (or increase) the logging level 1263 all over the system with one single configuration option, use the 1264 "threshold" keyword in the Log4perl configuration file: 1265 1266 log4perl.threshold = ERROR 1267 1268 sets the system-wide (or hierarchy-wide according to the log4j 1269 documentation) to ERROR and therefore deprives every logger in the 1270 system of the right to log lower-prio messages. 1271 1272 Easy Mode 1273 For teaching purposes (especially for [1]), I've put ":easy" mode into 1274 "Log::Log4perl", which just initializes a single root logger with a 1275 defined priority and a screen appender including some nice standard 1276 layout: 1277 1278 ### Initialization Section 1279 use Log::Log4perl qw(:easy); 1280 Log::Log4perl->easy_init($ERROR); # Set priority of root logger to ERROR 1281 1282 ### Application Section 1283 my $logger = get_logger(); 1284 $logger->fatal("This will get logged."); 1285 $logger->debug("This won't."); 1286 1287 This will dump something like 1288 1289 2002/08/04 11:43:09 ERROR> script.pl:16 main::function - This will get logged. 1290 1291 to the screen. While this has been proven to work well familiarizing 1292 people with "Log::Logperl" slowly, effectively avoiding to clobber them 1293 over the head with a plethora of different knobs to fiddle with 1294 (categories, appenders, levels, layout), the overall mission of 1295 "Log::Log4perl" is to let people use categories right from the start to 1296 get used to the concept. So, let's keep this one fairly hidden in the 1297 man page (congrats on reading this far :). 1298 1299 Stealth loggers 1300 Sometimes, people are lazy. If you're whipping up a 50-line script and 1301 want the comfort of Log::Log4perl without having the burden of carrying 1302 a separate log4perl.conf file or a 5-liner defining that you want to 1303 append your log statements to a file, you can use the following 1304 features: 1305 1306 use Log::Log4perl qw(:easy); 1307 1308 Log::Log4perl->easy_init( { level => $DEBUG, 1309 file => ">>test.log" } ); 1310 1311 # Logs to test.log via stealth logger 1312 DEBUG("Debug this!"); 1313 INFO("Info this!"); 1314 WARN("Warn this!"); 1315 ERROR("Error this!"); 1316 1317 some_function(); 1318 1319 sub some_function { 1320 # Same here 1321 FATAL("Fatal this!"); 1322 } 1323 1324 In ":easy" mode, "Log::Log4perl" will instantiate a *stealth logger* 1325 named $_default_logger and import it into the current package. Also, it 1326 will introduce the convenience functions "TRACE", "DEBUG()", "INFO()", 1327 "WARN()", "ERROR()", "FATAL()", and "ALWAYS" into the package namespace. 1328 These functions simply take messages as arguments and forward them to 1329 "_default_logger->debug()", "_default_logger->info()" and so on. If a 1330 message should never be blocked, regardless of the log level, use the 1331 "ALWAYS" function which corresponds to a log level of "OFF": 1332 1333 ALWAYS "This will be printed regardless of the log level"; 1334 1335 The "easy_init" method can be called with a single level value to create 1336 a STDERR appender and a root logger as in 1337 1338 Log::Log4perl->easy_init($DEBUG); 1339 1340 or, as shown below (and in the example above) with a reference to a 1341 hash, specifying values for "level" (the logger's priority), "file" (the 1342 appender's data sink), "category" (the logger's category> and "layout" 1343 for the appender's pattern layout specification. All key-value pairs are 1344 optional, they default to $DEBUG for "level", "STDERR" for "file", "" 1345 (root category) for "category" and "%d %m%n" for "layout": 1346 1347 Log::Log4perl->easy_init( { level => $DEBUG, 1348 file => ">test.log", 1349 category => "Bar::Twix", 1350 layout => '%F{1}-%L-%M: %m%n' } ); 1351 1352 The "file" parameter takes file names preceded by ">" (overwrite) and 1353 ">>" (append) as arguments. This will cause 1354 "Log::Log4perl::Appender::File" appenders to be created behind the 1355 scenes. Also the keywords "STDOUT" and "STDERR" (no ">" or ">>") are 1356 recognized, which will utilize and configure 1357 "Log::Log4perl::Appender::Screen" appropriately. 1358 1359 If a file appender receives Unicode strings, use 1360 1361 file => ":utf8> test.log" 1362 1363 to establish a utf8 line discpline on the file, otherwise you'll get a 1364 'wide character in print' warning message and probably not what you'd 1365 expect as output. 1366 1367 The stealth loggers can be used in different packages, you just need to 1368 make sure you're calling the "use" function in every package you're 1369 using "Log::Log4perl"'s easy services: 1370 1371 package Bar::Twix; 1372 use Log::Log4perl qw(:easy); 1373 sub eat { DEBUG("Twix mjam"); } 1374 1375 package Bar::Mars; 1376 use Log::Log4perl qw(:easy); 1377 sub eat { INFO("Mars mjam"); } 1378 1379 package main; 1380 1381 use Log::Log4perl qw(:easy); 1382 1383 Log::Log4perl->easy_init( { level => $DEBUG, 1384 file => ">>test.log", 1385 category => "Bar::Twix", 1386 layout => '%F{1}-%L-%M: %m%n' }, 1387 { level => $DEBUG, 1388 file => "STDOUT", 1389 category => "Bar::Mars", 1390 layout => '%m%n' }, 1391 ); 1392 Bar::Twix::eat(); 1393 Bar::Mars::eat(); 1394 1395 As shown above, "easy_init()" will take any number of different logger 1396 definitions as hash references. 1397 1398 Also, stealth loggers feature the functions "LOGWARN()", "LOGDIE()", and 1399 "LOGEXIT()", combining a logging request with a subsequent Perl warn() 1400 or die() or exit() statement. So, for example 1401 1402 if($all_is_lost) { 1403 LOGDIE("Terrible Problem"); 1404 } 1405 1406 will log the message if the package's logger is at least "FATAL" but 1407 "die()" (including the traditional output to STDERR) in any case 1408 afterwards. 1409 1410 See "Log and die or warn" for the similar "logdie()" and "logwarn()" 1411 functions of regular (i.e non-stealth) loggers. 1412 1413 Similarily, "LOGCARP()", "LOGCLUCK()", "LOGCROAK()", and "LOGCONFESS()" 1414 are provided in ":easy" mode, facilitating the use of "logcarp()", 1415 "logcluck()", "logcroak()", and "logconfess()" with stealth loggers. 1416 1417 When using Log::Log4perl in easy mode, please make sure you understand 1418 the implications of "Pitfalls with Categories". 1419 1420 By the way, these convenience functions perform exactly as fast as the 1421 standard Log::Log4perl logger methods, there's *no* performance penalty 1422 whatsoever. 1423 1424 Nested Diagnostic Context (NDC) 1425 If you find that your application could use a global (thread-specific) 1426 data stack which your loggers throughout the system have easy access to, 1427 use Nested Diagnostic Contexts (NDCs). Also check out "Mapped Diagnostic 1428 Context (MDC)", this might turn out to be even more useful. 1429 1430 For example, when handling a request of a web client, it's probably 1431 useful to have the user's IP address available in all log statements 1432 within code dealing with this particular request. Instead of passing 1433 this piece of data around between your application functions, you can 1434 just use the global (but thread-specific) NDC mechanism. It allows you 1435 to push data pieces (scalars usually) onto its stack via 1436 1437 Log::Log4perl::NDC->push("San"); 1438 Log::Log4perl::NDC->push("Francisco"); 1439 1440 and have your loggers retrieve them again via the "%x" placeholder in 1441 the PatternLayout. With the stack values above and a PatternLayout 1442 format like "%x %m%n", the call 1443 1444 $logger->debug("rocks"); 1445 1446 will end up as 1447 1448 San Francisco rocks 1449 1450 in the log appender. 1451 1452 The stack mechanism allows for nested structures. Just make sure that at 1453 the end of the request, you either decrease the stack one by one by 1454 calling 1455 1456 Log::Log4perl::NDC->pop(); 1457 Log::Log4perl::NDC->pop(); 1458 1459 or clear out the entire NDC stack by calling 1460 1461 Log::Log4perl::NDC->remove(); 1462 1463 Even if you should forget to do that, "Log::Log4perl" won't grow the 1464 stack indefinitely, but limit it to a maximum, defined in 1465 "Log::Log4perl::NDC" (currently 5). A call to "push()" on a full stack 1466 will just replace the topmost element by the new value. 1467 1468 Again, the stack is always available via the "%x" placeholder in the 1469 Log::Log4perl::Layout::PatternLayout class whenever a logger fires. It 1470 will replace "%x" by the blank-separated list of the values on the 1471 stack. It does that by just calling 1472 1473 Log::Log4perl::NDC->get(); 1474 1475 internally. See details on how this standard log4j feature is 1476 implemented in Log::Log4perl::NDC. 1477 1478 Mapped Diagnostic Context (MDC) 1479 Just like the previously discussed NDC stores thread-specific 1480 information in a stack structure, the MDC implements a hash table to 1481 store key/value pairs in. 1482 1483 The static method 1484 1485 Log::Log4perl::MDC->put($key, $value); 1486 1487 stores $value under a key $key, with which it can be retrieved later 1488 (possibly in a totally different part of the system) by calling the 1489 "get" method: 1490 1491 my $value = Log::Log4perl::MDC->get($key); 1492 1493 If no value has been stored previously under $key, the "get" method will 1494 return "undef". 1495 1496 Typically, MDC values are retrieved later on via the "%X{...}" 1497 placeholder in "Log::Log4perl::Layout::PatternLayout". If the "get()" 1498 method returns "undef", the placeholder will expand to the string 1499 "[undef]". 1500 1501 An application taking a web request might store the remote host like 1502 1503 Log::Log4perl::MDC->put("remote_host", $r->headers("HOST")); 1504 1505 at its beginning and if the appender's layout looks something like 1506 1507 log4perl.appender.Logfile.layout.ConversionPattern = %X{remote_host}: %m%n 1508 1509 then a log statement like 1510 1511 DEBUG("Content delivered"); 1512 1513 will log something like 1514 1515 adsl-63.dsl.snf.pacbell.net: Content delivered 1516 1517 later on in the program. 1518 1519 For details, please check Log::Log4perl::MDC. 1520 1521 Resurrecting hidden Log4perl Statements 1522 Sometimes scripts need to be deployed in environments without having 1523 Log::Log4perl installed yet. On the other hand, you dont't want to live 1524 without your Log4perl statements -- they're gonna come in handy later. 1525 1526 So, just deploy your script with Log4perl statements commented out with 1527 the pattern "###l4p", like in 1528 1529 ###l4p DEBUG "It works!"; 1530 # ... 1531 ###l4p INFO "Really!"; 1532 1533 If Log::Log4perl is available, use the ":resurrect" tag to have Log4perl 1534 resurrect those burried statements before the script starts running: 1535 1536 use Log::Log4perl qw(:resurrect :easy); 1537 1538 ###l4p Log::Log4perl->easy_init($DEBUG); 1539 ###l4p DEBUG "It works!"; 1540 # ... 1541 ###l4p INFO "Really!"; 1542 1543 This will have a source filter kick in and indeed print 1544 1545 2004/11/18 22:08:46 It works! 1546 2004/11/18 22:08:46 Really! 1547 1548 In environments lacking Log::Log4perl, just comment out the first line 1549 and the script will run nevertheless (but of course without logging): 1550 1551 # use Log::Log4perl qw(:resurrect :easy); 1552 1553 ###l4p Log::Log4perl->easy_init($DEBUG); 1554 ###l4p DEBUG "It works!"; 1555 # ... 1556 ###l4p INFO "Really!"; 1557 1558 because everything's a regular comment now. Alternatively, put the magic 1559 Log::Log4perl comment resurrection line into your shell's PERL5OPT 1560 environment variable, e.g. for bash: 1561 1562 set PERL5OPT=-MLog::Log4perl=:resurrect,:easy 1563 export PERL5OPT 1564 1565 This will awaken the giant within an otherwise silent script like the 1566 following: 1567 1568 #!/usr/bin/perl 1569 1570 ###l4p Log::Log4perl->easy_init($DEBUG); 1571 ###l4p DEBUG "It works!"; 1572 1573 As of "Log::Log4perl" 1.12, you can even force *all* modules loaded by a 1574 script to have their hidden Log4perl statements resurrected. For this to 1575 happen, load "Log::Log4perl::Resurrector" *before* loading any modules: 1576 1577 use Log::Log4perl qw(:easy); 1578 use Log::Log4perl::Resurrector; 1579 1580 use Foobar; # All hidden Log4perl statements in here will 1581 # be uncommented before Foobar gets loaded. 1582 1583 Log::Log4perl->easy_init($DEBUG); 1584 ... 1585 1586 Check the "Log::Log4perl::Resurrector" manpage for more details. 1587 1588 Access defined appenders 1589 All appenders defined in the configuration file or via Perl code can be 1590 retrieved by the "appender_by_name()" class method. This comes in handy 1591 if you want to manipulate or query appender properties after the 1592 Log4perl configuration has been loaded via "init()". 1593 1594 Note that internally, Log::Log4perl uses the "Log::Log4perl::Appender" 1595 wrapper class to control the real appenders (like 1596 "Log::Log4perl::Appender::File" or "Log::Dispatch::FileRotate"). The 1597 "Log::Log4perl::Appender" class has an "appender" attribute, pointing to 1598 the real appender. 1599 1600 The reason for this is that external appenders like 1601 "Log::Dispatch::FileRotate" don't support all of Log::Log4perl's 1602 appender control mechanisms (like appender thresholds). 1603 1604 The previously mentioned method "appender_by_name()" returns a 1605 referrence to the *real* appender object. If you want access to the 1606 wrapper class (e.g. if you want to modify the appender's threshold), use 1607 the hash $Log::Log4perl::Logger::APPENDER_BY_NAME{...} instead, which 1608 holds references all appender wrapper objects. 1609 1610 Modify appender thresholds 1611 To conveniently adjust appender thresholds (e.g. because a script uses 1612 more_logging()), use 1613 1614 # decrease thresholds of all appenders 1615 Log::Log4perl->appender_thresholds_adjust(-1); 1616 1617 This will decrease the thresholds of all appenders in the system by one 1618 level, i.e. WARN becomes INFO, INFO becomes DEBUG, etc. To only modify 1619 selected ones, use 1620 1621 # decrease thresholds of all appenders 1622 Log::Log4perl->appender_thresholds_adjust(-1, ['AppName1', ...]); 1623 1624 and pass the names of affected appenders in a ref to an array. 1625 1626Advanced configuration within Perl 1627 Initializing Log::Log4perl can certainly also be done from within Perl. 1628 At last, this is what "Log::Log4perl::Config" does behind the scenes. 1629 Log::Log4perl's configuration file parsers are using a publically 1630 available API to set up Log::Log4perl's categories, appenders and 1631 layouts. 1632 1633 Here's an example on how to configure two appenders with the same layout 1634 in Perl, without using a configuration file at all: 1635 1636 ######################## 1637 # Initialization section 1638 ######################## 1639 use Log::Log4perl; 1640 use Log::Log4perl::Layout; 1641 use Log::Log4perl::Level; 1642 1643 # Define a category logger 1644 my $log = Log::Log4perl->get_logger("Foo::Bar"); 1645 1646 # Define a layout 1647 my $layout = Log::Log4perl::Layout::PatternLayout->new("[%r] %F %L %m%n"); 1648 1649 # Define a file appender 1650 my $file_appender = Log::Log4perl::Appender->new( 1651 "Log::Log4perl::Appender::File", 1652 name => "filelog", 1653 filename => "/tmp/my.log"); 1654 1655 # Define a stdout appender 1656 my $stdout_appender = Log::Log4perl::Appender->new( 1657 "Log::Log4perl::Appender::Screen", 1658 name => "screenlog", 1659 stderr => 0); 1660 1661 # Have both appenders use the same layout (could be different) 1662 $stdout_appender->layout($layout); 1663 $file_appender->layout($layout); 1664 1665 $log->add_appender($stdout_appender); 1666 $log->add_appender($file_appender); 1667 $log->level($INFO); 1668 1669 Please note the class of the appender object is passed as a *string* to 1670 "Log::Log4perl::Appender" in the *first* argument. Behind the scenes, 1671 "Log::Log4perl::Appender" will create the necessary 1672 "Log::Log4perl::Appender::*" (or "Log::Dispatch::*") object and pass 1673 along the name value pairs we provided to 1674 "Log::Log4perl::Appender->new()" after the first argument. 1675 1676 The "name" value is optional and if you don't provide one, 1677 "Log::Log4perl::Appender->new()" will create a unique one for you. The 1678 names and values of additional parameters are dependent on the 1679 requirements of the particular appender class and can be looked up in 1680 their manual pages. 1681 1682 A side note: In case you're wondering if 1683 "Log::Log4perl::Appender->new()" will also take care of the "min_level" 1684 argument to the "Log::Dispatch::*" constructors called behind the scenes 1685 -- yes, it does. This is because we want the "Log::Dispatch" objects to 1686 blindly log everything we send them ("debug" is their lowest setting) 1687 because *we* in "Log::Log4perl" want to call the shots and decide on 1688 when and what to log. 1689 1690 The call to the appender's *layout()* method specifies the format (as a 1691 previously created "Log::Log4perl::Layout::PatternLayout" object) in 1692 which the message is being logged in the specified appender. If you 1693 don't specify a layout, the logger will fall back to 1694 "Log::Log4perl::SimpleLayout", which logs the debug level, a hyphen (-) 1695 and the log message. 1696 1697 Layouts are objects, here's how you create them: 1698 1699 # Create a simple layout 1700 my $simple = Log::Log4perl::SimpleLayout(); 1701 1702 # create a flexible layout: 1703 # ("yyyy/MM/dd hh:mm:ss (file:lineno)> message\n") 1704 my $pattern = Log::Log4perl::Layout::PatternLayout("%d (%F:%L)> %m%n"); 1705 1706 Every appender has exactly one layout assigned to it. You assign the 1707 layout to the appender using the appender's "layout()" object: 1708 1709 my $app = Log::Log4perl::Appender->new( 1710 "Log::Log4perl::Appender::Screen", 1711 name => "screenlog", 1712 stderr => 0); 1713 1714 # Assign the previously defined flexible layout 1715 $app->layout($pattern); 1716 1717 # Add the appender to a previously defined logger 1718 $logger->add_appender($app); 1719 1720 # ... and you're good to go! 1721 $logger->debug("Blah"); 1722 # => "2002/07/10 23:55:35 (test.pl:207)> Blah\n" 1723 1724 It's also possible to remove appenders from a logger: 1725 1726 $logger->remove_appender($appender_name); 1727 1728 will remove an appender, specified by name, from a given logger. Please 1729 note that this does *not* remove an appender from the system. 1730 1731 To eradicate an appender from the system, you need to call 1732 "Log::Log4perl->eradicate_appender($appender_name)" which will first 1733 remove the appender from every logger in the system and then will delete 1734 all references Log4perl holds to it. 1735 1736How about Log::Dispatch::Config? 1737 Tatsuhiko Miyagawa's "Log::Dispatch::Config" is a very clever simplified 1738 logger implementation, covering some of the *log4j* functionality. Among 1739 the things that "Log::Log4perl" can but "Log::Dispatch::Config" can't 1740 are: 1741 1742 * You can't assign categories to loggers. For small systems that's 1743 fine, but if you can't turn off and on detailed logging in only a 1744 tiny subsystem of your environment, you're missing out on a majorly 1745 useful log4j feature. 1746 1747 * Defining appender thresholds. Important if you want to solve 1748 problems like "log all messages of level FATAL to STDERR, plus log 1749 all DEBUG messages in "Foo::Bar" to a log file". If you don't have 1750 appenders thresholds, there's no way to prevent cluttering STDERR 1751 with DEBUG messages. 1752 1753 * PatternLayout specifications in accordance with the standard (e.g. 1754 "%d{HH:mm}"). 1755 1756 Bottom line: Log::Dispatch::Config is fine for small systems with simple 1757 logging requirements. However, if you're designing a system with lots of 1758 subsystems which you need to control independantly, you'll love the 1759 features of "Log::Log4perl", which is equally easy to use. 1760 1761Using Log::Log4perl from wrapper classes 1762 If you don't use "Log::Log4perl" as described above, but from a wrapper 1763 class (like your own Logging class which in turn uses "Log::Log4perl"), 1764 the pattern layout will generate wrong data for %F, %C, %L and the like. 1765 Reason for this is that "Log::Log4perl"'s loggers assume a static caller 1766 depth to the application that's using them. If you're using one (or 1767 more) wrapper classes, "Log::Log4perl" will indicate where your logger 1768 classes called the loggers, not where your application called your 1769 wrapper, which is probably what you want in this case. But don't 1770 dispair, there's a solution: Just increase the value of 1771 $Log::Log4perl::caller_depth (defaults to 0) by one for every wrapper 1772 that's in between your application and "Log::Log4perl", then 1773 "Log::Log4perl" will compensate for the difference. 1774 1775 Also, note that if you're using a subclass of Log4perl, like 1776 1777 package MyL4pWrapper; 1778 use Log::Log4perl; 1779 our @ISA = qw(Log::Log4perl); 1780 1781 and you want to call get_logger() in your code, like 1782 1783 use MyL4pWrapper; 1784 1785 sub some_function { 1786 my $logger = MyL4pWrapper->get_logger(__PACKAGE__); 1787 $logger->debug("Hey, there."); 1788 } 1789 1790 you have to explicitly spell out the category, as in __PACKAGE__ above. 1791 You can't rely on 1792 1793 # Don't do that! 1794 MyL4pWrapper->get_logger(); 1795 1796 and assume that Log4perl will take the class of the current package as 1797 the category. (Reason behind this is that Log4perl will think you're 1798 calling "get_logger("MyL4pWrapper")" and take "MyL4pWrapper" as the 1799 category.) 1800 1801Access to Internals 1802 The following methods are only of use if you want to peek/poke in the 1803 internals of Log::Log4perl. Be careful not to disrupt its inner 1804 workings. 1805 1806 "Log::Log4perl->appenders()" 1807 To find out which appenders are currently defined (not only for a 1808 particular logger, but overall), a "appenders()" method is available 1809 to return a reference to a hash mapping appender names to their 1810 Log::Log4perl::Appender object references. 1811 1812Dirty Tricks 1813 infiltrate_lwp() 1814 The famous LWP::UserAgent module isn't Log::Log4perl-enabled. Often, 1815 though, especially when tracing Web-related problems, it would be 1816 helpful to get some insight on what's happening inside 1817 LWP::UserAgent. Ideally, LWP::UserAgent would even play along in the 1818 Log::Log4perl framework. 1819 1820 A call to "Log::Log4perl->infiltrate_lwp()" does exactly this. In a 1821 very rude way, it pulls the rug from under LWP::UserAgent and 1822 transforms its "debug/conn" messages into "debug()" calls of loggers 1823 of the category "LWP::UserAgent". Similarily, "LWP::UserAgent"'s 1824 "trace" messages are turned into "Log::Log4perl"'s "info()" method 1825 calls. 1826 1827 Suppressing 'duplicate' LOGDIE messages 1828 If a script with a simple Log4perl configuration uses logdie() to 1829 catch errors and stop processing, as in 1830 1831 use Log::Log4perl qw(:easy) ; 1832 Log::Log4perl->easy_init($DEBUG); 1833 1834 shaky_function() or LOGDIE "It failed!"; 1835 1836 there's a cosmetic problem: The message gets printed twice: 1837 1838 2005/07/10 18:37:14 It failed! 1839 It failed! at ./t line 12 1840 1841 The obvious solution is to use LOGEXIT() instead of LOGDIE(), but 1842 there's also a special tag for Log4perl that suppresses the second 1843 message: 1844 1845 use Log::Log4perl qw(:no_extra_logdie_message); 1846 1847 This causes logdie() and logcroak() to call exit() instead of die(). 1848 To modify the script exit code in these occasions, set the variable 1849 $Log::Log4perl::LOGEXIT_CODE to the desired value, the default is 1. 1850 1851EXAMPLE 1852 A simple example to cut-and-paste and get started: 1853 1854 use Log::Log4perl qw(get_logger); 1855 1856 my $conf = q( 1857 log4perl.category.Bar.Twix = WARN, Logfile 1858 log4perl.appender.Logfile = Log::Log4perl::Appender::File 1859 log4perl.appender.Logfile.filename = test.log 1860 log4perl.appender.Logfile.layout = \ 1861 Log::Log4perl::Layout::PatternLayout 1862 log4perl.appender.Logfile.layout.ConversionPattern = %d %F{1} %L> %m %n 1863 ); 1864 1865 Log::Log4perl::init(\$conf); 1866 1867 my $logger = get_logger("Bar::Twix"); 1868 $logger->error("Blah"); 1869 1870 This will log something like 1871 1872 2002/09/19 23:48:15 t1 25> Blah 1873 1874 to the log file "test.log", which Log4perl will append to or create it 1875 if it doesn't exist already. 1876 1877INSTALLATION 1878 If you want to use external appenders provided with "Log::Dispatch", you 1879 need to install "Log::Dispatch" (2.00 or better) from CPAN, which itself 1880 depends on "Attribute-Handlers" and "Params-Validate". And a lot of 1881 other modules, that's the reason why we're now shipping Log::Log4perl 1882 with its own standard appenders and only if you wish to use additional 1883 ones, you'll have to go through the "Log::Dispatch" installation 1884 process. 1885 1886 Log::Log4perl needs "Test::More", "Test::Harness" and "File::Spec", but 1887 they already come with fairly recent versions of perl. If not, 1888 everything's automatically fetched from CPAN if you're using the CPAN 1889 shell (CPAN.pm), because they're listed as dependencies. 1890 1891 "Time::HiRes" (1.20 or better) is required only if you need the 1892 fine-grained time stamps of the %r parameter in 1893 "Log::Log4perl::Layout::PatternLayout". 1894 1895 Manual installation works as usual with 1896 1897 perl Makefile.PL 1898 make 1899 make test 1900 make install 1901 1902 If you're running Windows (98, 2000, NT, XP etc.), and you're too lazy 1903 to rummage through all of Log-Log4perl's dependencies, don't despair: 1904 We're providing a PPM package which installs easily with your 1905 Activestate Perl. Check 1906 "how_can_i_install_log__log4perl_on_microsoft_windows" in 1907 Log::Log4perl::FAQ for details. 1908 1909DEVELOPMENT 1910 Log::Log4perl is still being actively developed. We will always make 1911 sure the test suite (approx. 500 cases) will pass, but there might still 1912 be bugs. please check http://log4perl.sourceforge.net for the latest 1913 release. The api has reached a mature state, we will not change it 1914 unless for a good reason. 1915 1916 Bug reports and feedback are always welcome, just email them to our 1917 mailing list shown in the AUTHORS section. We're usually addressing them 1918 immediately. 1919 1920REFERENCES 1921 [1] Michael Schilli, "Retire your debugger, log smartly with 1922 Log::Log4perl!", Tutorial on perl.com, 09/2002, 1923 http://www.perl.com/pub/a/2002/09/11/log4perl.html 1924 1925 [2] Ceki Gülcü, "Short introduction to log4j", 1926 http://jakarta.apache.org/log4j/docs/manual.html 1927 1928 [3] Vipan Singla, "Don't Use System.out.println! Use Log4j.", 1929 http://www.vipan.com/htdocs/log4jhelp.html 1930 1931 [4] The Log::Log4perl project home page: http://log4perl.sourceforge.net 1932 1933SEE ALSO 1934 Log::Log4perl::Config, Log::Log4perl::Appender, 1935 Log::Log4perl::Layout::PatternLayout, 1936 Log::Log4perl::Layout::SimpleLayout, Log::Log4perl::Level, 1937 Log::Log4perl::JavaMap Log::Log4perl::NDC, 1938 1939AUTHORS 1940 Please send bug reports or requests for enhancements to the authors via 1941 our 1942 1943 MAILING LIST (questions, bug reports, suggestions/patches): 1944 log4perl-devel@lists.sourceforge.net 1945 1946 Authors (please contact them via the list above, not directly) 1947 Mike Schilli <m@perlmeister.com> 1948 Kevin Goess <cpan@goess.org> 1949 1950 Contributors (in alphabetical order): 1951 Ateeq Altaf, Cory Bennett, Jeremy Bopp, Hutton Davidson, Chris R. 1952 Donnelly, Matisse Enzer, Hugh Esco, James FitzGibbon, Carl Franks, 1953 Dennis Gregorovic, Paul Harrington, David Hull, Robert Jacobson, 1954 Jeff Macdonald, Markus Peter, Brett Rann, Erik Selberg, Aaron 1955 Straup Cope, Lars Thegler, David Viner, Mac Yang. 1956 1957COPYRIGHT AND LICENSE 1958 Copyright 2002-2007 by Mike Schilli <m@perlmeister.com> and Kevin Goess 1959 <cpan@goess.org>. 1960 1961 This library is free software; you can redistribute it and/or modify it 1962 under the same terms as Perl itself. 1963 1964