Google Git
Sign in
apache / logging-log4j-site / d0d0de55986756593c08e5d2b8059541eacaf428 / . / log4j-2.0-rc1 / manual / filters.html
blob: dedabd4c47e8107a02d541499a374a12bbc29798 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- Generated by Apache Maven Doxia at Feb 9, 2014 -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>
Log4j Filters - Apache Log4j 2</title>
<link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="../css/site.css" type="text/css" />
<script type="text/javascript" src="../js/jquery.min.js"></script>
<script type="text/javascript" src="../js/bootstrap.min.js"></script>
<script type="text/javascript" src="../js/prettify.min.js"></script>
<script type="text/javascript" src="../js/site.js"></script>
<meta name="author" content="Ralph Goers" />
<meta name="Date-Revision-yyyymmdd" content="20140209" />
<meta http-equiv="Content-Language" content="en" />
</head>
<body class="composite">
<img class="logo-left" src="../images/ls-logo.jpg" alt="Apache logging services logo" />
<img class="logo-right" src="../images/logo.jpg" alt="Apache log4j logo" />
<div class="clear"></div>
<div class="navbar">
<div class="navbar-inner">
<div class="container-fluid">
<a class="brand" href="http://logging.apache.org/log4j/2.x/">Apache Log4j 2 &trade;</a>
<ul class="nav">
<li>
<a href="http://wiki.apache.org/logging" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a>
</li>
<li>
<a href="http://www.apache.org/" class="external" target="_blank" title="Apache">Apache</a>
</li>
<li>
<a href="../../../" title="Logging Services">Logging Services</a>
</li>
<li>
<a href="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="external" target="_blank" title="Sonar">Sonar</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container-fluid">
<table class="layout-table">
<tr>
<td class="sidebar">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-home"></i>Apache Log4j™ 2</li>
<li class="none">
<a href="../index.html" title="About">About</a>
</li>
<li class="none">
<a href="../download.html" title="Download">Download</a>
</li>
<li class="none">
<a href="../maven-artifacts.html" title="Maven and Ivy">Maven and Ivy</a>
</li>
<li class="none">
<a href="../build.html" title="Build">Build</a>
</li>
<li class="none">
<a href="../changelog.html" title="Changelog">Changelog</a>
</li>
<li class="collapsed">
<a href="../javadoc.html" title="Javadoc">Javadoc</a>
</li>
<li class="none">
<a href="../faq.html" title="FAQ">FAQ</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-book"></i>Manual</li>
<li class="none">
<a href="../manual/index.html" title="Introduction">Introduction</a>
</li>
<li class="none">
<a href="../manual/architecture.html" title="Architecture">Architecture</a>
</li>
<li class="none">
<a href="../manual/migration.html" title="Log4j 1.x Migration">Log4j 1.x Migration</a>
</li>
<li class="collapsed">
<a href="../manual/api.html" title="API">API</a>
</li>
<li class="collapsed">
<a href="../manual/configuration.html" title="Configuration">Configuration</a>
</li>
<li class="collapsed">
<a href="../manual/webapp.html" title="Web Applications and JSPs">Web Applications and JSPs</a>
</li>
<li class="collapsed">
<a href="../manual/plugins.html" title="Plugins">Plugins</a>
</li>
<li class="collapsed">
<a href="../manual/lookups.html" title="Lookups">Lookups</a>
</li>
<li class="collapsed">
<a href="../manual/appenders.html" title="Appenders">Appenders</a>
</li>
<li class="collapsed">
<a href="../manual/layouts.html" title="Layouts">Layouts</a>
</li>
<li class="expanded active">
<a href="../manual/filters.html" title="Filters">Filters</a>
<ul>
<li class="none">
<a href="../manual/filters.html#BurstFilter" title="Burst">Burst</a>
</li>
<li class="none">
<a href="../manual/filters.html#CompositeFilter" title="CompositeFilter">CompositeFilter</a>
</li>
<li class="none">
<a href="../manual/filters.html#DynamicThresholdFilter" title="DynamicThreshold">DynamicThreshold</a>
</li>
<li class="none">
<a href="../manual/filters.html#MapFilter" title="Map">Map</a>
</li>
<li class="none">
<a href="../manual/filters.html#MarkerFilter" title="Marker">Marker</a>
</li>
<li class="none">
<a href="../manual/filters.html#RegexFilter" title="Regex">Regex</a>
</li>
<li class="none">
<a href="../manual/filters.html#StructuredDataFilter" title="StructuredData">StructuredData</a>
</li>
<li class="none">
<a href="../manual/filters.html#ThreadContextMapFilter" title="ThreadContextMap">ThreadContextMap</a>
</li>
<li class="none">
<a href="../manual/filters.html#ThresholdFilter" title="Threshold">Threshold</a>
</li>
<li class="none">
<a href="../manual/filters.html#TimeFilter" title="Time">Time</a>
</li>
</ul>
</li>
<li class="collapsed">
<a href="../manual/async.html" title="Async Loggers">Async Loggers</a>
</li>
<li class="none">
<a href="../manual/jmx.html" title="JMX">JMX</a>
</li>
<li class="none">
<a href="../manual/logsep.html" title="Logging Separation">Logging Separation</a>
</li>
<li class="collapsed">
<a href="../manual/extending.html" title="Extending Log4j">Extending Log4j</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Components</li>
<li class="none">
<a href="../log4j-api/index.html" title="API">API</a>
</li>
<li class="none">
<a href="../log4j-core/index.html" title="Implementation">Implementation</a>
</li>
<li class="none">
<a href="../log4j-jcl/index.html" title="Commons Logging Bridge">Commons Logging Bridge</a>
</li>
<li class="none">
<a href="../log4j-1.2-api/index.html" title="Log4j 1.2 API">Log4j 1.2 API</a>
</li>
<li class="none">
<a href="../log4j-slf4j-impl/index.html" title="SLF4J Binding">SLF4J Binding</a>
</li>
<li class="none">
<a href="../log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter">Log4j 2 to SLF4J Adapter</a>
</li>
<li class="none">
<a href="../log4j-flume-ng/index.html" title="Apache Flume NG Appender">Apache Flume NG Appender</a>
</li>
<li class="none">
<a href="../log4j-taglib/index.html" title="Log4j Tag Library">Log4j Tag Library</a>
</li>
<li class="none">
<a href="../log4j-jmx-gui/index.html" title="Log4j JMX GUI">Log4j JMX GUI</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-info-sign"></i>Project Information</li>
<li class="none">
<a href="../dependencies.html" title="Dependencies">Dependencies</a>
</li>
<li class="none">
<a href="../dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
</li>
<li class="none">
<a href="../dependency-management.html" title="Dependency Management">Dependency Management</a>
</li>
<li class="none">
<a href="../team-list.html" title="Project Team">Project Team</a>
</li>
<li class="none">
<a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a>
</li>
<li class="none">
<a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
</li>
<li class="none">
<a href="../license.html" title="Project License">Project License</a>
</li>
<li class="none">
<a href="../source-repository.html" title="Source Repository">Source Repository</a>
</li>
<li class="none">
<a href="../project-summary.html" title="Project Summary">Project Summary</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Project Reports</li>
<li class="none">
<a href="../changes-report.html" title="Changes Report">Changes Report</a>
</li>
<li class="none">
<a href="../jira-report.html" title="JIRA Report">JIRA Report</a>
</li>
<li class="none">
<a href="../surefire-report.html" title="Surefire Report">Surefire Report</a>
</li>
<li class="none">
<a href="../rat-report.html" title="RAT Report">RAT Report</a>
</li>
</ul>
</div>
<div id="poweredBy">
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
<img class="poweredBy" alt="Built by Maven" src="../images/maven-feather.png" />
</a>
</div>
</td>
<td class="content">
<!-- Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. -->
<div class="section"><h2>Filters<a name="Filters"></a></h2>
<p>
Filters allow Log Events to be evaluated to determine if or how they should be published. A Filter
will be called on one if its filter methods and will return a Result, which is an Enum that has
one of 3 values - ACCEPT, DENY or NEUTRAL.
</p>
<p>
Filters may be configured in one of four locations;
</p><ol style="list-style-type: decimal">
<li>Context-wide Filters are configured directly in the configuration. Events that are
rejected by these filters will not be passed to loggers for further processing. Once an
event has been accepted by a Context-wide filter it will not be evaluated by any other
Context-wide Filters nor will the Logger's Level be used to filter the event. The event
will be evaluated by Logger and Appender Filters however.</li>
<li>Logger Filters are configured on a specified Logger. These are evaluated after the
Context-wide Filters and the Log Level for the Logger. Events that are rejected by these
filters will be discarded and the event will not be passed to a parent Logger regardless
of the additivity setting.</li>
<li>Appender Filters are used to determine if a specific Appender should handle the
formatting and publication of the event.</li>
<li>Appender Reference Filters are used to determine if a Logger should route the event to
an appender.</li>
</ol>
<a name="BurstFilter"></a>
<div class="section"><h3>BurstFilter<a name="BurstFilter"></a></h3>
<p>
The BurstFilter provides a mechanism to control the rate at which LogEvents are processed by
silently discarding events after the maximum limit has been reached.
</p>
<table border="0" class="bodyTable"><caption align="top">Burst Filter Parameters</caption>
<tr class="a">
<th>Parameter Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr class="b">
<td>level</td>
<td>String</td>
<td>Level of messages to be filtered. Anything at or below this level will be
filtered out if <tt>maxBurst</tt> has been exceeded. The default is
WARN meaning any messages that are higher than warn will be logged
regardless of the size of a burst.
</td>
</tr>
<tr class="a">
<td>rate</td>
<td>float</td>
<td>The average number of events per second to allow.</td>
</tr>
<tr class="b">
<td>maxBurst</td>
<td>integer</td>
<td>The maximum number of events that can occur before events are filtered for exceeding the
average rate. The default is 10 times the rate.</td>
</tr>
<tr class="a">
<td>onMatch</td>
<td>String</td>
<td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td>
</tr>
<tr class="b">
<td>onMismatch</td>
<td>String</td>
<td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is
DENY.</td>
</tr>
</table>
<p>
A configuration containing the BurstFilter might look like:
</p><div class="prettyprint linenums"><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;warn&quot; name=&quot;MyApp&quot; packages=&quot;&quot;&gt;
&lt;Appenders&gt;
&lt;RollingFile name=&quot;RollingFile&quot; fileName=&quot;logs/app.log&quot;
filePattern=&quot;logs/app-%d{MM-dd-yyyy}.log.gz&quot;&gt;
&lt;BurstFilter level=&quot;INFO&quot; rate=&quot;16&quot; maxBurst=&quot;100&quot;/&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;TimeBasedTriggeringPolicy /&gt;
&lt;/RollingFile&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Root level=&quot;error&quot;&gt;
&lt;AppenderRef ref=&quot;RollingFile&quot;/&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;</pre></div>
</div>
<a name="CompositeFilter"></a>
<div class="section"><h3>CompositeFilter<a name="CompositeFilter"></a></h3>
<p>
The CompositeFilter provides a way to specify more than one filter. It is added to the
configuration as a filters element and contains other filters to be evaluated. The filters
element accepts no parameters.
</p>
<p>
A configuration containing the CompositeFilter might look like:
</p><div class="prettyprint linenums"><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;warn&quot; name=&quot;MyApp&quot; packages=&quot;&quot;&gt;
&lt;Filters&gt;
&lt;Marker marker=&quot;EVENT&quot; onMatch=&quot;ACCEPT&quot; onMismatch=&quot;NEUTRAL&quot;/&gt;
&lt;DynamicThresholdFilter key=&quot;loginId&quot; defaultThreshold=&quot;ERROR&quot;
onMatch=&quot;ACCEPT&quot; onMismatch=&quot;NEUTRAL&quot;&gt;
&lt;KeyValuePair key=&quot;User1&quot; value=&quot;DEBUG&quot;/&gt;
&lt;/DynamicThresholdFilter&gt;
&lt;/Filters&gt;
&lt;Appenders&gt;
&lt;File name=&quot;Audit&quot; fileName=&quot;logs/audit.log&quot;&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;/File&gt;
&lt;RollingFile name=&quot;RollingFile&quot; fileName=&quot;logs/app.log&quot;
filePattern=&quot;logs/app-%d{MM-dd-yyyy}.log.gz&quot;&gt;
&lt;BurstFilter level=&quot;INFO&quot; rate=&quot;16&quot; maxBurst=&quot;100&quot;/&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;TimeBasedTriggeringPolicy /&gt;
&lt;/RollingFile&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Logger name=&quot;EventLogger&quot; level=&quot;info&quot;&gt;
&lt;AppenderRef ref=&quot;Audit&quot;/&gt;
&lt;/Logger&gt;
&lt;Root level=&quot;error&quot;&gt;
&lt;AppenderRef ref=&quot;RollingFile&quot;/&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;</pre></div>
</div>
<a name="DynamicThresholdFilter"></a>
<div class="section"><h3>DynamicThresholdFilter<a name="DynamicThresholdFilter"></a></h3>
<p>
The DynamicThresholdFilter allows filtering by log level based on specific attributes. For example,
if the user's loginId is being captured in the ThreadContext Map then it is possible to enable
debug logging for only that user.
</p>
<table border="0" class="bodyTable"><caption align="top">Dynamic Threshold Filter Parameters</caption>
<tr class="a">
<th>Parameter Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr class="b">
<td>defaultThreshold</td>
<td>String</td>
<td>Level of messages to be filtered. If there is no matching key in the key/value pairs
then this level will be compared against the event's level.
</td>
</tr>
<tr class="a">
<td>keyValuePair</td>
<td>KeyValuePair[]</td>
<td>One or more KeyValuePair elements that define the matching value for the key and the Level
to evaluate when the key matches.</td>
</tr>
<tr class="b">
<td>onMatch</td>
<td>String</td>
<td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td>
</tr>
<tr class="a">
<td>onMismatch</td>
<td>String</td>
<td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is
DENY.</td>
</tr>
</table>
<p>
Here is a sample configuration containing the DynamicThresholdFilter:
</p><div class="prettyprint linenums"><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;warn&quot; name=&quot;MyApp&quot; packages=&quot;&quot;&gt;
&lt;DynamicThresholdFilter key=&quot;loginId&quot; defaultThreshold=&quot;ERROR&quot;
onMatch=&quot;ACCEPT&quot; onMismatch=&quot;NEUTRAL&quot;&gt;
&lt;KeyValuePair key=&quot;User1&quot; value=&quot;DEBUG&quot;/&gt;
&lt;/DynamicThresholdFilter&gt;
&lt;Appenders&gt;
&lt;RollingFile name=&quot;RollingFile&quot; fileName=&quot;logs/app.log&quot;
filePattern=&quot;logs/app-%d{MM-dd-yyyy}.log.gz&quot;&gt;
&lt;BurstFilter level=&quot;INFO&quot; rate=&quot;16&quot; maxBurst=&quot;100&quot;/&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;TimeBasedTriggeringPolicy /&gt;
&lt;/RollingFile&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Root level=&quot;error&quot;&gt;
&lt;AppenderRef ref=&quot;RollingFile&quot;/&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;</pre></div>
</div>
<a name="MapFilter"></a>
<div class="section"><h3>MapFilter<a name="MapFilter"></a></h3>
<p>
The MapFilter allows filtering against data elements that are in a MapMessage.
</p>
<table border="0" class="bodyTable"><caption align="top">Map Filter Parameters</caption>
<tr class="a">
<th>Parameter Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr class="b">
<td>keyValuePair</td>
<td>KeyValuePair[]</td>
<td>One or more KeyValuePair elements that define the key in the map and the value to match on. If the
same key is specified more than once then the check for that key will automatically be an &quot;or&quot; since
a Map can only contain a single value.</td>
</tr>
<tr class="a">
<td>operator</td>
<td>String</td>
<td>If the operator is &quot;or&quot; then a match by any one of the key/value pairs will be considered to be
a match, otherwise all the key/value pairs must match.</td>
</tr>
<tr class="b">
<td>onMatch</td>
<td>String</td>
<td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td>
</tr>
<tr class="a">
<td>onMismatch</td>
<td>String</td>
<td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is
DENY.</td>
</tr>
</table>
<p>
As in this configuration, the MapFilter can be used to log particular events:
</p><div class="prettyprint linenums"><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;warn&quot; name=&quot;MyApp&quot; packages=&quot;&quot;&gt;
&lt;MapFilter onMatch=&quot;ACCEPT&quot; onMismatch=&quot;NEUTRAL&quot; operator=&quot;or&quot;&gt;
&lt;KeyValuePair key=&quot;eventId&quot; value=&quot;Login&quot;/&gt;
&lt;KeyValuePair key=&quot;eventId&quot; value=&quot;Logout&quot;/&gt;
&lt;/MapFilter&gt;
&lt;Appenders&gt;
&lt;RollingFile name=&quot;RollingFile&quot; fileName=&quot;logs/app.log&quot;
filePattern=&quot;logs/app-%d{MM-dd-yyyy}.log.gz&quot;&gt;
&lt;BurstFilter level=&quot;INFO&quot; rate=&quot;16&quot; maxBurst=&quot;100&quot;/&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;TimeBasedTriggeringPolicy /&gt;
&lt;/RollingFile&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Root level=&quot;error&quot;&gt;
&lt;AppenderRef ref=&quot;RollingFile&quot;/&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;</pre></div>
<p>
This sample configuration will exhibit the same behavior as the preceding example since the only
logger configured is the root.
</p><div class="prettyprint linenums"><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;warn&quot; name=&quot;MyApp&quot; packages=&quot;&quot;&gt;
&lt;Appenders&gt;
&lt;RollingFile name=&quot;RollingFile&quot; fileName=&quot;logs/app.log&quot;
filePattern=&quot;logs/app-%d{MM-dd-yyyy}.log.gz&quot;&gt;
&lt;BurstFilter level=&quot;INFO&quot; rate=&quot;16&quot; maxBurst=&quot;100&quot;/&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;TimeBasedTriggeringPolicy /&gt;
&lt;/RollingFile&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Root level=&quot;error&quot;&gt;
&lt;MapFilter onMatch=&quot;ACCEPT&quot; onMismatch=&quot;NEUTRAL&quot; operator=&quot;or&quot;&gt;
&lt;KeyValuePair key=&quot;eventId&quot; value=&quot;Login&quot;/&gt;
&lt;KeyValuePair key=&quot;eventId&quot; value=&quot;Logout&quot;/&gt;
&lt;/MapFilter&gt;
&lt;AppenderRef ref=&quot;RollingFile&quot;&gt;
&lt;/AppenderRef&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;</pre></div>
<p>
This third sample configuration will exhibit the same behavior as the preceding examples since the only
logger configured is the root and the root is only configured with a single appender reference.
</p><div class="prettyprint linenums"><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;warn&quot; name=&quot;MyApp&quot; packages=&quot;&quot;&gt;
&lt;Appenders&gt;
&lt;RollingFile name=&quot;RollingFile&quot; fileName=&quot;logs/app.log&quot;
filePattern=&quot;logs/app-%d{MM-dd-yyyy}.log.gz&quot;&gt;
&lt;BurstFilter level=&quot;INFO&quot; rate=&quot;16&quot; maxBurst=&quot;100&quot;/&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;TimeBasedTriggeringPolicy /&gt;
&lt;/RollingFile&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Root level=&quot;error&quot;&gt;
&lt;AppenderRef ref=&quot;RollingFile&quot;&gt;
&lt;MapFilter onMatch=&quot;ACCEPT&quot; onMismatch=&quot;NEUTRAL&quot; operator=&quot;or&quot;&gt;
&lt;KeyValuePair key=&quot;eventId&quot; value=&quot;Login&quot;/&gt;
&lt;KeyValuePair key=&quot;eventId&quot; value=&quot;Logout&quot;/&gt;
&lt;/MapFilter&gt;
&lt;/AppenderRef&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;</pre></div>
</div>
<a name="MarkerFilter"></a>
<div class="section"><h3>MarkerFilter<a name="MarkerFilter"></a></h3>
<p>
The MarkerFilter compares the configured Marker value against the Marker that is included
in the LogEvent. A match occurs when the Marker name matches either the Log Event's Marker
or one of its parents.
</p>
<table border="0" class="bodyTable"><caption align="top">Marker Filter Parameters</caption>
<tr class="a">
<th>Parameter Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr class="b">
<td>marker</td>
<td>String</td>
<td>
The name of the Marker to compare.
</td>
</tr>
<tr class="a">
<td>onMatch</td>
<td>String</td>
<td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td>
</tr>
<tr class="b">
<td>onMismatch</td>
<td>String</td>
<td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is
DENY.</td>
</tr>
</table>
<p>
A sample configuration that only allows the event to be written by the appender if the Marker matches:
</p><div class="prettyprint linenums"><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;warn&quot; name=&quot;MyApp&quot; packages=&quot;&quot;&gt;
&lt;Appenders&gt;
&lt;RollingFile name=&quot;RollingFile&quot; fileName=&quot;logs/app.log&quot;
filePattern=&quot;logs/app-%d{MM-dd-yyyy}.log.gz&quot;&gt;
&lt;MarkerFilter marker=&quot;FLOW&quot; onMatch=&quot;ACCEPT&quot; onMismatch=&quot;DENY&quot;/&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;TimeBasedTriggeringPolicy /&gt;
&lt;/RollingFile&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Root level=&quot;error&quot;&gt;
&lt;AppenderRef ref=&quot;RollingFile&quot;/&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;</pre></div>
</div>
<a name="RegexFilter"></a>
<div class="section"><h3>RegexFilter<a name="RegexFilter"></a></h3>
<p>
The RegexFilter allows the formatted or unformatted message to be compared against a regular expression.
</p>
<table border="0" class="bodyTable"><caption align="top">Regex Filter Parameters</caption>
<tr class="a">
<th>Parameter Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr class="b">
<td>regex</td>
<td>String</td>
<td>
The regular expression.
</td>
</tr>
<tr class="a">
<td>useRawMsg</td>
<td>boolean</td>
<td>If true the unformatted message will be used, otherwise the formatted message will be used. The
default value is false.</td>
</tr>
<tr class="b">
<td>onMatch</td>
<td>String</td>
<td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td>
</tr>
<tr class="a">
<td>onMismatch</td>
<td>String</td>
<td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is
DENY.</td>
</tr>
</table>
<p>
A sample configuration that only allows the event to be written by the appender if it contains the word &quot;test&quot;:
</p><div class="prettyprint linenums"><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;warn&quot; name=&quot;MyApp&quot; packages=&quot;&quot;&gt;
&lt;Appenders&gt;
&lt;RollingFile name=&quot;RollingFile&quot; fileName=&quot;logs/app.log&quot;
filePattern=&quot;logs/app-%d{MM-dd-yyyy}.log.gz&quot;&gt;
&lt;RegexFilter regex=&quot;.* test .*&quot; onMatch=&quot;ACCEPT&quot; onMismatch=&quot;DENY&quot;/&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;TimeBasedTriggeringPolicy /&gt;
&lt;/RollingFile&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Root level=&quot;error&quot;&gt;
&lt;AppenderRef ref=&quot;RollingFile&quot;/&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;</pre></div>
</div>
<a name="StructuredDataFilter"></a>
<div class="section"><h3>StructuredDataFilter<a name="StructuredDataFilter"></a></h3>
<p>
The StructuredDataFilter is a MapFilter that also allows filtering on the event id, type and message.
</p>
<table border="0" class="bodyTable"><caption align="top">StructuredData Filter Parameters</caption>
<tr class="a">
<th>Parameter Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr class="b">
<td>keyValuePair</td>
<td>KeyValuePair[]</td>
<td>One or more KeyValuePair elements that define the key in the map and the value to match on. &quot;id&quot;,
&quot;id.name&quot;, &quot;type&quot;, and &quot;message&quot; should be used to match on the StructuredDataId, the name
portion of the StructuredDataId, the type, and the formatted message respectively. If the
same key is specified more than once then the check for that key will automatically be an &quot;or&quot; since
a Map can only contain a single value.
</td>
</tr>
<tr class="a">
<td>operator</td>
<td>String</td>
<td>If the operator is &quot;or&quot; then a match by any one of the key/value pairs will be considered to be
a match, otherwise all the key/value pairs must match.</td>
</tr>
<tr class="b">
<td>onMatch</td>
<td>String</td>
<td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td>
</tr>
<tr class="a">
<td>onMismatch</td>
<td>String</td>
<td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is
DENY.</td>
</tr>
</table>
<p>
As in this configuration, the StructuredDataFilter can be used to log particular events:
</p><div class="prettyprint linenums"><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;warn&quot; name=&quot;MyApp&quot; packages=&quot;&quot;&gt;
&lt;StructuredDataFilter onMatch=&quot;ACCEPT&quot; onMismatch=&quot;NEUTRAL&quot; operator=&quot;or&quot;&gt;
&lt;KeyValuePair key=&quot;id&quot; value=&quot;Login&quot;/&gt;
&lt;KeyValuePair key=&quot;id&quot; value=&quot;Logout&quot;/&gt;
&lt;/StructuredDataFilter&gt;
&lt;Appenders&gt;
&lt;RollingFile name=&quot;RollingFile&quot; fileName=&quot;logs/app.log&quot;
filePattern=&quot;logs/app-%d{MM-dd-yyyy}.log.gz&quot;&gt;
&lt;BurstFilter level=&quot;INFO&quot; rate=&quot;16&quot; maxBurst=&quot;100&quot;/&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;TimeBasedTriggeringPolicy /&gt;
&lt;/RollingFile&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Root level=&quot;error&quot;&gt;
&lt;AppenderRef ref=&quot;RollingFile&quot;/&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;</pre></div>
</div>
<a name="ThreadContextMapFilter"></a>
<div class="section"><h3>ThreadContextMapFilter<a name="ThreadContextMapFilter"></a></h3>
<p>
The ThreadContextMapFilter allows filtering against data elements that are in the ThreadContext Map.
</p>
<table border="0" class="bodyTable"><caption align="top">ThreadContext Map Filter Parameters</caption>
<tr class="a">
<th>Parameter Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr class="b">
<td>keyValuePair</td>
<td>KeyValuePair[]</td>
<td>One or more KeyValuePair elements that define the key in the map and the value to match on. If the
same key is specified more than once then the check for that key will automatically be an &quot;or&quot; since
a Map can only contain a single value.</td>
</tr>
<tr class="a">
<td>operator</td>
<td>String</td>
<td>If the operator is &quot;or&quot; then a match by any one of the key/value pairs will be considered to be
a match, otherwise all the key/value pairs must match.</td>
</tr>
<tr class="b">
<td>onMatch</td>
<td>String</td>
<td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td>
</tr>
<tr class="a">
<td>onMismatch</td>
<td>String</td>
<td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is
DENY.</td>
</tr>
</table>
<p>
A configuration containing the ThreadContextMapFilter might look like:
</p><div class="prettyprint linenums"><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;warn&quot; name=&quot;MyApp&quot; packages=&quot;&quot;&gt;
&lt;ThreadContextMapFilter onMatch=&quot;ACCEPT&quot; onMismatch=&quot;NEUTRAL&quot; operator=&quot;or&quot;&gt;
&lt;KeyValuePair key=&quot;User1&quot; value=&quot;DEBUG&quot;/&gt;
&lt;KeyValuePair key=&quot;User2&quot; value=&quot;WARN&quot;/&gt;
&lt;/ThreadContextMapFilter&gt;
&lt;Appenders&gt;
&lt;RollingFile name=&quot;RollingFile&quot; fileName=&quot;logs/app.log&quot;
filePattern=&quot;logs/app-%d{MM-dd-yyyy}.log.gz&quot;&gt;
&lt;BurstFilter level=&quot;INFO&quot; rate=&quot;16&quot; maxBurst=&quot;100&quot;/&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;TimeBasedTriggeringPolicy /&gt;
&lt;/RollingFile&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Root level=&quot;error&quot;&gt;
&lt;AppenderRef ref=&quot;RollingFile&quot;/&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;</pre></div>
<p>
The ThreadContextMapFilter can also be applied to a logger for filtering:
</p><div class="prettyprint linenums"><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;warn&quot; name=&quot;MyApp&quot; packages=&quot;&quot;&gt;
&lt;Appenders&gt;
&lt;RollingFile name=&quot;RollingFile&quot; fileName=&quot;logs/app.log&quot;
filePattern=&quot;logs/app-%d{MM-dd-yyyy}.log.gz&quot;&gt;
&lt;BurstFilter level=&quot;INFO&quot; rate=&quot;16&quot; maxBurst=&quot;100&quot;/&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;TimeBasedTriggeringPolicy /&gt;
&lt;/RollingFile&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Root level=&quot;error&quot;&gt;
&lt;AppenderRef ref=&quot;RollingFile&quot;/&gt;
&lt;ThreadContextMapFilter onMatch=&quot;ACCEPT&quot; onMismatch=&quot;NEUTRAL&quot; operator=&quot;or&quot;&gt;
&lt;KeyValuePair key=&quot;foo&quot; value=&quot;bar&quot;/&gt;
&lt;KeyValuePair key=&quot;User2&quot; value=&quot;WARN&quot;/&gt;
&lt;/ThreadContextMapFilter&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;
</pre></div>
</div>
<a name="ThresholdFilter"></a>
<div class="section"><h3>ThresholdFilter<a name="ThresholdFilter"></a></h3>
<p>
This filter returns the onMatch result if the level in the LogEvent is the same or more specific
than the configured level and the onMismatch value otherwise. For example, if the ThresholdFilter
is configured with Level ERROR and the LogEvent contains Level DEBUG then the onMismatch value will
be returned since ERROR events are more specific than DEBUG.
</p>
<table border="0" class="bodyTable"><caption align="top">Threshold Filter Parameters</caption>
<tr class="a">
<th>Parameter Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr class="b">
<td>level</td>
<td>String</td>
<td>
A valid Level name to match on.
</td>
</tr>
<tr class="a">
<td>onMatch</td>
<td>String</td>
<td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td>
</tr>
<tr class="b">
<td>onMismatch</td>
<td>String</td>
<td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is
DENY.</td>
</tr>
</table>
<p>
A sample configuration that only allows the event to be written by the appender if the level matches:
</p><div class="prettyprint linenums"><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;warn&quot; name=&quot;MyApp&quot; packages=&quot;&quot;&gt;
&lt;Appenders&gt;
&lt;RollingFile name=&quot;RollingFile&quot; fileName=&quot;logs/app.log&quot;
filePattern=&quot;logs/app-%d{MM-dd-yyyy}.log.gz&quot;&gt;
&lt;ThresholdFilter level=&quot;TRACE&quot; onMatch=&quot;ACCEPT&quot; onMismatch=&quot;DENY&quot;/&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;TimeBasedTriggeringPolicy /&gt;
&lt;/RollingFile&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Root level=&quot;error&quot;&gt;
&lt;AppenderRef ref=&quot;RollingFile&quot;/&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;</pre></div>
</div>
<a name="TimeFilter"></a>
<div class="section"><h3>TimeFilter<a name="TimeFilter"></a></h3>
<p>
The time filter can be used to restrict filter to only a certain portion of the day.
</p>
<table border="0" class="bodyTable"><caption align="top">Time Filter Parameters</caption>
<tr class="a">
<th>Parameter Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr class="b">
<td>start</td>
<td>String</td>
<td>
A time in HH:mm:ss format.
</td>
</tr>
<tr class="a">
<td>end</td>
<td>String</td>
<td>
A time in HH:mm:ss format. Specifying an end time less than the start time will result in no
log entries being written.
</td>
</tr>
<tr class="b">
<td>timezone</td>
<td>String</td>
<td>
The timezone to use when comparing to the event timestamp.
</td>
</tr>
<tr class="a">
<td>onMatch</td>
<td>String</td>
<td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td>
</tr>
<tr class="b">
<td>onMismatch</td>
<td>String</td>
<td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is
DENY.</td>
</tr>
</table>
<p>
A sample configuration that only allows the event to be written by the appender from 5:00 to 5:30 am each
day using the default timezone:
</p><div class="prettyprint linenums"><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Configuration status=&quot;warn&quot; name=&quot;MyApp&quot; packages=&quot;&quot;&gt;
&lt;Appenders&gt;
&lt;RollingFile name=&quot;RollingFile&quot; fileName=&quot;logs/app.log&quot;
filePattern=&quot;logs/app-%d{MM-dd-yyyy}.log.gz&quot;&gt;
&lt;TimeFilter start=&quot;05:00:00&quot; end=&quot;05:30:00&quot; onMatch=&quot;ACCEPT&quot; onMismatch=&quot;DENY&quot;/&gt;
&lt;PatternLayout&gt;
&lt;pattern&gt;%d %p %c{1.} [%t] %m%n&lt;/pattern&gt;
&lt;/PatternLayout&gt;
&lt;TimeBasedTriggeringPolicy /&gt;
&lt;/RollingFile&gt;
&lt;/Appenders&gt;
&lt;Loggers&gt;
&lt;Root level=&quot;error&quot;&gt;
&lt;AppenderRef ref=&quot;RollingFile&quot;/&gt;
&lt;/Root&gt;
&lt;/Loggers&gt;
&lt;/Configuration&gt;</pre></div>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="footer">
<p>Copyright &copy; 1999-2014 <a class="external" href="http://www.apache.org">Apache Software Foundation</a>. All Rights Reserved.</p>
<p>Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p>
<p>Site powered by <a class="external" href="http://twitter.github.com/bootstrap/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p>
</div>
</div>
</body>
</html>