Log::Log4perl::Filter - Log4perl Custom Filter Base Class
use Log::Log4perl;
Log::Log4perl->init(\ <<'EOT'); log4perl.logger = INFO, Screen log4perl.filter.MyFilter = sub { /let this through/ } log4perl.appender.Screen = Log::Log4perl::Appender::Screen log4perl.appender.Screen.Filter = MyFilter log4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout EOT
# Define a logger my $logger = Log::Log4perl->get_logger("Some");
# Let this through $logger->info("Here's the info, let this through!");
# Suppress this $logger->info("Here's the info, suppress this!");
################################################################# # StringMatch Filter: ################################################################# log4perl.filter.M1 = Log::Log4perl::Filter::StringMatch log4perl.filter.M1.StringToMatch = let this through log4perl.filter.M1.AcceptOnMatch = true
################################################################# # LevelMatch Filter: ################################################################# log4perl.filter.M1 = Log::Log4perl::Filter::LevelMatch log4perl.filter.M1.LevelToMatch = INFO log4perl.filter.M1.AcceptOnMatch = true
Log4perl allows the use of customized filters in its appenders to control the output of messages. These filters might grep for certain text chunks in a message, verify that its priority matches or exceeds a certain level or that this is the 10th time the same message has been submitted -- and come to a log/no log decision based upon these circumstantial facts.
Filters have names and can be specified in two different ways in the Log4perl
configuration file: As subroutines or as filter classes. Here's a
simple filter named MyFilter
which just verifies that the
oncoming message matches the regular expression /let this through/i
:
log4perl.filter.MyFilter = sub { /let this through/i }
It exploits the fact that when ok()
is called on a message,
Perl's special $_
variable will be set to the message text (prerendered,
i.e. concatenated but not layouted) to be logged.
The ok()
subroutine is expected to return a true value
if it wants the message to be logged or a false value if doesn't.
Also, Log::Log4perl will pass a hash to the ok()
method,
containing all key/value pairs that it would pass to the corresponding
appender, as specified in Log::Log4perl::Appender. Here's an
example of a filter checking the priority of the oncoming message:
log4perl.filter.MyFilter = sub { \ my %p = @_; \ $p{log4p_level} eq "WARN" or \ $p{log4p_level} eq "INFO" \ }
If the message priority equals WARN
or INFO
,
it returns a true value, causing
the message to be logged.
For common tasks like verifying that the message priority matches
a certain priority, there's already a
set of predefined filters available. To perform an exact level match, it's
much cleaner to use Log4perl's LevelMatch
filter instead:
log4perl.filter.M1 = Log::Log4perl::Filter::LevelMatch log4perl.filter.M1.LevelToMatch = INFO log4perl.filter.M1.AcceptOnMatch = true
This will let the message through if its priority is INFO and suppress it otherwise. The statement can be negated by saying
log4perl.filter.M1.AcceptOnMatch = false
instead. This way, the message will be logged if its priority is anything but INFO.
On a similar note, Log4perl's StringMatch
filter will check the
oncoming message for strings or regular expressions:
log4perl.filter.M1 = Log::Log4perl::Filter::StringMatch log4perl.filter.M1.StringToMatch = bl.. bl.. log4perl.filter.M1.AcceptOnMatch = true
This will open the gate for messages like blah blah
because the
regular expression in the StringToMatch
matches them. Again,
the setting of AcceptOnMatch
determines if the filter is defined
in a positive or negative way.
All class filter entries in the configuration file
have to adhere to the following rule:
Only after a filter has been defined by name and class/subroutine,
its attribute values can be
assigned, just like the true
value above gets assigned to the
AcceptOnMatch
attribute after the
filter M1
has been defined.
Attaching a filter to an appender is as easy as assigning its name to
the appender's Filter
attribute:
log4perl.appender.MyAppender.Filter = MyFilter
This will cause Log::Log4perl
to call the filter subroutine/method
every time a message is supposed to be passed to the appender. Depending
on the filter's return value, Log::Log4perl
will either continue as
planned or withdraw immediately.
Sometimes, it's useful to combine the output of various filters to arrive at a log/no log decision. While Log4j, Log4perl's mother ship, has chosen to implement this feature as a filter chain, similar to Linux' IP chains, Log4perl tries a different approach.
Typically, filter results will not need to be bumped along chains but combined in a programmatic manner using boolean logic. ``Log if this filter says 'yes' and that filter says 'no''' is a fairly common requirement, but hard to implement as a chain.
Log::Log4perl::Filter::Boolean
is a specially predefined custom filter
for Log4perl. It combines the results of other custom filters
in arbitrary ways, using boolean expressions:
log4perl.logger = WARN, AppWarn, AppError
log4perl.filter.Match1 = sub { /let this through/ } log4perl.filter.Match2 = sub { /and that, too/ } log4perl.filter.MyBoolean = Log::Log4perl::Filter::Boolean log4perl.filter.MyBoolean.logic = Match1 || Match2
log4perl.appender.Screen = Log::Log4perl::Appender::Screen log4perl.appender.Screen.Filter = MyBoolean log4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout
Log::Log4perl::Filter::Boolean
's boolean expressions allow for combining
different appenders by name using AND (&& or &), OR (|| or |) and NOT (!) as
logical expressions. Also, parentheses can be used for defining precedences.
Operator precedence follows standard Perl conventions. Here's a bunch of examples:
Match1 && !Match2 # Match1 and not Match2 !(Match1 || Match2) # Neither Match1 nor Match2 (Match1 && Match2) || Match3 # Both Match1 and Match2 or Match3
If none of Log::Log4perl's predefined filter classes fits your needs,
you can easily roll your own: Just define a new class,
derive it from the baseclass Log::Log4perl::Filter
,
and define its new
and ok
methods like this:
package Log::Log4perl::Filter::MyFilter;
use base Log::Log4perl::Filter;
sub new { my ($class, %options) = @_;
my $self = { %options, }; bless $self, $class;
return $self; }
sub ok { my ($self, %p) = @_;
# ... decide and return 1 or 0 }
1;
Values you've defined for its attributes in Log4perl's configuration file,
will be received through its new
method:
log4perl.filter.MyFilter = Log::Log4perl::Filter::MyFilter log4perl.filter.MyFilter.color = red
will cause Log::Log4perl::Filter::MyFilter
's constructor to be called
like this:
Log::Log4perl::Filter::MyFilter->new( name => "MyFilter", color => "red" );
The custom filter class should use this to set the object's attributes, to have them available later to base log/nolog decisions on it.
ok()
is the filter's method to tell if it agrees or disagrees with logging
the message. It will be called by Log::Log4perl whenever it needs the
filter to decide. A false value returned by ok()
will block messages,
a true value will let them through.
See the Log::Log4perl::FAQ manpage for this.
eg::L4pResurrectable, Log::Log4perl, Log::Log4perl::NDC, Log::Log4perl::Config, Log::Log4perl::Appender, Log::Log4perl::Util, Log::Log4perl::Level, Log::Log4perl::Filter, Log::Log4perl::Logger, Log::Log4perl::Layout, Log::Log4perl::JavaMap, Log::Log4perl::FAQ, Log::Log4perl::MDC, Log::Log4perl::Resurrector, Log::Log4perl::DateFormat, Log::Log4perl::Filter::Boolean, Log::Log4perl::Filter::LevelRange, Log::Log4perl::Filter::LevelMatch, Log::Log4perl::Filter::StringMatch, Log::Log4perl::Config::Watch, Log::Log4perl::Config::PropertyConfigurator, Log::Log4perl::Config::DOMConfigurator, Log::Log4perl::Config::BaseConfigurator, Log::Log4perl::JavaMap::FileAppender, Log::Log4perl::JavaMap::RollingFileAppender, Log::Log4perl::JavaMap::NTEventLogAppender, Log::Log4perl::JavaMap::TestBuffer, Log::Log4perl::JavaMap::JDBCAppender, Log::Log4perl::JavaMap::ConsoleAppender, Log::Log4perl::JavaMap::SyslogAppender, Log::Log4perl::Util::Semaphore, Log::Log4perl::Appender::Synchronized, Log::Log4perl::Appender::RRDs, Log::Log4perl::Appender::Screen, Log::Log4perl::Appender::DBI, Log::Log4perl::Appender::TestBuffer, Log::Log4perl::Appender::ScreenColoredLevels, Log::Log4perl::Appender::Socket, Log::Log4perl::Appender::Buffer, Log::Log4perl::Appender::Limit, Log::Log4perl::Appender::File, Log::Log4perl::Appender::TestFileCreeper, Log::Log4perl::Appender::TestArrayBuffer, Log::Log4perl::Appender::String, Log::Log4perl::Layout::PatternLayout, Log::Log4perl::Layout::SimpleLayout, Log::Log4perl::Layout::NoopLayout, Log::Log4perl::Layout::PatternLayout::Multiline
Source Code: Log::Log4perl::Filter
Mike Schilli, <log4perl@perlmeister.com>, 2003