SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from RedHat EL 8 perl-Log-Log4perl-1.50-1.el8.noarch.rpm

Log::Log4perl

Section: User Contributed Perl Documentation (3)
Updated: 2020-07-22
Index 

NAME

Log::Log4perl - Log4j implementation for Perl 

SYNOPSIS

                # Easy mode if you like it simple ...    use Log::Log4perl qw(:easy);    Log::Log4perl->easy_init($ERROR);    DEBUG "This doesn't go anywhere";    ERROR "This gets logged";        # ... or standard mode for more features:    Log::Log4perl::init('/etc/log4perl.conf');        --or--            # Check config every 10 secs    Log::Log4perl::init_and_watch('/etc/log4perl.conf',10);    --then--        $logger = Log::Log4perl->get_logger('house.bedrm.desk.topdrwr');        $logger->debug('this is a debug message');    $logger->info('this is an info message');    $logger->warn('etc');    $logger->error('..');    $logger->fatal('..');        #####/etc/log4perl.conf###############################    log4perl.logger.house              = WARN,  FileAppndr1    log4perl.logger.house.bedroom.desk = DEBUG, FileAppndr1        log4perl.appender.FileAppndr1      = Log::Log4perl::Appender::File    log4perl.appender.FileAppndr1.filename = desk.log     log4perl.appender.FileAppndr1.layout   = \                            Log::Log4perl::Layout::SimpleLayout    ######################################################
 

ABSTRACT

Log::Log4perl provides a powerful logging API for your application 

DESCRIPTION

Log::Log4perl lets you remote-control and fine-tune the logging behaviourof your system from the outside. It implements the widely popular (Java-based) Log4j logging package in pure Perl.

For a detailed tutorial on Log::Log4perl usage, please read

<http://www.perl.com/pub/a/2002/09/11/log4perl.html>

Logging beats a debugger if you want to know what's going on in your code during runtime. However, traditional logging packagesare too static and generate a flood of log messages in your log filesthat won't help you.

"Log::Log4perl" is different. It allows you to control the number of logging messages generated at three different levels:

*
At a central location in your system (either in a configuration file orin the startup code) you specify which components (classes, functions) of your system should generate logs.
*
You specify how detailed the logging of these components should be byspecifying logging levels.
*
You also specify which so-called appenders you want to feed yourlog messages to (``Print it to the screen and also append it to /tmp/my.log'')and which format (``Write the date first, then the file name and line number, and then the log message'') they should be in.

This is a very powerful and flexible mechanism. You can turn on and offyour logs at any time, specify the level of detail and make thatdependent on the subsystem that's currently executed.

Let me give you an example: You might find out that your system has a problem in the "MySystem::Helpers::ScanDir"component. Turning on detailed debugging logs all over the system wouldgenerate a flood of useless log messages and bog your system down beyondrecognition. With "Log::Log4perl", however, you can tell the system:"Continue to log only severe errors to the log file. Open a secondlog file, turn on full debug logs in the "MySystem::Helpers::ScanDir"component and dump all messages originating from there into the newlog file". And all this is possible by just changing the parametersin a configuration file, which your system can re-read even while it's running! 

How to use it

The "Log::Log4perl" package can be initialized in two ways: Eithervia Perl commands or via a "log4j"-style configuration file. 

Initialize via a configuration file

This is the easiest way to prepare your system for using"Log::Log4perl". Use a configuration file like this:

    ############################################################    # A simple root logger with a Log::Log4perl::Appender::File     # file appender in Perl.    ############################################################    log4perl.rootLogger=ERROR, LOGFILE        log4perl.appender.LOGFILE=Log::Log4perl::Appender::File    log4perl.appender.LOGFILE.filename=/var/log/myerrs.log    log4perl.appender.LOGFILE.mode=append        log4perl.appender.LOGFILE.layout=PatternLayout    log4perl.appender.LOGFILE.layout.ConversionPattern=[%r] %F %L %c - %m%n

These lines define your standard logger that's appending severeerrors to "/var/log/myerrs.log", using the format

    [millisecs] source-filename line-number class - message newline

Assuming that this configuration file is saved as "log.conf", you need to read it in the startup section of your code, using the followingcommands:

  use Log::Log4perl;  Log::Log4perl->init("log.conf");

After that's done somewhere in the code, you can retrievelogger objects anywhere in the code. Note thatthere's no need to carry any logger references around with your functions and methods. You can get a logger anytime via a singletonmechanism:

    package My::MegaPackage;    use  Log::Log4perl;    sub some_method {        my($param) = @_;        my $log = Log::Log4perl->get_logger("My::MegaPackage");        $log->debug("Debug message");        $log->info("Info message");        $log->error("Error message");        ...    }

With the configuration file above, "Log::Log4perl" will write``Error message'' to the specified log file, but won't do anything for the "debug()" and "info()" calls, because the log level has been setto "ERROR" for all components in the first line of configuration file shown above.

