######################################################################
    Log::Log4perl 0.51
######################################################################

NAME
    Log::Log4perl - Log4j implementation for Perl

SYNOPSIS
        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 to your application

DESCRIPTION
    Log::Log4perl lets you remote-control and fine-tune the logging
    behaviour of 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 packages are too
    static and generate a flood of log messages in your log files that 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
        or in 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
        by specifying logging *levels*.

    *   You also specify which so-called *appenders* you want to feed your
        log 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 off
    your logs at any time, specify the level of detail and make that
    dependent 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 would generate a flood of
    useless log messages and bog your system down beyond recognition. With
    "Log::Log4perl", however, you can tell the system: "Continue to log only
    severe errors to the log file. Open a second log file, turn on full
    debug logs in the "MySystem::Helpers::ScanDir" component and dump all
    messages originating from there into the new log file". And all this is
    possible by just changing the parameters in 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: Either via
    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 severe errors
    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 in the startup section of your code, using the following
    commands:

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

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

        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 set to
    "ERROR" for all components in the first line of configuration file shown
    above.

    Why "Log::Log4perl->get_logger" and not "Log::Log4perl->new"? We don't
    want to create a new object every time. Usually in OO-Programming, you
    create an object once and use the reference to it to call its methods.
    However, this requires that you pass around the object to all functions
    and the last thing we want is pollute each and every function/method
    we'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, it just
    calls the Logger's static "get_logger($category)" method to obtain a
    reference to the *one and only* possible logger object of a certain
    category. That's called a *singleton* if you're a Gamma fan.

    How does the logger know which 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 class hierarchy ("My" and then the
    we're at the root) to figure out if a log level is defined 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 *debug* and *info* messages are
    suppressed.

  Log Levels
    There are five predefined log levels: "FATAL", "ERROR", "WARN", "INFO"
    and "DEBUG" (in descending priority). Your configured logging level has
    to at least match the priority of the logging message.

    If your configured logging level is "WARN", then messages logged with
    "info()" and "debug()" message 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->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 level using
    the constants defined in "Log::Log4perl::Level":

        use Log::Log4perl::Level;

        $logger->log($DEBUG, "...");
        $logger->log($INFO, "...");
        $logger->log($WARN, "...");
        $logger->log($ERROR, "...");
        $logger->log($FATAL, "...");

    But nobody does that, really. Neither does anyone need more logging
    levels than these predefined ones. If you think you do, I would suggest
    you look into steering your logging behaviour via the category
    mechanism.

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

        $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 current
    level, as derived from either the logger's category (or, in absence of
    that, 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 return
    the same values. These are of the format "is*Level*Enabled()", so
    "$logger->isDebugEnabled()" is synonymous to "$logger->is_debug()".

    These level checking functions will come in handy later, when we want to
    block unnecessary expensive parameter construction in case the logging
    level is too low 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 operation only to figure out shortly after that the string
    can be ignored entirely because the configured logging level is lower
    than $ERROR.

    The to-be-logged message passed to all of the functions described above
    can consist of an arbitrary number of arguments, which the logging
    functions just chain together to a single string. Therefore

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

    are identical.

  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->logwarn();
        $logger->logdie();

    These print out log messages in the WARN and FATAL level, respectively,
    and then call the built-in warn() and die() functions. Since there is an
    ERROR level between WARN and FATAL, there are two additional helper
    functions 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 do just what the Carp functions
    do, but with logging:

        $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 will
    be triggered whenever the configured logging level requires a message to
    be logged and not suppressed.

    "Log::Log4perl" doesn't define any appenders by default, not even the
    root logger 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 <gcarls@cpan.org>. It allows for hooking up Log::Log4perl
    with the graphical Log Analyzer Chainsaw (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, you
    have to fetch Log::Dispatch from CPAN and install it. Also the
    particular appender you're using might require installing the particular
    module.

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

  Appender Example
    Now let's assume that we want to log "info()" or higher prioritized
    messages in the "Foo::Bar" category to 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 in the
    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 the message is going to be logged by the specified
    appender. The format shown for the file appender is logging not only the
    message but also the number of milliseconds since the program has
    started (%r), the name of the file the 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!

    The screen 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 from this
    specific category logger to be logged in the defined format and
    locations.

  Configuration files
    As shown above, you can define "Log::Log4perl" loggers both from within
    your Perl code or from configuration files. The latter have the
    unbeatable advantage 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
    the module's logging behaviour to their needs.

    "Log::Log4perl" has been designed to understand "Log4j" configuration
    files -- as used by the original Java implementation. Instead of
    reiterating the format description in [2], let me just list three
    examples (also derived from [2]), which should also illustrate how 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 root
    hierarchy and has the system write them to the console.
    "ConsoleAppender" is a Java appender, but "Log::Log4perl" jumps through
    a significant number of hoops internally to map these to their
    corresponding 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 within the "Com::Foo" component
    and below are only forwarded to the appender if 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 logger
    picks it up and forwards it to the one and only appender of the root
    category, 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 the log
    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 thinks
    it should be logged, the appender doesn't just write it out haphazardly.
    There's ways to tell the appender how to format the message and add all
    sorts of interesting data to it: The date and time when the event
    happened, the file, the line number, the debug 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 simple way 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 format string can contain a number of
        placeholders which will be replaced 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
            %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 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
            %x The elements of the NDC stack (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 characteristics
        of a date, according to the SimpleDateFormat in the Java World
        (http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.ht
        ml)

        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 (like "Wednesday").

        Similar options are available for shrinking the displayed category
        or limit file/path components, %F{1} only displays the source file
        *name* without any path components while %F logs the full path.
        %c{2} only logs 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 in the config file like this:

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

        See Log::Log4perl::Layout::PatternLayout for further details on
        customized specifiers.

        Please note that the subroutines you're defining in this way are
        going to be run in the "main" namespace, so be sure to fully qualify
        functions and 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 of Perl opcodes that can be embedded in the config file atails on
 fo("Important Info!");

    The "layout" settings specified in the configuration section define the
    format in which the message is going to be logged by the specified
    appender. The format shown for the file appender is logging not only the
    message but also the number of milliseconds since the program has
    started (%r), the name of the file the 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!

    The screen 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 from this
    specific category logger to be logged in the defined format and
    locations.

  Configuration files
    As shown above, you can define "Log::Log4perl" loggers both from within
    your Perl code or from configuration files. The latter have the
    unbeatable advantage 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
    the module's logging behaviour to their needs.

    "Log::Log4perl" has been designed to understand "Log4j" configuration
    files -- as used by the original Java implementation. Instead of
    reiterating the format description in [2], let me just list three
    examples (also derived from [2]), which should also illustrate how 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 root
    hierarchy and has the system write them to the console.
    "ConsoleAppender" is a Java appender, but "Log::Log4perl" jumps through
    a significant number of hoops internally to map these to their
    corresponding 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 within the "Com::Foo" component
    and below are only forwarded to the appender if 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 logger
    picks it up and forwards it to the one and only appender of the root
    category, 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 the log
    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 thinks
    it should be logged, the appender doesn't just write it out haphazardly.
    There's ways to tell the appender how to format the message and add all
    sorts of interesting data to it: The date and time when the event
    happened, the file, the line number, the debug 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 simple way 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 format string can contain a number of
        placeholders which will be replaced 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
            %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 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
            %x The elements of the NDC stack (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 characteristics
        of a date, according to the SimpleDateFormat in the Java World
        (http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.ht
        ml)

        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 (like "Wednesday").

        Similar options are available for shrinking the displayed category
        or limit file/path components, %F{1} only displays the source file
        *name* without any path components while %F logs the full path.
        %c{2} only logs 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 in the config file like this:

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

        See Log::Log4perl::Layout::PatternLayout for further details on
        customized specifiers.

        Please note that the subroutines you're defining in this way are
        going to be run in the "main" namespace, so be sure to fully qualify
        functions and 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 of Perl opcodes that can be embedded in the config file atails on
 fo("Important Info!");

    The "layout" settings specified in the configuration section define the
    format in which the message is going to be logged by the specified
    appender. The format shown for the file appender is logging not only the
    message but also the number of milliseconds since the program has
    started (%r), the name of the file the 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!

    The screen 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 from this
    specific category logger to be logged in the defined format and
    locations.

  Configuration files
    As shown above, you can define "Log::Log4perl" loggers both from within
    your Perl code or from configuration files. The latter have the
    unbeatable advantage 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
    the module's logging behaviour to their needs.

    "Log::Log4perl" has been designed to understand "Log4j" configuration
    files -- as used by the original Java implementation. Instead of
    reiterating the format description in [2], let me just list three
    examples (also derived from [2]), which should also illustrate how 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 root
    hierarchy and has the system write them to the console.
    "ConsoleAppender" is a Java appender, but "Log::Log4perl" jumps through
    a significant number of hoops internally to map these to their
    corresponding 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 within the "Com::Foo" component
    and below are only forwarded to the appender if 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 logger
    picks it up and forwards it to the one and only appender of the root
    category, 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 the log
    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 thinks
    it should be logged, the appender doesn't just write it out haphazardly.
    There's ways to tell the appender how to format the message and add all
    sorts of interesting data to it: The date and time when the event
    happened, the file, the line number, the debug 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 simple way 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 format string can contain a number of
        placeholders which will be replaced 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
            %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 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
            %x The elements of the NDC stack (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 characteristics
        of a date, according to the SimpleDateFormat in the Java World
        (http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.ht
        ml)

        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 (like "Wednesday").

        Similar options are available for shrinking the displayed category
        or limit file/path components, %F{1} only displays the source file
        *name* without any path components while %F logs the full path.
        %c{2} only logs 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 in the config file like this:

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

        See Log::Log4perl::Layout::PatternLayout for further details on
        customized specifiers.

        Please note that the subroutines you're defining in this way are
        going to be run in the "main" namespace, so be sure to fully qualify
        functions and 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 of Perl opcodes that can be embedded in the config file atails on
 fo("Important Info!");

    The "layout" settings specified in the configuration section define the
    format in which the message is going to be logged by the specified
    appender. The format shown for the file appender is logging not only the
    message but also the number of milliseconds since the program has
    started (%r), the name of the file the 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!

    The screen 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 from this
    specific category logger to be logged in the defined format and
    locations.

  Configuration files
    As shown above, you can define "Log::Log4perl" loggers both from within
    your Perl code or from configuration files. The latter have the
    unbeatable advantage 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
    the module's logging behaviour to their needs.

    "Log::Log4perl" has been designed to understand "Log4j" configuration
    files -- as used by the original Java implementation. Instead of
    reiterating the format description in [2], let me just list three
    examples (also derived from [2]), which should also illustrate how 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 root
    hierarchy and has the system write them to the console.
    "ConsoleAppender" is a Java appender, but "Log::Log4perl" jumps through
    a significant number of hoops internally to map these to their
    corresponding 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 within the "Com::Foo" component
    and below are only forwarded to the appender if 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 logger
    picks it up and forwards it to the one and only appender of the root
    category, 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 the log
    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 thinks
    it should be logged, the appender doesn't just write it out haphazardly.
    There's ways to tell the appender how to format the message and add all
    sorts of interesting data to it: The date and time when the event
    happened, the file, the line number, the debug 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 simple way 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 format string can contain a number of
        placeholders which will be replaced 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
            %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 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
            %x The elements of the NDC stack (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 characteristics
        of a date, according to the SimpleDateFormat in the Java World
        (http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.ht
        ml)

        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 (like "Wednesday").

        Similar options are available for shrinking the displayed category
        or limit file/path components, %F{1} only displays the source file
        *name* without any path components while %F logs the full path.
        %c{2} only logs 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 in the config file like this:

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

        See Log::Log4perl::Layout::PatternLayout for further details on
        customized specifiers.

        Please note that the subroutines you're defining in this way are
        going to be run in the "main" namespace, so be sure to fully qualify
        functions and 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 of Perl opcodes that can be embedded in the config file atails on
 fo("Important Info!");

    The "layout" settings specified in the configuration section define the
    format in which the message is going to be logged by the specified
    appender. The format shown for the file appender is logging not only the
    message but also the number of milliseconds since the program has
    started (%r), the name of the file the 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!

    The screen 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 from this
    specific category logger to be logged in the defined format and
    locations.

  Configuration files
    As shown above, you can define "Log::Log4perl" loggers both from within
    your Perl code or from configuration files. The latter have the
    unbeatable advantage 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
    the module's logging behaviour to their needs.

    "Log::Log4perl" has been designed to understand "Log4j" configuration
    files -- as used by the original Java implementation. Instead of
    reiterating the format description in [2], let me just list three
    examples (also derived from [2]), which should also illustrate how 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 root
    hierarchy and has the system write them to the console.
    "ConsoleAppender" is a Java appender, but "Log::Log4perl" jumps through
    a significant number of hoops internally to map these to their
    corresponding 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 within the "Com::Foo" component
    and below are only forwarded to the appender if 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 logger
    picks it up and forwards it to the one and only appender of the root
    category, 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 the log
    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 thinks
    it should be logged, the appender doesn't just write it out haphazardly.
    There's ways to tell the appender how to format the message and add all
    sorts of interesting data to it: The date and time when the event
    happened, the file, the line number, the debug 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 simple way 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 format string can contain a number of
        placeholders which will be replaced 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
            %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 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
            %x The elements of the NDC stack (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 characteristics
        of a date, according to the SimpleDateFormat in the Java World
        (http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.ht
        ml)

        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 (like "Wednesday").

        Similar options are available for shrinking the displayed category
        or limit file/path components, %F{1} only displays the source file
        *name* without any path components while %F logs the full path.
        %c{2} only logs 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 in the config file like this:

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

        See Log::Log4perl::Layout::PatternLayout for further details on
        customized specifiers.

        Please note that the subroutines you're defining in this way are
        going to be run in the "main" namespace, so be sure to fully qualify
        functions and 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 of Perl opcodes that can be embedded in the config file atails on
 fo("Important Info!");

    The "layout" settings specified in the configuration section define the
    format in which the message is going to be logged by the specified
    appender. The format shown for the file appender is logging not only the
    message but also the number of milliseconds since the program has
    started (%r), the name of the file the 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!

    The screen 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 from this
    specific category logger to be logged in the defined format and
    locations.

  Configuration files
    As shown above, you can define "Log::Log4perl" loggers both from within
    your Perl code or from configuration files. The latter have the
    unbeatable advantage 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
    the module's logging behaviour to their needs.

    "Log::Log4perl" has been designed to understand "Log4j" configuration
    files -- as used by the original Java implementation. Instead of
    reiterating the format description in [2], let me just list three
    examples (also derived from [2]), which should also illustrate how 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 root
    hierarchy and has the system write them to the console.
    "ConsoleAppender" is a Java appender, but "Log::Log4perl" jumps through
    a significant number of hoops internally to map these to their
    corresponding 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 within the "Com::Foo" component
    and below are only forwarded to the appender if 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 logger
    picks it up and forwards it to the one and only appender of the root
    category, 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 the log
    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 thinks
    it should be logged, the appender doesn't just write it out haphazardly.
    There's ways to tell the appender how to format the message and add all
    sorts of interesting data to it: The date and time when the event
    happened, the file, the line number, the debug 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 simple way 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 format string can contain a number of
        placeholders which will be replaced 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
            %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 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
            %x The elements of the NDC stack (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 characteristics
        of a date, according to the SimpleDateFormat in the Java World
        (http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.ht
        ml)

        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 (like "Wednesday").

        Similar options are available for shrinking the displayed category
        or limit file/path components, %F{1} only displays the source file
        *name* without any path components while %F logs the full path.
        %c{2} only logs 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 in the config file like this:

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

        See Log::Log4perl::Layout::PatternLayout for further details on
        customized specifiers.

        Please note that the subroutines you're defining in this way are
        going to be run in the "main" namespace, so be sure to fully qualify
        functions and 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 of Perl opcodes that can be embedded in the config file atails on
 fo("Important Info!");

    The "layout" settings specified in the configuration section define the
    format in which the message is going to be logged by the specified
    appender. The format shown for the file appender is logging not only the
    message but also the number of milliseconds since the program has
    started (%r), the name of the file the 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!

    The screen 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 from this
    specific category logger to be logged in the defined format and
    locations.

  Configuration files
    As shown above, you can define "Log::Log4perl" loggers both from within
    your Perl code or from configuration files. The latter have the
    unbeatable advantage 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
    the module's logging behaviour to their needs.

    "Log::Log4perl" has been designed to understand "Log4j" configuration
    files -- as used by the original Java implementation. Instead of
    reiterating the format description in [2], let me just list three
    examples (also derived from [2]), which should also illustrate how 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 root
    hierarchy and has the system write them to the console.
    "ConsoleAppender" is a Java appender, but "Log::Log4perl" jumps through
    a significant number of hoops internally to map these to their
    corresponding 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 within the "Com::Foo" component
    and below are only forwarded to the appender if 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 logger
    picks it up and forwards it to the one and only appender of the root
    category, 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 the log
    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 thinks
    it should be logged, the appender doesn't just write it out haphazardly.
    There's ways to tell the appender how to format the message and add all
    sorts of interesting data to it: The date and time when the event
    happened, the file, the line number, the debug 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 simple way 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 format string can contain a number of
        placeholders which will be replaced 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
            %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 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
            %x The elements of the NDC stack (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 characteristics
        of a date, according to the SimpleDateFormat in the Java World
        (http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.ht
        ml)

        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 (like "Wednesday").

        Similar options are available for shrinking the displayed category
        or limit file/path components, %F{1} only displays the source file
        *name* without any path components while %F logs the full path.
        %c{2} only logs 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 in the config file like this:

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

        See Log::Log4perl::Layout::PatternLayout for further details on
        customized specifiers.

        Please note that the subroutines you're defining in this way are
        going to be run in the "main" namespace, so be sure to fully qualify
        functions and 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 of Perl opcodes that can be embedded in the config file atails on
 fo("Important Info!");

    The "layout" settings specified in the configuration section define the
    format in which the message is going to be logged by the specified
    appender. The format shown for the file appender is logging not only the
    message but also the number of milliseconds since the program has
    started (%r), the name of the file the 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!

    The screen 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 from this
    specific category logger to be logged in the defined format and
    locations.

  Configuration files
    As shown above, you can define "Log::Log4perl" loggers both from within
    your Perl code or from configuration files. The latter have the
    unbeatable advantage 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
    the module's logging behaviour to their needs.

    "Log::Log4perl" has been designed to understand "Log4j" configuration
    files -- as used by the original Java implementation. Instead of
    reiterating the format description in [2], let me just list three
    examples (also derived from [2]), which should also illustrate how 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 root
    hierarchy and has the system write them to the console.
    "ConsoleAppender" is a Java appender, but "Log::Log4perl" jumps through
    a significant number of hoops internally to map these to their
    corresponding 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 within the "Com::Foo" component
    and below are only forwarded to the appender if 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 logger
    picks it up and forwards it to the one and only appender of the root
    category, 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 the log
    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 thinks
    it should be logged, the appender doesn't just write it out haphazardly.
    There's ways to tell the appender how to format the message and add all
    sorts of interesting data to it: The date and time when the event
    happened, the file, the lin