Filters

Filtering is a mechanism which allows the user to configure more precisely which logging events will be logged by an appender, and which will be ignored.

Multiple filters can be defined on any appender; they will form a filter chain. When a logging event is passed onto an appender, the event will first pass through the filter chain. Each filter in the chain will examine the logging event and make a decision to either:

ACCEPT the logging event - The event will be logged without consulting the remaining filters in the chain.
DENY the logging event - The event will be not logged without consulting the remaining filters in the chain.
Remain NEUTRAL - No decision is made, therefore the next filter in the chain is consulted. If there are no remaining filters in the chain, the event is logged.

Configuring filters

Filters are configurable in the XML and PHP configuration format. They cannot be configured using the properties configuration format.

Like appenders and layouts, depending on the class used, filters may have configurable parameters which determine their behaviour.

Here is a configuration example:

<configuration xmlns="http://logging.apache.org/log4php/">
    <appender name="defualt" class="LoggerAppenderEcho">
        <layout class="LoggerLayoutSimple"/>
        <filter class="LoggerFilterStringMatch">
            <param name="stringToMatch" value="interesting" />
            <param name="acceptOnMatch" value="true" />
        </filter>
        <filter class="LoggerFilterLevelRange">
            <param name="levelMin" value="debug" />
            <param name="levelMax" value="error" />
        </filter>
    </appender>
    <root>
        <level value="TRACE" />
        <appender_ref ref="defualt" />
    </root>
</configuration>

array(
    'appenders' => array(
        'default' => array(
            'class' => 'LoggerAppenderEcho'
            'layout' => array(
                'class' => 'LoggerLayoutSimple'
            ),
            'filters' => array(
                array(
                    'class' => 'LoggerFilterStringMatch',
                    'params' => array(
                        'stringToMatch' => 'interesting',
                        'acceptOnMatch' => true,
                    )
                ),
                array(
                    'class' => 'LoggerFilterLevelRange',
                    'params' => array(
                        'levelMin' => 'debug',
                        'levelMax' => 'error',
                    )
                )
            )
        )
    ),
    'rootLogger' => array(
    	'appenders' => array('default'),
    )
)

In this example, there are two filters defined for the default appender.

The first filter LoggerFilterStringMatch searches for the string "interesting" in the logging event's message. If the string is found, the filter will ACCEPT the logging event, and the event will be logged. If the string is not found, the filter will remain NEUTRAL, and the event will be passed on to the next filter.

The second filter LoggerFilterLevelRange ACCEPTS all events which have a level between DEBUG and ERROR (in other words, levels DEBUG, INFO, WARN and ERROR). It DENIES all other events.

Therefore, this filter configuration will log events which which have a level between DEBUG and ERROR, except of theose which have the string "interesting" in the message. Those will be logged regardless of their level.

Filter reference

The following filters are available in log4php:

Name	Destination
LoggerFilterDenyAll	Denies all logging events.
LoggerFilterLevelMatch	Filters based on logging event level.
LoggerFilterLevelRange	Filters based on logging event level range.
LoggerFilterStringMatch	Filters by searching for a string in the logging event message.

LoggerFilterDenyAll

This filters simply denies all logging events. It has no configurable parameters.

LoggerFilterLevelMatch

This filter either accepts the specified logger level or denies it.

Configurable parameters

Parameter	Type	Required	Default	Description
levelToMatch	LoggerLevel	Yes	-	The level to match
acceptOnMatch	boolean	No	true	If true, the matching log level is accepted, denied otherwise.

Example

The following filter configuration will deny all logging events with level DEBUG. It will remain neutral for others.

<filter class="LoggerFilterLevelMatch">
    <param name="levelToMatch" value="debug" />
    <param name="acceptOnMatch" value="false" />
</filter>

LoggerFilterLevelRange

This filter accepts or denies logging events if their log level is within the specified range.

Configurable parameters

Parameter	Type	Required	Default	Description
levelMin	LoggerLevel	Yes	-	The minimum level to log. If set, levels lower than this will be denied.
levelMax	LoggerLevel	Yes	-	The maximum level to log. If set, levels higher than this will be denied.
acceptOnMatch	boolean	No	true	If true, the matching log level is accepted, denied otherwise.

Example

The following filter configuration denies levels greater than WARN.

<filter class="LoggerFilterLevelRange">
    <param name="levelMax" value="warn" />
    <param name="acceptOnMatch" value="false" />
</filter>

LoggerFilterStringMatch

This filter allows or denies logging events if their message contains a given string.

Configurable parameters

Parameter	Type	Required	Default	Description
stringToMatch	LoggerLevel	Yes	-	The level to match
levelMax	LoggerLevel	Yes	-	The level to match
acceptOnMatch	boolean	No	true	If true, the matching log level is accepted, denied otherwise.

Example

The following filter configuration denies events which contain the string "not-interesting" in their message.

<filter class="LoggerFilterStringMatch">
    <param name="StringToMatch" value="not-interesting" />
    <param name="AcceptOnMatch" value="false" />
</filter>