Why "Log::Log4perl->get_logger" andnot "Log::Log4perl->new"? We don't want to create a newobject every time. Usually in OO-Programming, you create an objectonce and use the reference to it to call its methods. However,this requires that you pass around the object to all functionsand the last thing we want is pollute each and every function/methodwe're using with a handle to the "Logger":

    sub function {  # Brrrr!!        my($logger, $some, $other, $parameters) = @_;    }

Instead, if a function/method wants a reference to the logger, itjust calls the Logger's static "get_logger($category)" method to obtaina reference to the one and only possible logger object ofa certain category.That's called a singleton if you're a Gamma fan.

How does the logger knowwhich messages it is supposed to log and which ones to suppress?"Log::Log4perl" works with inheritance: The config file above didn't specify anything about "My::MegaPackage". And yet, we've defined a logger of the category "My::MegaPackage".In this case, "Log::Log4perl" will walk up the namespace hierarchy("My" and then we're at the root) to figure out if a log level isdefined somewhere. In the case above, the log level at the root(root always defines a log level, but not necessarily an appender)defines that the log level is supposed to be "ERROR" --- meaning that DEBUGand INFO messages are suppressed. Note that this 'inheritance' isunrelated to Perl's class inheritance, it is merely related to thelogger namespace.By the way, if you're ever in doubt about what a logger's category is, use "$logger->category()" to retrieve it. 

Log Levels

There are six predefined log levels: "FATAL", "ERROR", "WARN", "INFO","DEBUG", and "TRACE" (in descending priority). Your configured logging levelhas to at least match the priority of the logging message.

If your configured logging level is "WARN", then messages logged with "info()", "debug()", and "trace()" will be suppressed. "fatal()", "error()" and "warn()" will make their way through,because their priority is higher or equal than the configured setting.

Instead of calling the methods

    $logger->trace("...");  # Log a trace message    $logger->debug("...");  # Log a debug message    $logger->info("...");   # Log a info message    $logger->warn("...");   # Log a warn message    $logger->error("...");  # Log a error message    $logger->fatal("...");  # Log a fatal message

you could also call the "log()" method with the appropriate levelusing the constants defined in "Log::Log4perl::Level":

    use Log::Log4perl::Level;    $logger->log($TRACE, "...");    $logger->log($DEBUG, "...");    $logger->log($INFO, "...");    $logger->log($WARN, "...");    $logger->log($ERROR, "...");    $logger->log($FATAL, "...");

This form is rarely used, but it comes in handy if you want to log at different levels depending on an exit code of a function:

    $logger->log( $exit_level{ $rc }, "...");

As for needing more logging levels than these predefined ones: It'susually best to steer your logging behaviour via the category mechanism instead.

If you need to find out if the currently configured logginglevel would allow a logger's logging statement to go through, use thelogger's "is_level()" methods:

    $logger->is_trace()    # True if trace messages would go through    $logger->is_debug()    # True if debug messages would go through    $logger->is_info()     # True if info messages would go through    $logger->is_warn()     # True if warn messages would go through    $logger->is_error()    # True if error messages would go through    $logger->is_fatal()    # True if fatal messages would go through

Example: "$logger->is_warn()" returns true if the logger's currentlevel, as derived from either the logger's category (or, in absence ofthat, one of the logger's parent's level setting) is $WARN, $ERROR or $FATAL.

Also available are a series of more Java-esque functions which returnthe same values. These are of the format "isLevelEnabled()",so "$logger->isDebugEnabled()" is synonymous to "$logger->is_debug()".

These level checking functionswill come in handy later, when we want to block unnecessaryexpensive parameter construction in case the logging level is toolow to log the statement anyway, like in:

    if($logger->is_error()) {        $logger->error("Erroneous array: @super_long_array");    }

If we had just written

    $logger->error("Erroneous array: @super_long_array");

then Perl would have interpolated@super_long_array into the string via an expensive operationonly to figure out shortly after that the string can be ignoredentirely because the configured logging level is lower than $ERROR.

The to-be-loggedmessage passed to all of the functions described above canconsist of an arbitrary number of arguments, which the logging functionsjust chain together to a single string. Therefore

    $logger->debug("Hello ", "World", "!");  # and    $logger->debug("Hello World!");

are identical.

Note that even if one of the methods above returns true, it doesn't necessarily mean that the message will actually get logged. What is_debug() checks is thatthe logger used is configured to let a message of the given priority (DEBUG) through. But after this check, Log4perl will eventually apply custom filters and forward the message to one or more appenders. None of thisgets checked by is_xxx(), for the simple reason that it's impossible to know what a custom filter does with a message withouthaving the actual message or what an appender does to a message withoutactually having it log it. 

Log and die or warn

Often, when you croak / carp / warn / die, you want to log those messages.Rather than doing the following:

    $logger->fatal($err) && die($err);

you can use the following:

    $logger->logdie($err);

And if instead of using

    warn($message);    $logger->warn($message);

to both issue a warning via Perl's warn() mechanism and make sure you havethe same message in the log file as well, use:

    $logger->logwarn($message);

Since there isan ERROR level between WARN and FATAL, there are two additional helperfunctions in case you'd like to use ERROR for either warn() or die():

    $logger->error_warn();    $logger->error_die();

Finally, there's the Carp functions that, in addition to logging,also pass the stringified message to their companions in the Carp package:

    $logger->logcarp();        # warn w/ 1-level stack trace    $logger->logcluck();       # warn w/ full stack trace    $logger->logcroak();       # die w/ 1-level stack trace    $logger->logconfess();     # die w/ full stack trace
 

Appenders

If you don't define any appenders, nothing will happen. Appenders willbe triggered whenever the configured logging level requires a messageto be logged and not suppressed.

"Log::Log4perl" doesn't define any appenders by default, not even the rootlogger has one.

"Log::Log4perl" already comes with a standard set of appenders:

    Log::Log4perl::Appender::Screen    Log::Log4perl::Appender::ScreenColoredLevels    Log::Log4perl::Appender::File    Log::Log4perl::Appender::Socket    Log::Log4perl::Appender::DBI    Log::Log4perl::Appender::Synchronized    Log::Log4perl::Appender::RRDs

to log to the screen, to files and to databases.

On CPAN, you can find additional appenders like

    Log::Log4perl::Layout::XMLLayout

by Guido Carls <gcarlsAATTcpan.org>.It allows for hooking up Log::Log4perl with the graphical Log AnalyzerChainsaw (see ``Can I use Log::Log4perl with log4j's Chainsaw?'' in Log::Log4perl::FAQ). 

Additional Appenders via Log::Dispatch

"Log::Log4perl" also supports Dave Rolskys excellent "Log::Dispatch"framework which implements a wide variety of different appenders.

Here's the list of appender modules currently available via "Log::Dispatch":

       Log::Dispatch::ApacheLog       Log::Dispatch::DBI (by Tatsuhiko Miyagawa)       Log::Dispatch::Email,       Log::Dispatch::Email::MailSend,       Log::Dispatch::Email::MailSendmail,       Log::Dispatch::Email::MIMELite       Log::Dispatch::File       Log::Dispatch::FileRotate (by Mark Pfeiffer)       Log::Dispatch::Handle       Log::Dispatch::Screen       Log::Dispatch::Syslog       Log::Dispatch::Tk (by Dominique Dumont)

Please note that in order to use any of these additional appenders, youhave to fetch Log::Dispatch from CPAN and install it. Also the particularappender you're using might require installing the particular module.

For additional information on appenders, please check theLog::Log4perl::Appender manual page. 

Appender Example

Now let's assume that we want to log "info()" orhigher prioritized messages in the "Foo::Bar" categoryto both STDOUT and to a log file, say "test.log".In the initialization section of your system,just define two appenders using the readily available"Log::Log4perl::Appender::File" and "Log::Log4perl::Appender::Screen" modules:

  use Log::Log4perl;     # Configuration in a string ...  my $conf = q(    log4perl.category.Foo.Bar          = INFO, Logfile, Screen    log4perl.appender.Logfile          = Log::Log4perl::Appender::File    log4perl.appender.Logfile.filename = test.log    log4perl.appender.Logfile.layout   = Log::Log4perl::Layout::PatternLayout    log4perl.appender.Logfile.layout.ConversionPattern = [%r] %F %L %m%n    log4perl.appender.Screen         = Log::Log4perl::Appender::Screen    log4perl.appender.Screen.stderr  = 0    log4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout  );     # ... passed as a reference to init()  Log::Log4perl::init( \$conf );

Once the initialization shown above has happened once, typically inthe startup code of your system, just use the defined logger anywhere in your system:

  ##########################  # ... in some function ...  ##########################  my $log = Log::Log4perl::get_logger("Foo::Bar");    # Logs both to STDOUT and to the file test.log  $log->info("Important Info!");

The "layout" settings specified in the configuration section define the format in which themessage is going to be logged by the specified appender. The format shownfor the file appender is logging not only the message but also the number ofmilliseconds since the program has started (%r), the name of the filethe call to the logger has happened and the line number there (%F and%L), the message itself (%m) and a OS-specific newline character (%n):

    [187] ./myscript.pl 27 Important Info!

Thescreen appender above, on the other hand, uses a "SimpleLayout", which logs the debug level, a hyphen (-) and the log message:

    INFO - Important Info!

For more detailed info on layout formats, see ``Log Layouts''.

In the configuration sample above, we chose to define a category logger ("Foo::Bar").This will cause only messages originating fromthis specific category logger to be logged in the defined formatand locations. 

Logging newlines

There's some controversy between different logging systems as to when and where newlines are supposed to be added to logged messages.

The Log4perl way is that a logging statement should not contain a newline:

    $logger->info("Some message");    $logger->info("Another message");

If this is supposed to end up in a log file like

    Some message    Another message

then an appropriate appender layout like ``%m%n'' will take care of addinga newline at the end of each message to make sure every message is printed on its own line.

Other logging systems, Log::Dispatch in particular, recommend adding thenewline to the log statement. This doesn't work well, however, if you, say,replace your file appender by a database appender, and all of a suddenthose newlines scattered around the code don't make sense anymore.

Assigning matching layouts to different appenders and leaving newlinesout of the code solves this problem. If you inherited code that has loggingstatements with newlines and want to make it work with Log4perl, readthe Log::Log4perl::Layout::PatternLayout documentation on how to accomplish that. 

Configuration files

As shown above, you can define "Log::Log4perl" loggers both from withinyour Perl code or from configuration files. The latter have the unbeatableadvantage that you can modify your system's logging behaviour without interfering with the code at all. So even if your code is being run by somebody who's totally oblivious to Perl, they still can adapt themodule's logging behaviour to their needs.

"Log::Log4perl" has been designed to understand "Log4j" configurationfiles --- as used by the original Java implementation. Instead of reiterating the format description in [2], let me just list threeexamples (also derived from [2]), which should also illustratehow it works:

    log4j.rootLogger=DEBUG, A1    log4j.appender.A1=org.apache.log4j.ConsoleAppender    log4j.appender.A1.layout=org.apache.log4j.PatternLayout    log4j.appender.A1.layout.ConversionPattern=%-4r %-5p %c %x - %m%n

This enables messages of priority "DEBUG" or higher in the roothierarchy and has the system write them to the console. "ConsoleAppender" is a Java appender, but "Log::Log4perl" jumpsthrough a significant number of hoops internally to map these to theircorresponding Perl classes, "Log::Log4perl::Appender::Screen" in this case.

Second example:

    log4perl.rootLogger=DEBUG, A1    log4perl.appender.A1=Log::Log4perl::Appender::Screen    log4perl.appender.A1.layout=PatternLayout    log4perl.appender.A1.layout.ConversionPattern=%d %-5p %c - %m%n    log4perl.logger.com.foo=WARN

This defines two loggers: The root logger and the "com.foo" logger.The root logger is easily triggered by debug-messages, but the "com.foo" logger makes sure that messages issued withinthe "Com::Foo" component and below are only forwarded to the appenderif they're of priority warning or higher.

Note that the "com.foo" logger doesn't define an appender. Therefore,it will just propagate the message up the hierarchy until the root loggerpicks it up and forwards it to the one and only appender of the rootcategory, using the format defined for it.

Third example:

    log4j.rootLogger=DEBUG, stdout, R    log4j.appender.stdout=org.apache.log4j.ConsoleAppender    log4j.appender.stdout.layout=org.apache.log4j.PatternLayout    log4j.appender.stdout.layout.ConversionPattern=%5p (%F:%L) - %m%n    log4j.appender.R=org.apache.log4j.RollingFileAppender    log4j.appender.R.File=example.log    log4j.appender.R.layout=org.apache.log4j.PatternLayout    log4j.appender.R.layout.ConversionPattern=%p %c - %m%n

The root logger defines two appenders here: "stdout", which uses "org.apache.log4j.ConsoleAppender" (ultimately mapped by "Log::Log4perl"to Log::Log4perl::Appender::Screen) to write to the screen. And"R", a "org.apache.log4j.RollingFileAppender" (mapped by "Log::Log4perl" to Log::Dispatch::FileRotate with the "File" attribute specifying thelog file.

See Log::Log4perl::Config for more examples and syntax explanations. 

Log Layouts

If the logging engine passes a message to an appender, because it thinksit should be logged, the appender doesn't justwrite it out haphazardly. There's ways to tell the appender how to formatthe message and add all sorts of interesting data to it: The date andtime when the event happened, the file, the line number, thedebug level of the logger and others.

There's currently two layouts defined in "Log::Log4perl": "Log::Log4perl::Layout::SimpleLayout" and"Log::Log4perl::Layout::PatternLayout":

Log::Log4perl::SimpleLayout
formats a message in a simpleway and just prepends it by the debug level and a hyphen:""$level - $message", for example "FATAL - Can't open password file".
Log::Log4perl::Layout::PatternLayout
on the other hand is very powerful and allows for a very flexible format in "printf"-style. The formatstring can contain a number of placeholders which will bereplaced by the logging engine when it's time to log the message:

    %c Category of the logging event.    %C Fully qualified package (or class) name of the caller    %d Current date in yyyy/MM/dd hh:mm:ss format    %F File where the logging event occurred    %H Hostname (if Sys::Hostname is available)    %l Fully qualified name of the calling method followed by the       callers source the file name and line number between        parentheses.    %L Line number within the file where the log statement was issued    %m The message to be logged    %m{chomp} The message to be logged, stripped off a trailing newline    %M Method or function where the logging request was issued    %n Newline (OS-independent)    %p Priority of the logging event    %P pid of the current process    %r Number of milliseconds elapsed from program start to logging        event    %R Number of milliseconds elapsed from last logging event to       current logging event     %T A stack trace of functions called    %x The topmost NDC (see below)    %X{key} The entry 'key' of the MDC (see below)    %% A literal percent (%) sign

NDC and MDC are explained in ``Nested Diagnostic Context (NDC)''and ``Mapped Diagnostic Context (MDC)''.

Also, %d can be fine-tuned to display only certain characteristicsof a date, according to the SimpleDateFormat in the Java World(<http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.html>)

In this way, %d{HH:mm} displays only hours and minutes of the current date,while %d{yy, EEEE} displays a two-digit year, followed by a spelled-out day(like "Wednesday").

Similar options are available for shrinking the displayed category orlimit file/path components, %F{1} only displays the source file namewithout any path components while %F logs the full path. %c{2} onlylogs the last two components of the current category, "Foo::Bar::Baz" becomes "Bar::Baz" and saves space.

If those placeholders aren't enough, then you can define your own right inthe config file like this:

    log4perl.PatternLayout.cspec.U = sub { return "UID $<" }

See Log::Log4perl::Layout::PatternLayout for further details oncustomized specifiers.

Please note that the subroutines you're defining in this way are goingto be run in the "main" namespace, so be sure to fully qualify functionsand variables if they're located in different packages.

SECURITY NOTE: this feature means arbitrary perl code can be embedded in the config file. In the rare case where the people who have access to your config file are different from the people who write your code and shouldn't have execute rights, you might want to call

    Log::Log4perl::Config->allow_code(0);

before you call init(). Alternatively you can supply a restricted set ofPerl opcodes that can be embedded in the config file as described in``Restricting what Opcodes can be in a Perl Hook''.

All placeholders are quantifiable, just like in printf. Following this tradition, "%-20c" will reserve 20 chars for the category and left-justify it.

For more details on logging and how to use the flexible and the simpleformat, check out the original "log4j" website under

SimpleLayout <http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/SimpleLayout.html>andPatternLayout <http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PatternLayout.html> 

Penalties

Logging comes with a price tag. "Log::Log4perl" has been optimizedto allow for maximum performance, both with logging enabled and disabled.

But you need to be aware that there's a small hit every time your codeencounters a log statement --- no matter if logging is enabled or not. "Log::Log4perl" has been designed to keep this so low that it willbe unnoticeable to most applications.

Here's a couple of tricks which help "Log::Log4perl" to avoidunnecessary delays:

You can save serious time if you're logging something like

        # Expensive in non-debug mode!    for (@super_long_array) {        $logger->debug("Element: $_");    }

and @super_long_array is fairly big, so looping through it is prettyexpensive. Only you, the programmer, knows that going through that "for"loop can be skipped entirely if the current logging level for the actual component is higher than "debug".In this case, use this instead:

        # Cheap in non-debug mode!    if($logger->is_debug()) {        for (@super_long_array) {            $logger->debug("Element: $_");        }    }

If you're afraid that generating the parameters to thelogging function is fairly expensive, use closures:

        # Passed as subroutine ref    use Data::Dumper;    $logger->debug(sub { Dumper($data) } );

This won't unravel $data via Dumper() unless it's actually neededbecause it's logged.

Also, Log::Log4perl lets you specify argumentsto logger functions in message output filter syntax:

    $logger->debug("Structure: ",                   { filter => \&Dumper,                     value  => $someref });

In this way, shortly before Log::Log4perl sending themessage out to any appenders, it will be searching all arguments forhash references and treat them in a special way:

It will invoke the function given as a reference with the "filter" key("Data::Dumper::Dumper()") and pass it the value that came withthe key named "value" as an argument.The anonymous hash in the call above will be replaced by the return value of the filter function. 

Categories

Categories are also called ``Loggers'' in Log4perl, both referto the same thing and these terms are used interchangeably."Log::Log4perl" uses categories to determine if a log statement ina component should be executed or suppressed at the current logging level.Most of the time, these categories are just the classes the log statementsare located in:

    package Candy::Twix;    sub new {         my $logger = Log::Log4perl->get_logger("Candy::Twix");        $logger->debug("Creating a new Twix bar");        bless {}, shift;    }     # ...    package Candy::Snickers;    sub new {         my $logger = Log::Log4perl->get_logger("Candy.Snickers");        $logger->debug("Creating a new Snickers bar");        bless {}, shift;    }    # ...    package main;    Log::Log4perl->init("mylogdefs.conf");        # => "LOG> Creating a new Snickers bar"    my $first = Candy::Snickers->new();        # => "LOG> Creating a new Twix bar"    my $second = Candy::Twix->new();

Note that you can separate your category hierarchy levelsusing either dots likein Java (.) or double-colons (::) like in Perl. Both notationsare equivalent and are handled the same way internally.

However, categories are just there to makeuse of inheritance: if you invoke a logger in a sub-category, it will bubble up the hierarchy and call the appropriate appenders.Internally, categories are not related to the class hierarchy of the programat all --- they're purely virtual. You can use arbitrary categories ---for example in the following program, which isn't oo-style, butprocedural:

    sub print_portfolio {        my $log = Log::Log4perl->get_logger("user.portfolio");        $log->debug("Quotes requested: @_");        for(@_) {            print "$_: ", get_quote($_), "\n";        }    }    sub get_quote {        my $log = Log::Log4perl->get_logger("internet.quotesystem");        $log->debug("Fetching quote: $_[0]");        return yahoo_quote($_[0]);    }

The logger in first function, "print_portfolio", is assigned the(virtual) "user.portfolio" category. Depending on the "Log4perl"configuration, this will either call a "user.portfolio" appender,a "user" appender, or an appender assigned to root --- without"user.portfolio" having any relevance to the class system used in the program.The logger in the second function adheres to the "internet.quotesystem" category --- again, maybe because it's bundled with other Internet functions, but not because there would bea class of this name somewhere.

However, be careful, don't go overboard: if you're developing a systemin object-oriented style, using the class hierarchy is usually your bestchoice. Think about the people taking over your code one day: Theclass hierarchy is probably what they know right up front, so it's easyfor them to tune the logging to their needs. 

Turn off a component

"Log4perl" doesn't only allow you to selectively switch on a categoryof log messages, you can also use the mechanism to selectively disablelogging in certain components whereas logging is kept turned on in higher-levelcategories. This mechanism comes in handy if you find that while bumping up the logging level of a high-level (i. e. close to root) category, that one component logs more than it should,

Here's how it works:

    ############################################################    # Turn off logging in a lower-level category while keeping    # it active in higher-level categories.    ############################################################    log4perl.rootLogger=DEBUG, LOGFILE    log4perl.logger.deep.down.the.hierarchy = ERROR, LOGFILE    # ... Define appenders ...

This way, log messages issued from within "Deep::Down::The::Hierarchy" and below will belogged only if they're "ERROR" or worse, while in all other system componentseven "DEBUG" messages will be logged. 

Return Values

All logging methods return values indicating if their messageactually reached one or more appenders. If the message has beensuppressed because of level constraints, "undef" is returned.

For example,

    my $ret = $logger->info("Message");

will return "undef" if the system debug level for the current categoryis not "INFO" or more permissive. If Log::Log4perlforwarded the message to one or more appenders, the number of appendersis returned.

If appenders decide to veto on the message with an appender threshold,the log method's return value will have them excluded. This means that ifyou've got one appender holding an appender threshold and you're logging a messagewhich passes the system's log level hurdle but not the appender threshold,0 will be returned by the log function.

The bottom line is: Logging functions will return a true value if the messagemade it through to one or more appenders and a false value if it didn't.This allows for constructs like

    $logger->fatal("@_") or print STDERR "@_\n";

which will ensure that the fatal message isn't lostif the current level is lower than FATAL or printed twice if the level is acceptable but an appender already points to STDERR. 

Pitfalls with Categories

Be careful with just blindly reusing the system's packages ascategories. If you do, you'll get into trouble with inherited methods.Imagine the following class setup:

    use Log::Log4perl;    ###########################################    package Bar;    ###########################################    sub new {        my($class) = @_;        my $logger = Log::Log4perl::get_logger(__PACKAGE__);        $logger->debug("Creating instance");        bless {}, $class;    }    ###########################################    package Bar::Twix;    ###########################################    our @ISA = qw(Bar);    ###########################################    package main;    ###########################################    Log::Log4perl->init(\ qq{    log4perl.category.Bar.Twix = DEBUG, Screen    log4perl.appender.Screen = Log::Log4perl::Appender::Screen    log4perl.appender.Screen.layout = SimpleLayout    });    my $bar = Bar::Twix->new();

"Bar::Twix" just inherits everything from "Bar", including the constructor"new()".Contrary to what you might be thinking at first, this won't log anything. Reason for this is the "get_logger()" call in package "Bar", whichwill always get a logger of the "Bar" category, even if we call "new()" viathe "Bar::Twix" package, which will make perl go up the inheritance tree to actually execute "Bar::new()". Since we've only defined loggingbehaviour for "Bar::Twix" in the configuration file, nothing will happen.

This can be fixed by changing the "get_logger()" method in "Bar::new()"to obtain a logger of the category matching theactual class of the object, like in

        # ... in Bar::new() ...    my $logger = Log::Log4perl::get_logger( $class );

In a method other than the constructor, the class name of the actualobject can be obtained by calling "ref()" on the object reference, so

    package BaseClass;    use Log::Log4perl qw( get_logger );    sub new {         bless {}, shift;     }    sub method {        my( $self ) = @_;        get_logger( ref $self )->debug( "message" );    }    package SubClass;    our @ISA = qw(BaseClass);

is the recommended pattern to make sure that

    my $sub = SubClass->new();    $sub->meth();

starts logging if the "SubClass" category (and not the "BaseClass" category has logging enabled at the DEBUG level. 

Initialize once and only once

It's important to realize that Log::Log4perl gets initialized once and onlyonce, typically at the start of a program or system. Calling "init()"more than once will cause it to clobber the existing configuration andreplace it by the new one.

If you're in a traditional CGI environment, where every request ishandled by a new process, calling "init()" every time is fine. Inpersistent environments like "mod_perl", however, Log::Log4perlshould be initialized either at system startup time (Apache offersstartup handlers for that) or via

        # Init or skip if already done    Log::Log4perl->init_once($conf_file);

"init_once()" is identical to "init()", just with the exceptionthat it will leave a potentially existing configuration alone and will only call "init()" if Log::Log4perl hasn't been initialized yet.

If you're just curious if Log::Log4perl has been initialized yet, thecheck

    if(Log::Log4perl->initialized()) {        # Yes, Log::Log4perl has already been initialized    } else {        # No, not initialized yet ...    }

can be used.

If you're afraid that the components of your system are stepping on each other's toes or if you are thinking that different components shouldinitialize Log::Log4perl separately, try to consolidate your systemto use a centralized Log4perl configuration file and use Log4perl's categories to separate your components. 

Custom Filters

Log4perl allows the use of customized filters in its appendersto control the output of messages. These filters might grep forcertain text chunks in a message, verify that its prioritymatches or exceeds a certain level or that this is the 10thtime the same message has been submitted --- and come to a log/no log decision based upon these circumstantial facts.

Check out Log::Log4perl::Filter for detailed instructions on how to use them. 

Performance

The performance of Log::Log4perl calls obviously depends on a lot of things.But to give you a general idea, here's some rough numbers:

On a Pentium 4 Linux box at 2.4 GHz, you'll get through

*
500,000 suppressed log statements per second
*
30,000 logged messages per second (using an in-memory appender)
*
init_and_watch delay mode: 300,000 suppressed, 30,000 logged.init_and_watch signal mode: 450,000 suppressed, 30,000 logged.

Numbers depend on the complexity of the Log::Log4perl configuration.For a more detailed benchmark test, check the "docs/benchmark.results.txt" document in the Log::Log4perl distribution. 

Cool Tricks

Here's a collection of useful tricks for the advanced "Log::Log4perl" user.For more, check the FAQ, either in the distribution (Log::Log4perl::FAQ) or on <http://log4perl.sourceforge.net>. 

Shortcuts

When getting an instance of a logger, instead of saying

    use Log::Log4perl;    my $logger = Log::Log4perl->get_logger();

it's often more convenient to import the "get_logger" method from "Log::Log4perl" into the current namespace:

    use Log::Log4perl qw(get_logger);    my $logger = get_logger();

Please note this difference: To obtain the root logger, please use"get_logger("")", call it without parameters ("get_logger()"), you'llget the logger of a category named after the current package. "get_logger()" is equivalent to "get_logger(__PACKAGE__)". 

Alternative initialization

Instead of having "init()" read in a configuration file by specifyinga file name or passing it a reference to an open filehandle("Log::Log4perl->init( \*FILE )"),you can also pass in a reference to a string, containing the content ofthe file:

    Log::Log4perl->init( \$config_text );

Also, if you've got the "name=value" pairs of the configuration ina hash, you can just as well initialize "Log::Log4perl" witha reference to it:

    my %key_value_pairs = (        "log4perl.rootLogger"       => "ERROR, LOGFILE",        "log4perl.appender.LOGFILE" => "Log::Log4perl::Appender::File",        ...    );    Log::Log4perl->init( \%key_value_pairs );

Or also you can use a URL, see below: 

Using LWP to parse URLs

(This section borrowed from XML::DOM::Parser by T.J. Mather).

The init() function now also supports URLs, e.g. http://www.erols.com/enno/xsa.xml.It uses LWP to download the file and then calls parse() on the resulting string.By default it will use a LWP::UserAgent that is created as follows:

 use LWP::UserAgent; $LWP_USER_AGENT = LWP::UserAgent->new; $LWP_USER_AGENT->env_proxy;

Note that env_proxy reads proxy settings from environment variables, which is what Log4perl needs todo to get through our firewall. If you want to use a different LWP::UserAgent, you can set it with

    Log::Log4perl::Config::set_LWP_UserAgent($my_agent);

Currently, LWP is used when the filename (passed to parsefile) starts with one ofthe following URL schemes: http, https, ftp, wais, gopher, or file (followed by a colon.)

Don't use this feature with init_and_watch(). 

Automatic reloading of changed configuration files

Instead of just statically initializing Log::Log4perl via

    Log::Log4perl->init($conf_file);

there's a way to have Log::Log4perl periodically check for changesin the configuration and reload it if necessary:

    Log::Log4perl->init_and_watch($conf_file, $delay);

In this mode, Log::Log4perl will examine the configuration file $conf_file every $delay seconds for changes via the file'slast modification timestamp. If the file has been updated, it willbe reloaded and replace the current Log::Log4perl configuration.

The way this works is that with every logger function called (debug(), is_debug(), etc.), Log::Log4perl will check if the delay interval has expired. If so, it will run a -M file check on the configuration file. If its timestamp has been modified, the currentconfiguration will be dumped and new content of the file will beloaded.

This convenience comes at a price, though: Calling time() with everylogging function call, especially the ones that are ``suppressed'' (!), will slow down these Log4perl calls by about 40%.

To alleviate this performance hit a bit, "init_and_watch()" can be configured to listen for a Unix signal to reload the configuration instead:

    Log::Log4perl->init_and_watch($conf_file, 'HUP');

This will set up a signal handler for SIGHUP and reload the configurationif the application receives this signal, e.g. via the "kill" command:

    kill -HUP pid

where "pid" is the process ID of the application. This will bring you backto about 85% of Log::Log4perl's normal execution speed for suppressedstatements. For details, check out ``Performance''. For more infoon the signal handler, look for ``SIGNAL MODE'' in Log::Log4perl::Config::Watch.

If you have a somewhat long delay set between physical config file checksor don't want to use the signal associated with the config file watcher,you can trigger a configuration reload at the next possible time bycalling "Log::Log4perl::Config->watcher->force_next_check()".

One thing to watch out for: If the configuration file contains a syntaxor other fatal error, a running application will stop with "die" ifthis damaged configuration will be loaded during runtime, triggeredeither by a signal or if the delay period expired and the change is detected. This behaviour might change in the future.

To allow the application to intercept and control a configuration reloadin init_and_watch mode, a callback can be specified:

    Log::Log4perl->init_and_watch($conf_file, 10, {             preinit_callback => \&callback });

If Log4perl determines that the configuration needs to be reloaded, it willcall the "preinit_callback" function without parameters. If the callbackreturns a true value, Log4perl will proceed and reload the configuration. Ifthe callback returns a false value, Log4perl will keep the old configurationand skip reloading it until the next time around. Inside the callback, anapplication can run all kinds of checks, including accessing the configurationfile, which is available via"Log::Log4perl::Config->watcher()->file()". 

Variable Substitution

To avoid having to retype the same expressions over and over again,Log::Log4perl's configuration files support simple variable substitution.New variables are defined simply by adding

    varname = value

lines to the configuration file before using

    ${varname}

afterwards to recall the assigned values. Here's an example:

    layout_class   = Log::Log4perl::Layout::PatternLayout    layout_pattern = %d %F{1} %L> %m %n        log4perl.category.Bar.Twix = WARN, Logfile, Screen    log4perl.appender.Logfile  = Log::Log4perl::Appender::File    log4perl.appender.Logfile.filename = test.log    log4perl.appender.Logfile.layout = ${layout_class}    log4perl.appender.Logfile.layout.ConversionPattern = ${layout_pattern}    log4perl.appender.Screen  = Log::Log4perl::Appender::Screen    log4perl.appender.Screen.layout = ${layout_class}    log4perl.appender.Screen.layout.ConversionPattern = ${layout_pattern}

This is a convenient way to define two appenders with the same layout without having to retype the pattern definitions.

Variable substitution via "${varname}" will first try to find an explicitly defined variable. If that fails, it will check your shell's environmentfor a variable of that name. If that also fails, the program will "die()". 

Perl Hooks in the Configuration File

If some of the values used in the Log4perl configuration file need to be dynamically modified by the program, use Perl hooks:

    log4perl.appender.File.filename = \        sub { return getLogfileName(); }

Each value starting with the string "sub {..." is interpreted as Perl code tobe executed at the time the application parses the configurationvia "Log::Log4perl::init()". The return value of the subroutineis used by Log::Log4perl as the configuration value.

The Perl code is executed in the "main" package, functions inother packages have to be called in fully-qualified notation.

Here's another example, utilizing an environment variable as ausername for a DBI appender:

    log4perl.appender.DB.username = \        sub { $ENV{DB_USER_NAME } }

However, please note the difference between these code snippets and thoseused for user-defined conversion specifiers as discussed inLog::Log4perl::Layout::PatternLayout: While the snippets above are run oncewhen "Log::Log4perl::init()" is called, the conversion specifiersnippets are executed each time a message is rendered according tothe PatternLayout.

SECURITY NOTE: this feature means arbitrary perl code can be embedded in the config file. In the rare case where the people who have access to your config file are different from the people who write your code and shouldn't have execute rights, you might want to set

    Log::Log4perl::Config->allow_code(0);

before you call init(). Alternatively you can supply a restricted set ofPerl opcodes that can be embedded in the config file as described in``Restricting what Opcodes can be in a Perl Hook''. 

Restricting what Opcodes can be in a Perl Hook

The value you pass to Log::Log4perl::Config->allow_code() determines whetherthe code that is embedded in the config file is eval'd unrestricted, oreval'd in a Safe compartment. By default, a value of '1' is assumed,which does a normal 'eval' without any restrictions. A value of '0' however prevents any embedded code from being evaluated.

If you would like fine-grained control over what can and cannot be includedin embedded code, then please utilize the following methods:

 Log::Log4perl::Config->allow_code( $allow ); Log::Log4perl::Config->allowed_code_ops($op1, $op2, ... ); Log::Log4perl::Config->vars_shared_with_safe_compartment( [ \%vars | $package, \@vars ] ); Log::Log4perl::Config->allowed_code_ops_convenience_map( [ \%map | $name, \@mask ] );

Log::Log4perl::Config->allowed_code_ops() takes a list of opcode masksthat are allowed to run in the compartment. The opcode masks must bespecified as described in Opcode:

 Log::Log4perl::Config->allowed_code_ops(':subprocess');

This example would allow Perl operations like backticks, system, fork, andwaitpid to be executed in the compartment. Of course, you probably don'twant to use this mask --- it would allow exactly what the Safe compartment isdesigned to prevent.

Log::Log4perl::Config->vars_shared_with_safe_compartment() takes the symbols whichshould be exported into the Safe compartment before the code is evaluated. The keys of this hash are the package names that the symbols are in, and thevalues are array references to the literal symbol names. For convenience,the default settings export the '%ENV' hash from the 'main' package into thecompartment:

 Log::Log4perl::Config->vars_shared_with_safe_compartment(   main => [ '%ENV' ], );

Log::Log4perl::Config->allowed_code_ops_convenience_map() is an accessormethod to a map of convenience names to opcode masks. At present, thefollowing convenience names are defined:

 safe        = [ ':browse' ] restrictive = [ ':default' ]

For convenience, if Log::Log4perl::Config->allow_code() is called with avalue which is a key of the map previously defined withLog::Log4perl::Config->allowed_code_ops_convenience_map(), then theallowed opcodes are set according to the value defined in the map. If thisis confusing, consider the following:

 use Log::Log4perl;  my $config = <<'END';  log4perl.logger = INFO, Main  log4perl.appender.Main = Log::Log4perl::Appender::File  log4perl.appender.Main.filename = \      sub { "example" . getpwuid($<) . ".log" }  log4perl.appender.Main.layout = Log::Log4perl::Layout::SimpleLayout END  $Log::Log4perl::Config->allow_code('restrictive'); Log::Log4perl->init( \$config );       # will fail $Log::Log4perl::Config->allow_code('safe'); Log::Log4perl->init( \$config );       # will succeed

The reason that the first call to ->init() fails is because the'restrictive' name maps to an opcode mask of ':default'. getpwuid() is notpart of ':default', so ->init() fails. The 'safe' name maps to an opcodemask of ':browse', which allows getpwuid() to run, so ->init() succeeds.

allowed_code_ops_convenience_map() can be invoked in several ways:

allowed_code_ops_convenience_map()
Returns the entire convenience name map as a hash reference in scalarcontext or a hash in list context.
allowed_code_ops_convenience_map( \%map )
Replaces the entire convenience name map with the supplied hash reference.
allowed_code_ops_convenience_map( $name )
Returns the opcode mask for the given convenience name, or undef if no suchname is defined in the map.
allowed_code_ops_convenience_map( $name, \@mask )
Adds the given name/mask pair to the convenience name map. If the namealready exists in the map, it's value is replaced with the new mask.

as can vars_shared_with_safe_compartment():

vars_shared_with_safe_compartment()
Return the entire map of packages to variables as a hash reference in scalarcontext or a hash in list context.
vars_shared_with_safe_compartment( \%packages )
Replaces the entire map of packages to variables with the supplied hashreference.
vars_shared_with_safe_compartment( $package )
Returns the arrayref of variables to be shared for a specific package.
vars_shared_with_safe_compartment( $package, \@vars )
Adds the given package / varlist pair to the map. If the package alreadyexists in the map, it's value is replaced with the new arrayref of variablenames.

For more information on opcodes and Safe Compartments, see Opcode andSafe. 

Changing the Log Level on a Logger

Log4perl provides some internal functions for quickly adjusting thelog level from within a running Perl program.

Now, some people mightargue that you should adjust your levels from within an external Log4perl configuration file, but Log4perl is everybody's darling.

Typically run-time adjusting of levels is doneat the beginning, or in response to some external input (like a``more logging'' runtime command for diagnostics).

You get the log level from a logger object with:

    $current_level = $logger->level();

and you may set it with the same method, provided you firstimported the log level constants, with:

    use Log::Log4perl::Level;

Then you can set the level on a logger to one of the constants,

    $logger->level($ERROR); # one of DEBUG, INFO, WARN, ERROR, FATAL

To increase the level of logging currently being done, use:

    $logger->more_logging($delta);

and to decrease it, use:

    $logger->less_logging($delta);

$delta must be a positive integer (for now, we may fix this later ;).

There are also two equivalent functions:

    $logger->inc_level($delta);    $logger->dec_level($delta);

They're included to allow you a choice in readability. Some folkswill prefer more/less_logging, as they're fairly clear in what theydo, and allow the programmer not to worry too much about what a Levelis and whether a higher level means more or less logging. However,other folks who do understand and have lots of code that deals withlevels will probably prefer the inc_level() and dec_level() methods asthey want to work with Levels and not worry about whether that meansmore or less logging. :)

That diatribe aside, typically you'll use more_logging() or inc_level()as such:

    my $v = 0; # default level of verbosity.        GetOptions("v+" => \$v, ...);    if( $v ) {      $logger->more_logging($v); # inc logging level once for each -v in ARGV    }
 

Custom Log Levels

First off, let me tell you that creating custom levels is heavilydeprecated by the log4j folks. Indeed, instead of creating additionallevels on top of the predefined DEBUG, INFO, WARN, ERROR and FATAL, you should use categories to control the amount of logging smartly,based on the location of the log-active code in the system.

Nevertheless, Log4perl provides a nice way to create custom levels via the create_custom_level() routine function. However, this must be donebefore the first call to init() or get_logger(). Say you want to createa NOTIFY logging level that comes after WARN (and thus before INFO).You'd do such as follows:

    use Log::Log4perl;    use Log::Log4perl::Level;    Log::Log4perl::Logger::create_custom_level("NOTIFY", "WARN");

And that's it! "create_custom_level()" creates the following functions /variables for level FOO:

    $FOO_INT        # integer to use in L4p::Level::to_level()    $logger->foo()  # log function to log if level = FOO    $logger->is_foo()   # true if current level is >= FOO

These levels can also be used in yourconfig file, but note that your config file probably won't beportable to another log4perl or log4j environment unless you'vemade the appropriate mods there too.

Since Log4perl translates log levels to syslog and Log::Dispatch if their appenders are used, you may add mappings for custom levels as well:

  Log::Log4perl::Level::add_priority("NOTIFY", "WARN",                                     $syslog_equiv, $log_dispatch_level);

For example, if your new custom ``NOTIFY'' level is supposed to map to syslog level 2 (``LOG_NOTICE'') and Log::Dispatch level 2 (``notice''), use:

  Log::Log4perl::Logger::create_custom_level("NOTIFY", "WARN", 2, 2);
 

System-wide log levels

As a fairly drastic measure to decrease (or increase) the logging levelall over the system with one single configuration option, use the "threshold"keyword in the Log4perl configuration file:

    log4perl.threshold = ERROR

sets the system-wide (or hierarchy-wide according to the log4j documentation)to ERROR and therefore deprives every logger in the system of the right to log lower-prio messages. 

Easy Mode

For teaching purposes (especially for [1]), I've put ":easy" mode into "Log::Log4perl", which just initializes a single root logger with a defined priority and a screen appender including some nice standa