SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from RedHat EL 8 perl-Log-Log4perl-1.50-1.el8.noarch.rpm

Filter

Section: User Contributed Perl Documentation (3)
Updated: 2020-07-22
Index 

NAME

Log::Log4perl::Filter - Log4perl Custom Filter Base Class 

SYNOPSIS

  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
 

DESCRIPTION

Log4perl allows the use of customized filters in its appendersto control the output of messages. These filters might grep forcertain text chunks in a message, verify that its prioritymatches or exceeds a certain level or that this is the 10thtime 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 Log4perlconfiguration 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 the subroutine definedabove 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 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 subroutine,containing all key/value pairs that it would pass to the corresponding appender, as specified in Log::Log4perl::Appender. Here's anexample of a filter checking the priority of the oncoming message:

  log4perl.filter.MyFilter        = sub {    \       my %p = @_;                           \       if($p{log4p_level} eq "WARN" or       \          $p{log4p_level} eq "INFO") {       \           return 1;                         \       }                                     \       return 0;                             \  }

If the message priority equals "WARN" or "INFO", it returns a true value, causingthe message to be logged. 

Predefined Filters

For common tasks like verifying that the message priority matchesa certain priority, there's already a set of predefined filters available. To perform an exact level match, it'smuch 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 suppressit otherwise. The statement can be negated by saying

  log4perl.filter.M1.AcceptOnMatch = false

instead. This way, the message will be logged if its priority isanything 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 definedin a positive or negative way.

All class filter entries in the configuration filehave to adhere to the following rule:Only after a filter has been defined by name and class/subroutine,its attribute values can beassigned, just like the "true" value above gets assigned to the"AcceptOnMatch" attribute after thefilter "M1" has been defined. 

Attaching a filter to an appender

Attaching a filter to an appender is as easy as assigning its name tothe appender's "Filter" attribute:

    log4perl.appender.MyAppender.Filter = MyFilter

This will cause "Log::Log4perl" to call the filter subroutine/methodevery time a message is supposed to be passed to the appender. Dependingon the filter's return value, "Log::Log4perl" will either continue asplanned or withdraw immediately. 

Combining filters with Log::Log4perl::Filter::Boolean

Sometimes, it's useful to combine the output of various filters toarrive 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 ifthis 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 filterfor 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 combiningdifferent appenders by name using AND (&& or &), OR (|| or |) and NOT (!) aslogical 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
 

Writing your own filter classes

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;

Log4perl will call the ok() method to determine if the filtershould let the message pass or not. A true return value indicatesthe message will be logged by the appender, a false value blocks it.

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 calledlike 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 loggingthe message. It will be called by Log::Log4perl whenever it needs thefilter to decide. A false value returned by "ok()" will block messages,a true value will let them through. 

A Practical Example: Level Matching

See Log::Log4perl::FAQ for this. 

SEE ALSO

Log::Log4perl::Filter::LevelMatch,Log::Log4perl::Filter::LevelRange,Log::Log4perl::Filter::StringRange,Log::Log4perl::Filter::Boolean 

LICENSE

Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess <cpanAATTgoess.org>.

This library is free software; you can redistribute it and/or modifyit under the same terms as Perl itself. 

AUTHOR

Please contribute patches to the project on Github:

    http://github.com/mschilli/log4perl

Send bug reports or requests for enhancements to the authors via our

MAILING LIST (questions, bug reports, suggestions/patches): log4perl-develAATTlists.sourceforge.net

Authors (please contact them via the list above, not directly):Mike Schilli <m@perlmeister.com>,Kevin Goess <cpanAATTgoess.org>

Contributors (in alphabetical order):Ateeq Altaf, Cory Bennett, Jens Berthold, Jeremy Bopp, HuttonDavidson, Chris R. Donnelly, Matisse Enzer, Hugh Esco, AnthonyFoiani, James FitzGibbon, Carl Franks, Dennis Gregorovic, AndyGrundman, Paul Harrington, Alexander Hartmaier David Hull, Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter, Brett Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope, Lars Thegler, David Viner, Mac Yang.


 

Index

NAME
SYNOPSIS
DESCRIPTION
Predefined Filters
Attaching a filter to an appender
Combining filters with Log::Log4perl::Filter::Boolean
Writing your own filter classes
A Practical Example: Level Matching
SEE ALSO
LICENSE
AUTHOR

This document was created byman2html,using the manual pages.