view release on metacpan or  search on metacpan

lib/Log/Log4perl/FAQ.pm  view on Meta::CPAN

japanese Katakana characters.

=head2 How can I send errors to the screen, and debug messages to a file?

Let's assume you want to maintain a detailed DEBUG output in a file
and only messages of level ERROR and higher should be printed on the
screen. Often times, developers come up with something like this:

     # Wrong!!!
    log4perl.logger = DEBUG, FileApp
    log4perl.logger = ERROR, ScreenApp
     # Wrong!!!

This won't work, however. Logger definitions aren't additive, and the
second statement will overwrite the first one. Log4perl versions
below 1.04 were silently accepting this, leaving people confused why
it wouldn't work as expected.
As of 1.04, this will throw a I<fatal error> to notify the user of
the problem.

What you want to do instead, is this:

    log4perl.logger                    = DEBUG, FileApp, ScreenApp

    log4perl.appender.FileApp          = Log::Log4perl::Appender::File
    log4perl.appender.FileApp.filename = test.log
    log4perl.appender.FileApp.layout   = SimpleLayout

    log4perl.appender.ScreenApp          = Log::Log4perl::Appender::Screen
    log4perl.appender.ScreenApp.stderr   = 0
    log4perl.appender.ScreenApp.layout   = SimpleLayout
       ### limiting output to ERROR messages
    log4perl.appender.ScreenApp.Threshold = ERROR
       ###

Note that without the second appender's C<Threshold> setting, both appenders
would receive all messages prioritized DEBUG and higher. With the
threshold set to ERROR, the second appender will filter the messages
as required.

=head2 Where should I put my logfiles?

Your log files may go anywhere you want them, but the effective
user id of the calling process must have write access.

If the log file doesn't exist at program start, Log4perl's file appender
will create it. For this, it needs write access to the directory where
the new file will be located in. If the log file already exists at startup,
the process simply needs write access to the file. Note that it will
need write access to the file's directory if you're encountering situations
where the logfile gets recreated, e.g. during log rotation.

If Log::Log4perl is used by a web server application (e.g. in a CGI script
or mod_perl), then the webserver's user (usually C<nobody> or C<www>)
must have the permissions mentioned above.

To prepare your web server to use log4perl, we'd recommend:

    webserver:~$ su -
    webserver:~# mkdir /var/log/cgiapps
    webserver:~# chown nobody:root /var/log/cgiapps/
    webserver:~# chown nobody:root -R /var/log/cgiapps/
    webserver:~# chmod 02755 -R /var/log/cgiapps/

Then set your /etc/log4perl.conf file to include:

    log4perl.appender.FileAppndr1.filename =
        /var/log/cgiapps/<app-name>.log

=head2 How can my file appender deal with disappearing log files?

The file appender that comes with Log4perl, L<Log::Log4perl::Appender::File>,
will open a specified log file at initialization time and will
keep writing to it via a file handle.

In case the associated file goes way, messages written by a
long-running process will still be written
to the file handle. In case the file has been moved to a different
location on the same file system, the writer will keep writing to
it under the new filename. In case the file has been removed from
the file system, the log messages will end up in nowhere land. This
is not a bug in Log4perl, this is how Unix works. There is
no error message in this case, because the writer has no idea that
the file handle is not associated with a visible file.

To prevent the loss of log messages when log files disappear, the
file appender's C<recreate> option needs to be set to a true value:

    log4perl.appender.Logfile.recreate = 1

This will instruct the file appender to check in regular intervals
(default: 30 seconds) if the log file is still there. If it finds
out that the file is missing, it will recreate it.

Continuously checking if the log file still exists is fairly
expensive. For this reason it is only performed every 30 seconds. To
change this interval, the option C<recreate_check_interval> can be set
to the number of seconds between checks. In the extreme case where the
check should be performed before every write, it can even be set to 0:

    log4perl.appender.Logfile.recreate = 1
    log4perl.appender.Logfile.recreate_check_interval = 0

To avoid having to check the file system so frequently, a signal
handler can be set up:

    log4perl.appender.Logfile.recreate = 1
    log4perl.appender.Logfile.recreate_check_signal = USR1

This will install a signal handler which will recreate a missing log file
immediately when it receives the defined signal.

Note that the init_and_watch() method for Log4perl's initialization
can also be instructed to install a signal handler, usually using the
HUP signal. Make sure to use a different signal if you're using both
of them at the same time.

=head2 How can I rotate a logfile with newsyslog?

Here's a few things that need to be taken care of when using the popular
log file rotating utility C<newsyslog>
(http://www.courtesan.com/newsyslog) with Log4perl's file appender