[log4perl-devel] Recipe of the week: How to log all ERROR messages to a file?

[Mike S. <m...@pe...>]

Hi all,

for all of you Log4perl fans out there: Here's part one of our new weekly series: "Log4perl Recipe
of the Week". Every week, in a cookbook style, I'll post a new recipe here, starting easy and
getting more and more complex over time. I'll collect all of them in an FAQ, which is available on
the log4perl home page. Today, we'll start with #1:

FAQ #1: How can I simply log all my ERROR messages to a file?

After pulling in the "Log::Log4perl" module, just initialize its
behaviour by passing in a configuration to its "init" method as a string
reference. Then, obtain a logger instance and write out a message with
its "error()" method:

    use Log::Log4perl qw(get_logger);

        # Define configuration
    my $conf = q(
        log4perl.logger                    = ERROR, FileApp
        log4perl.appender.FileApp          = Log::Dispatch::File
        log4perl.appender.FileApp.filename = test.log
        log4perl.appender.FileApp.layout   = PatternLayout
        log4perl.appender.FileApp.layout.ConversionPattern = %d> %m%n
    );

        # Initialize logging behaviour
    Log::Log4perl->init( \$conf );

        # Obtain a logger instance
    my $logger = get_logger("Bar::Twix");
    $logger->error("Oh my, a dreadful error!");
    $logger->warn("Oh my, a dreadful warning!");

This will append something like

    2002/10/29 20:11:55> Oh my, a dreadful error!

to the log file "test.log". How does this all work?

While the Log::Log4perl "init()" method typically takes the name of a
configuration file as its input parameter like in

    Log::Log4perl->init( "/path/mylog.conf" );

the example above shows how to pass in a configuration as text in a
scalar reference.

The configuration as shown defines a logger of the root category, which
has an appender of type "Log::Dispatch::File" attached. The line

    log4perl.logger = ERROR, FileApp

doesn't list a category, defining a root logger. Compare that with

    log4perl.logger.Bar.Twix = ERROR, FileApp

which would define a logger for the category "Bar::Twix", showing
probably different behaviour. "FileApp" on the right side of the
assignment is an arbitrarily defined variable name, which is only used
to somehow reference an appender defined later on.

Appender settings in the configuration are defined as follows:

    log4perl.appender.FileApp          = Log::Dispatch::File
    log4perl.appender.FileApp.filename = test.log

It selects the file appender of the "Log::Dispatch" hierarchy, which is
tricked by Log::Log4perl into thinking that it should append to the file
"test.log" if it already exists. If we wanted to overwrite a potentially
existing file, we would have to explicitly set the appropriate
"Log::Dispatch::File" parameter "mode":

    log4perl.appender.FileApp          = Log::Dispatch::File
    log4perl.appender.FileApp.filename = test.log
    log4perl.appender.FileApp.mode     = write

Also, the configuration defines a PatternLayout format, adding the
nicely formatted current date and time, an arrow (>) and a space before
the messages, which is then followed by a newline:

    log4perl.appender.FileApp.layout   = PatternLayout
    log4perl.appender.FileApp.layout.ConversionPattern = %d> %m%n

Obtaining a logger instance and actually logging something is typically
done in a different system part as the Log::Log4perl initialisation
section, but in this example, it's just done right after init for the
sake of compactness:

        # Obtain a logger instance
    my $logger = get_logger("Bar::Twix");
    $logger->error("Oh my, a dreadful error!");

This retrieves an instance of the logger of the category "Bar::Twix",
which, as all other categories, inherits behaviour from the root logger
if no other loggers are defined in the initialization section.

The "error()" method fires up a message, which the root logger catches.
Its priority is equal to or higher than the root logger's priority
(ERROR), which causes the root logger to forward it to its attached
appender. By contrast, the following

    $logger->warn("Oh my, a dreadful warning!");

doesn't make it through, because the root logger sports a higher setting
(ERROR and up) than the WARN priority of the message.

That's it for today! Let me know if you like this format. You can read the whole thing
HTML-formatted here:
 http://log4perl.sourceforge.net/releases/Log-Log4perl/docs/html/Log/Log4perl/FAQ.html

Until next week!

-- Mike
--------------------------------------------------------
Mike Schilli log...@pe...
--------------------------------------------------------