Predefined Filters

  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

    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.

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

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

Writing your own filter classes

    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 filter should let the message pass or not. A true return value indicates the 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 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.

A Practical Example: Level Matching