package returning a string containing the path to the log file. Or, think about using the value of an environment variable: log4perl.appender.DBI.user = sub { $ENV{USERNAME} }; When Cinit()> parses the configuration file, it will notice the assignment above because of its C_{pattern and treat it in a special way:
It will evaluate the subroutine (which can contain
arbitrary Perl code) and take its return value as the right side
of the assignment.

A typical application would be called like this on the command line:

app # log file is "test.log"
app -l mylog.txt # log file is "mylog.txt"

Here's some sample code implementing the command line interface above:

use Log::Log4perl qw(get_logger);
use Getopt::Std;

getopt('l:', \our %OPTS);

my $conf = q(
log4perl.category.Bar.Twix = WARN, Logfile
log4perl.appender.Logfile = Log::Log4perl::Appender::File
log4perl.appender.Logfile.filename = sub { logfile(); };
log4perl.appender.Logfile.layout = SimpleLayout
);

Log::Log4perl::init(\$conf);

my $logger = get_logger("Bar::Twix");
$logger->error("Blah");

###########################################
sub logfile {
###########################################
if(exists $OPTS{l}) {
return $OPTS{l};
} else {
return "test.log";
}
}

Every Perl hook may contain arbitrary perl code,
just make sure to fully qualify eventual variable names
(e.g. C<%main::OPTS> instead of C<%OPTS>).

B: 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(). This will prevent Log::Log4perl from
executing I Perl code in the config file (including
code for custom conversion specifiers
(see L).

=head2 How can I roll over my logfiles automatically at midnight?

Long-running applications tend to produce ever-increasing logfiles.
For backup and cleanup purposes, however, it is often desirable to move
the current logfile to a different location from time to time and
start writing a new one.

This is a non-trivial task, because it has to happen in sync with
the logging system in order not to lose any messages in the process.

Luckily, I's C appender
works well with Log::Log4perl to rotate your logfiles in a variety of ways.

Note, however, that having the application deal with rotating a log
file is not cheap. Among other things, it requires locking the log file
with every write to avoid race conditions.
There are good reasons to use external rotators like C
instead.
See the entry C in the
FAQ for more information on how to configure it.

When using C,
all you have to do is specify it in your Log::Log4perl configuration file
and your logfiles will be rotated automatically.

You can choose between rolling based on a maximum size ("roll if greater
than 10 MB") or based on a date pattern ("roll everyday at midnight").
In both cases, C allows you to define a
number C of saved files to keep around until it starts overwriting
the oldest ones. If you set the C parameter to 2 and the name of
your logfile is C, C will
move C to C on the first rollover. On the second
rollover, it will move C to C and then C
to C. On the third rollover, it will move C to
C (therefore discarding the old C) and
C to C. And so forth. This way, there's always
going to be a maximum of 2 saved log files around.

Here's an example of a Log::Log4perl configuration file, defining a
daily rollover at midnight (date pattern C), keeping
a maximum of 5 saved logfiles around:

log4perl.category = WARN, Logfile
log4perl.appender.Logfile = Log::Dispatch::FileRotate
log4perl.appender.Logfile.filename = test.log
log4perl.appender.Logfile.max = 5
log4perl.appender.Logfile.DatePattern = yyyy-MM-dd
log4perl.appender.Logfile.TZ = PST
log4perl.appender.Logfile.layout = \
Log::Log4perl::Layout::PatternLayout
log4perl.appender.Logfile.layout.ConversionPattern = %d %m %n

Please see the C documentation for details.
C is available on CPAN.

=head2 What's the easiest way to turn off all logging, even with a lengthy Log4perl configuration file?

In addition to category-based levels and appender thresholds,
Log::Log4perl supports system-wide logging thresholds. This is the
minimum level the system will require of any logging events in order for them
to make it through to any configured appenders.

For example, putting the line

log4perl.threshold = ERROR

anywhere in your configuration file will limit any output to any appender
to events with priority of ERROR or higher (ERROR or FATAL that is).

However, in order to suppress all logging entirely, you need to use a
priority that's higher than FATAL: It is simply called C, and it is never
used by any logger. By definition, it is higher than the highest
defined logger level.

Therefore, if you keep the line

log4perl.threshold = OFF

somewhere in your Log::Log4perl configuration, the system will be quiet
as a graveyard. If you deactivate the line (e.g. by commenting it out),
the system will, upon config reload, snap back to normal operation, providing
logging messages according to the rest of the configuration file again.

=head2 I keep getting duplicate log messages! What's wrong?

Having several settings for related categories in the Log4perl
configuration file sometimes leads to a phenomenon called
"message duplication". It can be very confusing at first,
but if thought through properly, it turns out that Log4perl behaves
as advertised. But, don't despair, of course there's a number of
ways to avoid message duplication in your logs.

Here's a sample Log4perl configuration file that produces the
phenomenon:

log4perl.logger.Cat = ERROR, Screen
log4perl.logger.Cat.Subcat = WARN, Screen

log4perl.appender.Screen = Log::Log4perl::Appender::Screen
log4perl.appender.Screen.layout = SimpleLayout

It defines two loggers, one for category C and one for
C, which is obviously a subcategory of C.
The parent logger has a priority setting of ERROR, the child
is set to the lower C level.

Now imagine the following code in your program:

my $logger = get_logger("Cat.Subcat");
$logger->warn("Warning!");

What do you think will happen? An unexperienced Log4perl user
might think: "Well, the message is being sent with level WARN, so the
C logger will accept it and forward it to the
attached C appender. Then, the message will percolate up
the logger hierarchy, find
the C logger, which will suppress the message because of its
ERROR setting."
But, perhaps surprisingly, what you'll get with the
code snippet above is not one but two log messages written
to the screen:

WARN - Warning!
WARN - Warning!

What happened? The culprit is that once the logger C
decides to fire, it will forward the message I
to all directly or indirectly attached appenders. The C logger
will never be asked if it wants the message or not -- the message
will just be pushed through to the appender attached to C.

One way to prevent the message from bubbling up the logger
hierarchy is to set the C flag of the subordinate logger to
C<0>:

log4perl.logger.Cat = ERROR, Screen
log4perl.logger.Cat.Subcat = WARN, Screen
log4perl.additivity.Cat.Subcat = 0

log4perl.appender.Screen = Log::Log4perl::Appender::Screen
log4perl.appender.Screen.layout = SimpleLayout

The message will now be accepted by the C logger,
forwarded to its appender, but then C will suppress
any further action. While this setting avoids duplicate messages
as seen before, it is often not the desired behaviour. Messages
percolating up the hierarchy are a useful Log4perl feature.

If you're defining I appenders for the two loggers,
one other option is to define an appender threshold for the
higher-level appender. Typically it is set to be
equal to the logger's level setting:

log4perl.logger.Cat = ERROR, Screen1
log4perl.logger.Cat.Subcat = WARN, Screen2

log4perl.appender.Screen1 = Log::Log4perl::Appender::Screen
log4perl.appender.Screen1.layout = SimpleLayout
log4perl.appender.Screen1.Threshold = ERROR

log4perl.appender.Screen2 = Log::Log4perl::Appender::Screen
log4perl.appender.Screen2.layout = SimpleLayout

Since the C appender now blocks every message with
a priority less than ERROR, even if the logger in charge
lets it through, the message percolating up the hierarchy is
being blocked at the last minute and I appended to C.

So far, we've been operating well within the boundaries of the
Log4j standard, which Log4perl adheres to. However, if
you would really, really like to use a single appender
and keep the message percolation intact without having to deal
with message duplication, there's a non-standard solution for you:

log4perl.logger.Cat = ERROR, Screen
log4perl.logger.Cat.Subcat = WARN, Screen

log4perl.appender.Screen = Log::Log4perl::Appender::Screen
log4perl.appender.Screen.layout = SimpleLayout

log4perl.oneMessagePerAppender = 1

The C flag will suppress duplicate messages
to the same appender. Again, that's non-standard. But way cool :).

=head2 How can I configure Log::Log4perl to send me email if something happens?

Some incidents require immediate action. You can't wait until someone
checks the log files, you need to get notified on your pager right away.

The easiest way to do that is by using the C
module as an appender. It comes with the C bundle and
allows you to specify recipient and subject of outgoing emails in the Log4perl
configuration file:

log4perl.category = FATAL, Mailer
log4perl.appender.Mailer = Log::Dispatch::Email::MailSend
log4perl.appender.Mailer.to = drone@pageme.net
log4perl.appender.Mailer.subject = Something's broken!
log4perl.appender.Mailer.layout = SimpleLayout

The message of every log incident this appender gets
will then be forwarded to the given
email address. Check the C documentation
for details. And please make sure there's not a flood of email messages
sent out by your application, filling up the receipient's inbox.

There's one caveat you need to know about: The C
hierarchy of appenders turns on I by default. This means that
the appender will not send out messages right away but wait until a
certain threshold has been reached. If you'd rather have your alerts
sent out immeditately, use

log4perl.appender.Mailer.buffered = 0

to turn buffering off.

=head2 How can I write my own appender?

First off, Log::Log4perl comes with a set of standard appenders. Then,
there's a lot of Log4perl-compatible appenders already
available on CPAN: Just run a search for C on
http://search.cpan.org and chances are that what you're looking for
has already been developed, debugged and been used successfully
in production -- no need for you to reinvent the wheel.

Also, Log::Log4perl ships with a nifty database appender named
Log::Log4perl::Appender::DBI -- check it out if talking to databases is your
desire.

But if you're up for a truly exotic task, you might have to write
an appender yourself. That's very easy -- it takes no longer
than a couple of minutes.

Say, we wanted to create an appender of the class
C, which logs messages
to the screen in a configurable color. Just create a new class
in C:

package ColorScreenAppender;

Now let's assume that your Log::Log4perl
configuration file C looks like this:

log4perl.logger = INFO, ColorApp

log4perl.appender.ColorApp=ColorScreenAppender
log4perl.appender.ColorApp.color=blue

log4perl.appender.ColorApp.layout = PatternLayout
log4perl.appender.ColorApp.layout.ConversionPattern=%d %m %n

This will cause Log::Log4perl on C to look for a class
ColorScreenAppender and call its constructor new(). Let's add
new() to ColorScreenAppender.pm:

sub new {
my($class, %options) = @_;

my $self = { %options };
bless $self, $class;

return $self;
}

To initialize this appender, Log::Log4perl will call
and pass all attributes of the appender as defined in the configuration
file to the constructor as name/value pairs (in this case just one):

ColorScreenAppender->new(color => "blue");

The new() method listed above stores the contents of the
%options hash in the object's
instance data hash (referred to by $self).
That's all for initializing a new appender with Log::Log4perl.

Second, ColorScreenAppender needs to expose a
C method, which will be called by Log::Log4perl
every time it thinks the appender should fire. Along with the
object reference (as usual in Perl's object world), log()
will receive a list of name/value pairs, of which only the one
under the key C shall be of interest for now since it is the
message string to be logged. At this point, Log::Log4perl has already taken
care of joining the message to be a single string.

For our special appender ColorScreenAppender, we're using the
Term::ANSIColor module to colorize the output:

use Term::ANSIColor;

sub log {
my($self, %params) = @_;

print colored($params{message},
$self->{color});
}

The color (as configured in the Log::Log4perl configuration file)
is available as $self-E{color} in the appender object. Don't
forget to return

1;

at the end of ColorScreenAppender.pm and you're done. Install the new appender
somewhere where perl can find it and try it with a test script like

use Log::Log4perl qw(:easy);
Log::Log4perl->init("test.conf");
ERROR("blah");

to see the new colored output. Is this cool or what?

And it gets even better: You can write dynamically generated appender
classes using the C module. Here's an example of
an appender prepending every outgoing message with a configurable
number of bullets:

use Class::Prototyped;

my $class = Class::Prototyped->newPackage(
"MyAppenders::Bulletizer",
bullets => 1,
log => sub {
my($self, %params) = @_;
print "*" x $self->bullets(),
$params{message};
},
);

use Log::Log4perl qw(:easy);

Log::Log4perl->init(\ q{
log4perl.logger = INFO, Bully

log4perl.appender.Bully=MyAppenders::Bulletizer
log4perl.appender.Bully.bullets=3

log4perl.appender.Bully.layout = PatternLayout
log4perl.appender.Bully.layout.ConversionPattern=%m %n
});

# ... prints: "***Boo!\n";
INFO "Boo!";

=head2 How can I drill down on references before logging them?

If you've got a reference to a nested structure or object, then
you probably don't want to log it as C but rather
dump it as something like

$VAR1 = {
'a' => 'b',
'd' => 'e'
};

via a module like Data::Dumper. While it's syntactically correct to say

$logger->debug(Data::Dumper::Dumper($ref));

this call imposes a huge performance penalty on your application
if the message is suppressed by Log::Log4perl, because Data::Dumper
will perform its expensive operations in any case, because it doesn't
know that its output will be thrown away immediately.

As of Log::Log4perl 0.28, there's a better way: Use the
message output filter format as in

$logger->debug( {filter => \&Data::Dumper::Dumper,
value => $ref} );

and Log::Log4perl won't call the filter function unless the message really
gets written out to an appender. Just make sure to pass the whole slew as a
reference to a hash specifying a filter function (as a sub reference)
under the key C and the value to be passed to the filter function in
C).
When it comes to logging, Log::Log4perl will call the filter function,
pass the C as an argument and log the return value.
Saves you serious cycles.

=head2 How can I collect all FATAL messages in an extra log file?

Suppose you have employed Log4perl all over your system and you've already
activated logging in various subsystems. On top of that, without disrupting
any other settings, how can you collect all FATAL messages all over the system
and send them to a separate log file?

If you define a root logger like this:

log4perl.logger = FATAL, File
log4perl.appender.File = Log::Log4perl::Appender::File
log4perl.appender.File.filename = /tmp/fatal.txt
log4perl.appender.File.layout = PatternLayout
log4perl.appender.File.layout.ConversionPattern= %d %m %n
# !!! Something's missing ...

you'll be surprised to not only receive all FATAL messages
issued anywhere in the system,
but also everything else -- gazillions of
ERROR, WARN, INFO and even DEBUG messages will end up in
your fatal.txt logfile!
Reason for this is Log4perl's (or better: Log4j's) appender additivity.
Once a
lower-level logger decides to fire, the message is going to be forwarded
to all appenders upstream -- without further priority checks with their
attached loggers.

There's a way to prevent this, however: If your appender defines a
minimum threshold, only messages of this priority or higher are going
to be logged. So, just add

log4perl.appender.File.Threshold = FATAL

to the configuration above, and you'll get what you wanted in the
first place: An overall system FATAL message collector.

=head2 How can I bundle several log messages into one?

Would you like to tally the messages arriving at your appender and
dump out a summary once they're exceeding a certain threshold?
So that something like

$logger->error("Blah");
$logger->error("Blah");
$logger->error("Blah");

won't be logged as

Blah
Blah
Blah

but as

[3] Blah

instead? If you'd like to hold off on logging a message until it has been
sent a couple of times, you can roll that out by creating a buffered
appender.

Let's define a new appender like

package TallyAppender;

sub new {
my($class, %options) = @_;

my $self = { maxcount => 5,
%options
};

bless $self, $class;

$self->{last_message} = "";
$self->{last_message_count} = 0;

return $self;
}

with two additional instance variables C and
C, storing the content of the last message sent
and a counter of how many times this has happened. Also, it features
a configuration parameter C which defaults to 5 in the
snippet above but can be set in the Log4perl configuration file like this:

log4perl.logger = INFO, A
log4perl.appender.A=TallyAppender
log4perl.appender.A.maxcount = 3

The main tallying logic lies in the appender's C method,
which is called every time Log4perl thinks a message needs to get logged
by our appender:

sub log {
my($self, %params) = @_;

# Message changed? Print buffer.
if($self->{last_message} and
$params{message} ne $self->{last_message}) {
print "[$self->{last_message_count}]: " .
"$self->{last_message}";
$self->{last_message_count} = 1;
$self->{last_message} = $params{message};
return;
}

$self->{last_message_count}++;
$self->{last_message} = $params{message};

# Threshold exceeded? Print, reset counter
if($self->{last_message_count} >=
$self->{maxcount}) {
print "[$self->{last_message_count}]: " .
"$params{message}";
$self->{last_message_count} = 0;
$self->{last_message} = "";
return;
}
}

We basically just check if the oncoming message in C<$param{message}>
is equal to what we've saved before in the C instance
variable. If so, we're increasing C.
We print the message in two cases: If the new message is different
than the buffered one, because then we need to dump the old stuff
and store the new. Or, if the counter exceeds the threshold, as
defined by the C configuration parameter.

Please note that the appender always gets the fully rendered message and
just compares it as a whole -- so if there's a date/timestamp in there,
that might confuse your logic. You can work around this by specifying
%m %n as a layout and add the date later on in the appender. Or, make
the comparison smart enough to omit the date.

At last, don't forget what happens if the program is being shut down.
If there's still messages in the buffer, they should be printed out
at that point. That's easy to do in the appender's DESTROY method,
which gets called at object destruction time:

sub DESTROY {
my($self) = @_;

if($self->{last_message_count}) {
print "[$self->{last_message_count}]: " .
"$self->{last_message}";
return;
}
}

This will ensure that none of the buffered messages are lost.
Happy buffering!

=head2 I want to log ERROR and WARN messages to different files! How can I do that?

Let's assume you wanted to have each logging statement written to a
different file, based on the statement's priority. Messages with priority
C are supposed to go to C, events prioritized
as C should end up in C.

Now, if you define two appenders C and C
and assign them both to the root logger,
messages bubbling up from any loggers below will be logged by both
appenders because of Log4perl's message propagation feature. If you limit
their exposure via the appender threshold mechanism and set
C's threshold to C and C's to C, you'll
still get C messages in C, because C's C
setting will just filter out messages with a I priority than
C -- C is higher and will be allowed to pass through.

What we need for this is a Log4perl I, available with
Log::Log4perl 0.30.

Both appenders need to verify that
the priority of the oncoming messages exactly I the priority
the appender is supposed to log messages of. To accomplish this task,
let's define two custom filters, C and C, which,
when attached to their appenders, will limit messages passed on to them
to those matching a given priority:

log4perl.logger = WARN, AppWarn, AppError

# Filter to match level ERROR
log4perl.filter.MatchError = Log::Log4perl::Filter::LevelMatch
log4perl.filter.MatchError.LevelToMatch = ERROR
log4perl.filter.MatchError.AcceptOnMatch = true

# Filter to match level WARN
log4perl.filter.MatchWarn = Log::Log4perl::Filter::LevelMatch
log4perl.filter.MatchWarn.LevelToMatch = WARN
log4perl.filter.MatchWarn.AcceptOnMatch = true

# Error appender
log4perl.appender.AppError = Log::Log4perl::Appender::File
log4perl.appender.AppError.filename = /tmp/app.err
log4perl.appender.AppError.layout = SimpleLayout
log4perl.appender.AppError.Filter = MatchError

# Warning appender
log4perl.appender.AppWarn = Log::Log4perl::Appender::File
log4perl.appender.AppWarn.filename = /tmp/app.warn
log4perl.appender.AppWarn.layout = SimpleLayout
log4perl.appender.AppWarn.Filter = MatchWarn

The appenders C and C defined above are logging to C and
C respectively and have the custom filters C and C
attached.
This setup will direct all WARN messages, issued anywhere in the system, to /tmp/app.warn (and
ERROR messages to /tmp/app.error) -- without any overlaps.

=head2 On our server farm, Log::Log4perl configuration files differ slightly from host to host. Can I roll them all into one?

You sure can, because Log::Log4perl allows you to specify attribute values
dynamically. Let's say that one of your appenders expects the host's IP address
as one of its attributes. Now, you could certainly roll out different
configuration files for every host and specify the value like

log4perl.appender.MyAppender = Log::Log4perl::Appender::SomeAppender
log4perl.appender.MyAppender.ip = 10.0.0.127

but that's a maintenance nightmare. Instead, you can have Log::Log4perl
figure out the IP address at configuration time and set the appender's
value correctly:

# Set the IP address dynamically
log4perl.appender.MyAppender = Log::Log4perl::Appender::SomeAppender
log4perl.appender.MyAppender.ip = sub { \
use Sys::Hostname; \
use Socket; \
return inet_ntoa(scalar gethostbyname hostname); \
}

If Log::Log4perl detects that an attribute value starts with something like
C<"sub {...">, it will interpret it as a perl subroutine which is to be executed
once at configuration time (not runtime!) and its return value is
to be used as the attribute value. This comes in handy
for rolling out applications whichs Log::Log4perl configuration files
show small host-specific differences, because you can deploy the unmodified
application distribution on all instances of the server farm.

=head2 Log4perl doesn't interpret my backslashes correctly!

If you're using Log4perl's feature to specify the configuration as a
string in your program (as opposed to a separate configuration file),
chances are that you've written it like this:

# *** WRONG! ***

Log::Log4perl->init( \ <EEND_HERE>) and that Perl won't
interpret backslashes at line-ends as continuation characters but
will essentially throw them out. So, in the code above, the layout line
will look like

log4perl.appender.A1.layout =

to Log::Log4perl which causes it to report an error. To interpret the backslash
at the end of the line correctly as a line-continuation character, use
the non-interpreting mode of the here-document like in

# *** RIGHT! ***

Log::Log4perl->init( \ <<'END_HERE');
log4perl.logger = WARN, A1
log4perl.appender.A1 = Log::Log4perl::Appender::Screen
log4perl.appender.A1.layout = \
Log::Log4perl::Layout::PatternLayout
log4perl.appender.A1.layout.ConversionPattern = %m%n
END_HERE

# *** RIGHT! ***

(note the single quotes around C<'END_HERE'>) or use C
instead of a here-document and Perl will treat the backslashes at
line-end as intended.

=head2 I want to suppress certain messages based on their content!

Let's assume you've plastered all your functions with Log4perl
statements like

sub some_func {

INFO("Begin of function");

# ... Stuff happens here ...

INFO("End of function");
}

to issue two log messages, one at the beginning and one at the end of
each function. Now you want to suppress the message at the beginning
and only keep the one at the end, what can you do? You can't use the category
mechanism, because both messages are issued from the same package.

Log::Log4perl's custom filters (0.30 or better) provide an interface for the
Log4perl user to step in right before a message gets logged and decide if
it should be written out or suppressed, based on the message content or other
parameters:

use Log::Log4perl qw(:easy);

Log::Log4perl::init( \ <<'EOT' );
log4perl.logger = INFO, A1
log4perl.appender.A1 = Log::Log4perl::Appender::Screen
log4perl.appender.A1.layout = \
Log::Log4perl::Layout::PatternLayout
log4perl.appender.A1.layout.ConversionPattern = %m%n

log4perl.filter.M1 = Log::Log4perl::Filter::StringMatch
log4perl.filter.M1.StringToMatch = Begin
log4perl.filter.M1.AcceptOnMatch = false

log4perl.appender.A1.Filter = M1
EOT

The last four statements in the configuration above are defining a custom
filter C of type C, which comes with
Log4perl right out of the box and allows you to define a text pattern to match
(as a perl regular expression) and a flag C indicating
if a match is supposed to suppress the message or let it pass through.

The last line then assigns this filter to the C appender, which will
call it every time it receives a message to be logged and throw all
messages out I matching the regular expression C.

Instead of using the standard C filter,
you can define your own, simply using a perl subroutine:

log4perl.filter.ExcludeBegin = sub { !/Begin/ }
log4perl.appender.A1.Filter = ExcludeBegin

For details on custom filters, check L.

=head2 My new module uses Log4perl -- but what happens if the calling program didn't configure it?

If a Perl module uses Log::Log4perl, it will typically rely on the
calling program to initialize it. If it is using Log::Log4perl in C<:easy>
mode, like in

package MyMod;
use Log::Log4perl qw(:easy);

sub foo {
DEBUG("In foo");
}

1;

and the calling program doesn't initialize Log::Log4perl at all (e.g. because
it has no clue that it's available), Log::Log4perl will silently
ignore all logging messages. However, if the module is using Log::Log4perl
in regular mode like in

package MyMod;
use Log::Log4perl qw(get_logger);

sub foo {
my $logger = get_logger("");
$logger->debug("blah");
}

1;

and the main program is just using the module like in

use MyMode;
MyMode::foo();

then Log::Log4perl will also ignore all logging messages but
issue a warning like

Log4perl: Seems like no initialization happened.
Forgot to call init()?

(only once!) to remind novice users to not forget to initialize
the logging system before using it.
However, if you want to suppress this message, just
add the C<:nowarn> target to the module's C call:

use Log::Log4perl qw(get_logger :nowarn);

This will have Log::Log4perl silently ignore all logging statements if
no initialization has taken place.

If the module wants to figure out if some other program part has
already initialized Log::Log4perl, it can do so by calling

Log::Log4perl::initialized()

which will return a true value in case Log::Log4perl has been initialized
and a false value if not.

=head2 How can I synchronize access to an appender?

If you're using the same instance of an appender in multiple processes,
and each process is passing on messages to the appender in parallel,
you might end up with overlapping log entries.

Typical scenarios include a file appender that you create in the main
program, and which will then be shared between the parent and a
forked child process. Or two separate processes, each initializing a
Log4perl file appender on the same logfile.

Log::Log4perl won't synchronize access to the shared logfile by
default. Depending on your operating system's flush mechanism,
buffer size and the size of your messages, there's a small chance of
an overlap.

The easiest way to prevent overlapping messages in logfiles written to
by multiple processes is setting the
file appender's C flag along with a file write mode of C<"append">.
This makes sure that
C uses C (which is guaranteed
to run uninterrupted) instead of C which might buffer
the message or get interrupted by the OS while it is writing. And in
C<"append"> mode, the OS kernel ensures that multiple processes share
one end-of-file marker, ensuring that each process writes to the I
end of the file. (The value of C<"append">
for the C parameter is the default setting in Log4perl's file
appender so you don't have to set it explicitely.)

# Guarantees atomic writes

log4perl.category.Bar.Twix = WARN, Logfile

log4perl.appender.Logfile = Log::Log4perl::Appender::File
log4perl.appender.Logfile.mode = append
log4perl.appender.Logfile.syswrite = 1
log4perl.appender.Logfile.filename = test.log
log4perl.appender.Logfile.layout = SimpleLayout

Another guaranteed way of having messages separated with any kind of
appender is putting a Log::Log4perl::Appender::Synchronized composite
appender in between Log::Log4perl and the real appender. It will make
sure to let messages pass through this virtual gate one by one only.

Here's a sample configuration to synchronize access to a file appender:

log4perl.category.Bar.Twix = WARN, Syncer

log4perl.appender.Logfile = Log::Log4perl::Appender::File
log4perl.appender.Logfile.autoflush = 1
log4perl.appender.Logfile.filename = test.log
log4perl.appender.Logfile.layout = SimpleLayout

log4perl.appender.Syncer = Log::Log4perl::Appender::Synchronized
log4perl.appender.Syncer.appender = Logfile

C uses
the C module and its semaphores, which will slow down writing
the log messages, but ensures sequential access featuring atomic checks.
Check L for details.

=head2 Can I use Log::Log4perl with log4j's Chainsaw?

Yes, Log::Log4perl can be configured to send its events to log4j's
graphical log UI I.

=for html

Figure 1: Chainsaw receives Log::Log4perl events

=for text
Figure1: Chainsaw receives Log::Log4perl events

Here's how it works:

=over 4

=item *

Get Guido Carls' Egcarls@cpan.orgE Log::Log4perl extension
C from CPAN and install it:

perl -MCPAN -eshell
cpan> install Log::Log4perl::Layout::XMLLayout

=item *

Install and start Chainsaw, which is part of the C distribution now
(see http://jakarta.apache.org/log4j ). Create a configuration file like

and name it e.g. C. Then start Chainsaw like

java -Dlog4j.debug=true -Dlog4j.configuration=config.xml \
-classpath ".:log4j-1.3alpha.jar:log4j-chainsaw-1.3alpha.jar" \
org.apache.log4j.chainsaw.LogUI

and watch the GUI coming up.

=item *

Configure Log::Log4perl to use a socket appender with an XMLLayout, pointing
to the host/port where Chainsaw (as configured above) is waiting with its
XMLSocketReceiver:

use Log::Log4perl qw(get_logger);
use Log::Log4perl::Layout::XMLLayout;

my $conf = q(
log4perl.category.Bar.Twix = WARN, Appender
log4perl.appender.Appender = Log::Log4perl::Appender::Socket
log4perl.appender.Appender.PeerAddr = localhost
log4perl.appender.Appender.PeerPort = 4445
log4perl.appender.Appender.layout = Log::Log4perl::Layout::XMLLayout
);

Log::Log4perl::init(\$conf);

# Nasty hack to suppress encoding header
my $app = Log::Log4perl::appenders->{"Appender"};
$app->layout()->{enc_set} = 1;

my $logger = get_logger("Bar.Twix");
$logger->error("One");

The nasty hack shown in the code snippet above is currently (October 2003)
necessary, because Chainsaw expects XML messages to arrive in a format like

without a preceding

which Log::Log4perl::Layout::XMLLayout applies to the first event sent
over the socket.

=back

See figure 1 for a screenshot of Chainsaw in action, receiving events from
the Perl script shown above.

Many thanks to Chainsaw's
Scott Deboy for his support!

=head2 How can I run Log::Log4perl under mod_perl?

In persistent environments it's important to play by the rules outlined
in section L.
If you haven't read this yet, please go ahead and read it right now. It's
very important.

And no matter if you use a startup handler to init() Log::Log4perl or use the
init_once() strategy (added in 0.42), either way you're very likely to have
unsynchronized writes to logfiles.

If Log::Log4perl is configured with a log file appender, and it is
initialized via
the Apache startup handler, the file handle created initially will be
shared among all Apache processes. Similarly, with the init_once()
approach: although every process has a separate L4p configuration,
processes are gonna share the appender file I instead, effectively
opening several different file handles on the same file.

Now, having several appenders using the same file handle or having
several appenders logging to the same file unsynchronized, this might
result in overlapping messages. Sometimes, this is acceptable. If it's
not, here's two strategies:

=over 4

=item *

Use the L appender to connect to
your file appenders. Here's the writeup:
http://log4perl.sourceforge.net/releases/Log-Log4perl/docs/html/Log/Log4perl/FAQ.html#23804

=item *

Use a different logfile for every process like in

#log4perl.conf
...
log4perl.appender.A1.filename = sub { "mylog.$$.log" }

=back

=head2 My program already uses warn() and die(). How can I switch to Log4perl?

If your program already uses Perl's C function to spew out
error messages and you'd like to channel those into the Log4perl world,
just define a C<__WARN__> handler where your program or module resides:

use Log::Log4perl qw(:easy);

$SIG{__WARN__} = sub {
local $Log::Log4perl::caller_depth =
$Log::Log4perl::caller_depth + 1;
WARN @_;
};

Why the C setting of C<$Log::Log4perl::caller_depth>?
If you leave that out,
C conversion specifiers like C<%M> or C<%F> (printing
the current function/method and source filename) will refer
to where the __WARN__ handler resides, not the environment
Perl's C function was issued from. Increasing C
adjusts for this offset. Having it C, makes sure the level
gets set back after the handler exits.

Once done, if your program does something like

sub some_func {
warn "Here's a warning";
}

you'll get (depending on your Log::Log4perl configuration) something like

2004/02/19 20:41:02-main::some_func: Here's a warning at ./t line 25.

in the appropriate appender instead of having a screen full of STDERR
messages. It also works with the C module and its C
and C functions.

If, on the other hand, catching C and friends is
required, a C<__DIE__> handler is appropriate:

$SIG{__DIE__} = sub {
if($^S) {
# We're in an eval {} and don't want log
# this message but catch it later
return;
}
$Log::Log4perl::caller_depth++;
LOGDIE @_;
};

This will call Log4perl's C function, which will log a fatal
error and then call die() internally, causing the program to exit. Works
equally well with C's C and C functions.

=head2 Some module prints messages to STDERR. How can I funnel them to Log::Log4perl?

If a module you're using doesn't use Log::Log4perl but prints logging
messages to STDERR instead, like

########################################
package IgnorantModule;
########################################

sub some_method {
print STDERR "Parbleu! An error!\n";
}

1;

there's still a way to capture these messages and funnel them
into Log::Log4perl, even without touching the module. What you need is
a trapper module like

########################################
package Trapper;
########################################

use Log::Log4perl qw(:easy);

sub TIEHANDLE {
my $class = shift;
bless [], $class;
}

sub PRINT {
my $self = shift;
$Log::Log4perl::caller_depth++;
DEBUG @_;
$Log::Log4perl::caller_depth--;
}

1;

and a C command in the main program to tie STDERR to the trapper
module along with regular Log::Log4perl initialization:

########################################
package main;
########################################

use Log::Log4perl qw(:easy);

Log::Log4perl->easy_init(
{level => $DEBUG,
file => 'stdout', # make sure not to use stderr here!
layout => "%d %M: %m%n",
});

tie *STDERR, "Trapper";

Make sure not to use STDERR as Log::Log4perl's file appender
here (which would be the default in C<:easy> mode), because it would
end up in an endless recursion.

Now, calling

IgnorantModule::some_method();

will result in the desired output

2004/05/06 11:13:04 IgnorantModule::some_method: Parbleu! An error!

=head2 How come PAR (Perl Archive Toolkit) creates executables which then can't find their Log::Log4perl appenders?

If not instructed otherwise, C dynamically pulls in
appender classes found in its configuration. If you specify

#!/usr/bin/perl
# mytest.pl

use Log::Log4perl qw(get_logger);

my $conf = q(
log4perl.category.Bar.Twix = WARN, Logfile
log4perl.appender.Logfile = Log::Log4perl::Appender::Screen
log4perl.appender.Logfile.layout = SimpleLayout
);

Log::Log4perl::init(\$conf);
my $logger = get_logger("Bar::Twix");
$logger->error("Blah");

then C will be pulled in while the program
runs, not at compile time. If you have PAR compile the script above to an
executable binary via

pp -o mytest mytest.pl

and then run C on a machine without having Log::Log4perl installed,
you'll get an error message like

ERROR: can't load appenderclass 'Log::Log4perl::Appender::Screen'
Can't locate Log/Log4perl/Appender/Screen.pm in @INC ...

Why? At compile time, C didn't realize that
C would be needed later on and didn't
wrap it into the executable created. To avoid this, either say
C in the script explicitely or
compile it with

pp -o mytest -M Log::Log4perl::Appender::Screen mytest.pl

to make sure the appender class gets included.

=head2 How can I access a custom appender defined in the configuration?

Any appender defined in the configuration file or somewhere in the code
can be accessed later via
Cappender_by_name("appender_name")>,
which returns a reference the the appender object.

Once you've got a hold of the object, it can be queried or modified to
your liking. For example, see the custom C defined below:
After calling C to define the Log4perl settings, the
appender object is retrieved to call its C and C
methods to control indentation of messages:

package IndentAppender;

sub new {
bless { indent => 0 }, $_[0];
}

sub indent_more { $_[0]->{indent}++ }
sub indent_less { $_[0]->{indent}-- }

sub log {
my($self, %params) = @_;
print " " x $self->{indent}, $params{message};
}

package main;

use Log::Log4perl qw(:easy);

my $conf = q(
log4perl.category = DEBUG, Indented
log4perl.appender.Indented = IndentAppender
log4perl.appender.Indented.layout = Log::Log4perl::Layout::SimpleLayout
);

Log::Log4perl::init(\$conf);

my $appender = Log::Log4perl->appender_by_name("Indented");

DEBUG "No identation";
$appender->indent_more();
DEBUG "One more";
$appender->indent_more();
DEBUG "Two more";
$appender->indent_less();
DEBUG "One less";

As you would expect, this will print

DEBUG - No identation
DEBUG - One more
DEBUG - Two more
DEBUG - One less

because the very appender used by Log4perl is modified dynamically at
runtime.

=head2 I don't know if Log::Log4perl is installed. How can I prepare my script?

In case your script needs to be prepared for environments that may or may
not have Log::Log4perl installed, there's a trick.

If you put the following BEGIN blocks at the top of the program,
you'll be able to use the DEBUG(), INFO(), etc. macros in
Log::Log4perl's C<:easy> mode.
If Log::Log4perl
is installed in the target environment, the regular Log::Log4perl rules
apply. If not, all of DEBUG(), INFO(), etc. are "stubbed" out, i.e. they
turn into no-ops:

use warnings;
use strict;

BEGIN {
eval { require Log::Log4perl; };

if($@) {
print "Log::Log4perl not installed - stubbing.\n";
no strict qw(refs);
*{"main::$_"} = sub { } for qw(DEBUG INFO WARN ERROR FATAL);
} else {
no warnings;
print "Log::Log4perl installed - life is good.\n";
require Log::Log4perl::Level;
Log::Log4perl::Level->import(__PACKAGE__);
Log::Log4perl->import(qw(:easy));
Log::Log4perl->easy_init($main::DEBUG);
}
}

# The regular script begins ...
DEBUG "Hey now!";

This snippet will first probe for Log::Log4perl, and if it can't be found,
it will alias DEBUG(), INFO(), with empty subroutines via typeglobs.
If Log::Log4perl is available, its level constants are first imported
(C<$DEBUG>, C<$INFO>, etc.) and then C gets called to initialize
the logging system.

=head2 Can file appenders create files with different permissions?

Typically, when C creates a new file,
its permissions are set to C. Why? Because your
environment's I most likely defaults to
C<0022>, that's the standard setting.

What's a I, you're asking? It's a template that's applied to
the permissions of all newly created files. While calls like
Cfoo")> will always try to create files in C mode, the system will apply the current I template to
determine the final permission setting. I is a bit mask that's
inverted and then applied to the requested permission setting, using a
bitwise AND:

$request_permission &~ $umask

So, a I setting of 0000 (the leading 0 simply indicates an
octal value) will create files in C mode, a setting of 0277
will use C, and the standard 0022 will use C.

As an example, if you want your log files to be created with
C permissions, use a I of C<0020> before
calling Log::Log4perl->init():

use Log::Log4perl;

umask 0020;
# Creates log.out in rw-r--rw mode
Log::Log4perl->init(\ q{
log4perl.logger = WARN, File
log4perl.appender.File = Log::Log4perl::Appender::File
log4perl.appender.File.filename = log.out
log4perl.appender.File.layout = SimpleLayout
});

=head2 Using Log4perl in an END block causes a problem!

It's not easy to get to this error, but if you write something like

END { Log::Log4perl::get_logger()->debug("Hey there."); }

use Log::Log4perl qw(:easy);
Log::Log4perl->easy_init($DEBUG);

it won't work. The reason is that C defines an
END block that cleans up all loggers. And perl will run END blocks
in the reverse order as they're encountered in the compile phase,
so in the scenario above, the END block will run I Log4perl
has cleaned up its loggers.

Placing END blocks using Log4perl I
a C statement fixes the problem:

use Log::Log4perl qw(:easy);
Log::Log4perl->easy_init($DEBUG);

END { Log::Log4perl::get_logger()->debug("Hey there."); }

In this scenario, the shown END block is executed I Log4perl
cleans up and the debug message will be processed properly.

=head2 Help! My appender is throwing a "Wide character in print" warning!

This warning shows up when Unicode strings are printed without
precautions. The warning goes away if the complaining appender is
set to utf-8 mode:

# Either in the log4perl configuration file:
log4perl.appender.Logfile.filename = test.log
log4perl.appender.Logfile.utf8 = 1

# Or, in easy mode:
Log::Log4perl->easy_init( {
level => $DEBUG,
file => ":utf8> test.log"
} );

If the complaining appender is a screen appender, C does the trick:

# Either STDOUT ...
binmode(STDOUT, ":utf8);

# ... or STDERR.
binmode(STDERR, ":utf8);

Some background on this: Perl's strings are either byte strings or
Unicode strings. C<"Mike"> is a byte string.
C<"\x{30DE}\x{30A4}\x{30AF}"> is a Unicode string. Unicode strings are
marked specially and are UTF-8 encoded internally.

If you print a byte string to STDOUT,
all is well, because STDOUT is by default set to byte mode. However,
if you print a Unicode string to STDOUT without precautions, C
will try to transform the Unicode string back to a byte string before
printing it out. This is troublesome if the Unicode string contains
'wide' characters which can't be represented in Latin-1.

For example, if you create a Unicode string with three japanese Katakana
characters as in

perl -le 'print "\x{30DE}\x{30A4}\x{30AF}"'

(coincidentally pronounced Ma-i-ku, the japanese pronounciation of
"Mike"), STDOUT is in byte mode and the warning

Wide character in print at ./script.pl line 14.

appears. Setting STDOUT to UTF-8 mode as in

perl -le 'binmode(STDOUT, ":utf8"); print "\x{30DE}\x{30A4}\x{30AF}"'

will silently print the Unicode string to STDOUT in UTF-8. To see the
characters printed, you'll need a UTF-8 terminal with a font including
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 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 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 or C)
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/.log

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

The file appender that comes with Log4perl, L,
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 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 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
immediatly 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 utilty C
(http://www.courtesan.com/newsyslog) with Log4perl's file appender
in long-running processes.

For example, with a newsyslog configuration like

# newsyslog.conf
/tmp/test.log 666 12 5 * B

and a call to

# newsyslog -f /path/to/newsyslog.conf

C will take action if C is larger than the
specified 5K in size. It will move the current log file C to
C and create a new and empty C with
the specified permissions (this is why C needs to run as root).
An already existing C would be moved to
C, C to C, and so
forth, for every one of a max number of 12 archived logfiles that have
been configured in C.

Although a new file has been created, from Log4perl's appender's point
of view, this situation is identical to the one described in the
previous FAQ entry, labeled C.

To make sure that log messages are written to the new log file and not
to an archived one or end up in nowhere land,
the appender's C and C have to be
configured to deal with the 'disappearing' log file.

The situation gets interesting when C's option
to compress archived log files is enabled. This causes the
original log file not to be moved, but to disappear. If the
file appender isn't configured to recreate the logfile in this situation,
log messages will actually be lost without warning. This also
applies for the short time frame of C seconds
in between the recreator's file checks.

To make sure that no messages get lost, one option is to set the
interval to

log4perl.appender.Logfile.recreate_check_interval = 0

However, this is fairly expensive. A better approach is to define
a signal handler:

log4perl.appender.Logfile.recreate = 1
log4perl.appender.Logfile.recreate_check_signal = USR1
log4perl.appender.Logfile.recreate_pid_write = /tmp/myappid

As a service for C users, Log4perl's file appender writes
the current process ID to a PID file specified by the C
option. C then needs to be configured as in

# newsyslog.conf configuration for compressing archive files and
# sending a signal to the Log4perl-enabled application
/tmp/test.log 666 12 5 * B /tmp/myappid 30

to send the defined signal (30, which is USR1 on FreeBSD) to the
application process at rotation time. Note that the signal number
is different on Linux, where USR1 denotes as 10. Check C
for details.

=head2 How can a process under user id A log to a file under user id B?

This scenario often occurs in configurations where processes run under
various user IDs but need to write to a log file under a fixed, but
different user id.

With a traditional file appender, the log file will probably be created
under one user's id and appended to under a different user's id. With
a typical umask of 0002, the file will be created with -rw-rw-r--
permissions. If a user who's not in the first user's group
subsequently appends to the log file, it will fail because of a
permission problem.

Two potential solutions come to mind:

=over 4

=item *

Creating the file with a umask of 0000 will allow all users to append
to the log file. Log4perl's file appender C
has an C option that can be set to support this:

log4perl.appender.File = Log::Log4perl::Appender::File
log4perl.appender.File.umask = sub { 0000 };

This way, the log file will be created with -rw-rw-rw- permissions and
therefore has world write permissions. This might open up the logfile
for unwanted manipulations by arbitrary users, though.

=item *

Running the process under an effective user id of C will allow
it to write to the log file, no matter who started the process.
However, this is not a good idea, because of security concerns.

=back

Luckily, under Unix, there's the syslog daemon which runs as root and
takes log requests from user processes over a socket and writes them
to log files as configured in C.

By modifying C and HUPing the syslog daemon, you can
configure new log files:

# /etc/syslog.conf
...
user.* /some/path/file.log

Using the C appender, which comes with the
C distribution, you can then send messages via syslog:

use Log::Log4perl qw(:easy);

Log::Log4perl->init(\< $DEBUG,
category => '',
%options
};

$self->{logger} = get_logger($self->{category}),
bless $self, $class;
}

sub PRINT {
my($self, @rest) = @_;
$Log::Log4perl::caller_depth++;
$self->{logger}->log($self->{level}, @rest);
$Log::Log4perl::caller_depth--;
}

sub PRINTF {
my($self, $fmt, @rest) = @_;
$Log::Log4perl::caller_depth++;
$self->PRINT(sprintf($fmt, @rest));
$Log::Log4perl::caller_depth--;
}

1;

Now, if you have a function like

sub function_printing_to_fh {
my($fh) = @_;
printf $fh "Hi there!\n";
}

which takes a filehandle and prints something to it, it can be used
with Log4perl:

use Log::Log4perl qw(:easy);
usa FileHandleLogger;

Log::Log4perl->easy_init($DEBUG);

tie *SOMEHANDLE, 'FileHandleLogger' or
die "tie failed ($!)";

function_printing_to_fh(*SOMEHANDLE);
# prints "2007/03/22 21:43:30 Hi there!"

If you want, you can even specify a different log level or category:

tie *SOMEHANDLE, 'FileHandleLogger',
level => $INFO, category => "Foo::Bar" or die "tie failed ($!)";

=head2 I want multiline messages rendered line-by-line!

With the standard C, if you send a multiline message to
an appender as in

use Log::Log4perl qw(:easy);
Log

it gets rendered this way:

2007/04/04 23:23:39 multi
line
message

If you want each line to be rendered separately according to
the layout use C:

use Log::Log4perl qw(:easy);

Log::Log4perl->init(\<easy_init($DEBUG);

my $a = A->new();
$a->{selfref} = $a;

then you'll see the error message shown above during global destruction.
How to tackle this problem?

First, you should clean up your circular references before global
destruction. They will not only cause objects to be destroyed in an order
that's hard to predict, but also eat up memory until the program shuts
down.

So, the program above could easily be fixed by putting

$a->{selfref} = undef;

at the end or in an END handler. If that's hard to do, use weak references:

package main;
use Scalar::Util qw(weaken);
use Log::Log4perl qw(:easy);
Log::Log4perl->easy_init($DEBUG);

my $a = A->new();
$a->{selfref} = weaken $a;

This allows perl to clean up the circular reference when the object
goes out of scope, and doesn't wait until global destruction.

=cut

=head1 SEE ALSO

Log::Log4perl

=head1 AUTHOR

Mike Schilli, Elog4perl@perlmeister.comE

=cut}