rgoers/src/site/xdoc/manual/filters.xml - logging-log4j1 - Git at Google

 <?xml version="1.0"?>
 <!--
     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.
 -->

 <document>
     <properties>
         <title>Log4J 2 Filters</title>
         <author email="rgoers@apache.org">Ralph Goers</author>
     </properties>

     <body>
       <section name="Filters">
         <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 three locations;
           <ol>
             <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>
           </ol>
         </p>
         <a name="BurstFilter"/>
         <subsection name="BurstFilter">
           <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="1" width="100%">
             <tr>
               <th>Parameter Name</th>
               <th>Type</th>
               <th>Description</th>
             </tr>
             <tr>
               <td>level</td>
               <td>String</td>
               <td>Level of messages to be filtered. Anything at or below this level will be
                 filtered out if <code>maxBurst</code> 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>
               <td>rate</td>
               <td>float</td>
               <td>The average number of events per second to allow.</td>
             </tr>
             <tr>
               <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>
               <td>omMatch</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>
               <td>omMismatch</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>
             <caption align="top">Burst Filter Parameters</caption>
           </table>
            <p>
             A configuration containing the BurstFilter might look like:

             <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <configuration status="warn" name="MyApp" packages="">
   <appenders>
     <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
       <BurstFilter level="INFO" rate="16" maxBurst="100"/>
       <PatternLayout>
         <pattern>%d %p %C{1.} [%t] %m%n</pattern>
       </PatternLayout>
       <TimeBasedTriggeringPolicy />
     </RollingFile>
   </appenders>
   <loggers>
     <root level="error">
       <appender-ref ref="RollingFile"/>
     </root>
   </loggers>
 </configuration>
   ]]></source>
           </p>
         </subsection>
         <a name="CompositeFilter"/>
         <subsection name="CompositeFilter">
           <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:

             <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <configuration status="warn" name="MyApp" packages="">
   <filters>
     <Marker marker="EVENT" onMatch="ACCEPT" onMismatch="NETURAL"/>
     <DynamicThresholdFilter key="loginId" defaultThreshold="ERROR" onMatch="ACCEPT" onMismatch="NEUTRAL">
       <KeyValuePair key="User1" value="DEBUG"/>
     </DynamicThresholdFilter>
   </filters>
   <appenders>
     <File name="Audit" fileName="logs/audit.log">
       <PatternLayout>
         <pattern>%d %p %C{1.} [%t] %m%n</pattern>
       </PatternLayout>
     </File>
     <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
       <BurstFilter level="INFO" rate="16" maxBurst="100"/>
       <PatternLayout>
         <pattern>%d %p %C{1.} [%t] %m%n</pattern>
       </PatternLayout>
       <TimeBasedTriggeringPolicy />
     </RollingFile>
   </appenders>
   <loggers>
     <logger name="EventLogger" level="info">
       <appender-ref ref="Audit"/>
     </logger>
     <root level="error">
       <appender-ref ref="RollingFile"/>
     </root>
   </loggers>
 </configuration>
   ]]></source>
           </p>
         </subsection>
         <a name="DynamicThresholdFilter"/>
         <subsection name="DynamicThresholdFilter">
           <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="1" width="100%">
             <tr>
               <th>Parameter Name</th>
               <th>Type</th>
               <th>Description</th>
             </tr>
             <tr>
               <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>
               <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>
               <td>omMatch</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>
               <td>omMismatch</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>
             <caption align="top">Dynamic Threshold Filter Parameters</caption>
           </table>
            <p>
             Here is a sample configuration containing the DynamicThresholdFilter:

             <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <configuration status="warn" name="MyApp" packages="">
     <DynamicThresholdFilter key="loginId" defaultThreshold="ERROR" onMatch="ACCEPT" onMismatch="NEUTRAL">
       <KeyValuePair key="User1" value="DEBUG"/>
     </DynamicThresholdFilter>
   <appenders>
     <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
       <BurstFilter level="INFO" rate="16" maxBurst="100"/>
       <PatternLayout>
         <pattern>%d %p %C{1.} [%t] %m%n</pattern>
       </PatternLayout>
       <TimeBasedTriggeringPolicy />
     </RollingFile>
   </appenders>
   <loggers>
     <root level="error">
       <appender-ref ref="RollingFile"/>
     </root>
   </loggers>
 </configuration>
   ]]></source>
           </p>
         </subsection>
         <a name="MapFilter"/>
         <subsection name="MapFilter">
           <p>
             The MapFilter allows filtering against data elements that are in a MapMessage.
           </p>
           <table border="1" width="100%">
             <tr>
               <th>Parameter Name</th>
               <th>Type</th>
               <th>Description</th>
             </tr>
             <tr>
               <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.</td>
             </tr>
             <tr>
               <td>operator</td>
               <td>String</td>
               <td>If the operator is "or" 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>
               <td>omMatch</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>
               <td>omMismatch</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>
             <caption align="top">Map Filter Parameters</caption>
           </table>
            <p>
             As in this configuration, the MapFilter can be used to log particular events:

             <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <configuration status="warn" name="MyApp" packages="">
   <MapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
     <KeyValuePair key="eventId" value="Login"/>
     <KeyValuePari key="eventId" value="Logout"/>
   </MapFilter>
   <appenders>
     <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
       <BurstFilter level="INFO" rate="16" maxBurst="100"/>
       <PatternLayout>
         <pattern>%d %p %C{1.} [%t] %m%n</pattern>
       </PatternLayout>
       <TimeBasedTriggeringPolicy />
     </RollingFile>
   </appenders>
   <loggers>
     <root level="error">
       <appender-ref ref="RollingFile"/>
     </root>
   </loggers>
 </configuration>
   ]]></source>
           </p>
         </subsection>
         <a name="MarkerFilter"/>
         <subsection name="MarkerFilter">
           <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="1" width="100%">
             <tr>
               <th>Parameter Name</th>
               <th>Type</th>
               <th>Description</th>
             </tr>
             <tr>
               <td>marker</td>
               <td>String</td>
               <td>
                 The name of the Marker to compare.
               </td>
             </tr>
             <tr>
               <td>omMatch</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>
               <td>omMismatch</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>
             <caption align="top">Marker Filter Parameters</caption>
           </table>
            <p>
              A sample configuration that only allows the event to be written by the appender if the Marker matches:

             <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <configuration status="warn" name="MyApp" packages="">
   <appenders>
     <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
       <MarkerFilter marker="FLOW" onMatch="ACCEPT" onMismatch="DENY"/>
       <PatternLayout>
         <pattern>%d %p %C{1.} [%t] %m%n</pattern>
       </PatternLayout>
       <TimeBasedTriggeringPolicy />
     </RollingFile>
   </appenders>
   <loggers>
     <root level="error">
       <appender-ref ref="RollingFile"/>
     </root>
   </loggers>
 </configuration>
   ]]></source>
           </p>
         </subsection>
         <a name="RegexFilter"/>
         <subsection name="RegexFilter">
            <p>
             The RegexFilter allows the formatted or unformatted message to be compared against a regular expression.
           </p>
           <table border="1" width="100%">
             <tr>
               <th>Parameter Name</th>
               <th>Type</th>
               <th>Description</th>
             </tr>
             <tr>
               <td>regex</td>
               <td>String</td>
               <td>
                 The regular expression.
               </td>
             </tr>
             <tr>
               <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>
               <td>omMatch</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>
               <td>omMismatch</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>
             <caption align="top">Regex Filter Parameters</caption>
           </table>
            <p>
              A sample configuration that only allows the event to be written by the appender if it contains the word "test":

             <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <configuration status="warn" name="MyApp" packages="">
   <appenders>
     <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
       <RegexFilter regex=".* test .*" onMatch="ACCEPT" onMismatch="DENY"/>
       <PatternLayout>
         <pattern>%d %p %C{1.} [%t] %m%n</pattern>
       </PatternLayout>
       <TimeBasedTriggeringPolicy />
     </RollingFile>
   </appenders>
   <loggers>
     <root level="error">
       <appender-ref ref="RollingFile"/>
     </root>
   </loggers>
 </configuration>
   ]]></source>
           </p>
         </subsection>
         <a name="StructuredDataFilter"/>
         <subsection name="StructuredDataFilter">
           <p>
             The StructuredDataFilter is a MapFilter that also allows filtering on the event id, type and message.
           </p>
           <table border="1" width="100%">
             <tr>
               <th>Parameter Name</th>
               <th>Type</th>
               <th>Description</th>
             </tr>
             <tr>
               <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. "id",
                 "id.name", "type", and "message" should be used to match on the StructuredDataId, the name
                 portion of the StructuredDataId, the type, and the formatted message respectively.
               </td>
             </tr>
             <tr>
               <td>operator</td>
               <td>String</td>
               <td>If the operator is "or" 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>
               <td>omMatch</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>
               <td>omMismatch</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>
             <caption align="top">StructuredData Filter Parameters</caption>
           </table>
            <p>
             As in this configuration, the StructuredDataFilter can be used to log particular events:

             <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <configuration status="warn" name="MyApp" packages="">
   <StructuredDataFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
     <KeyValuePair key="id" value="Login"/>
     <KeyValuePari key="id" value="Logout"/>
   </StructuredDataFilter>
   <appenders>
     <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
       <BurstFilter level="INFO" rate="16" maxBurst="100"/>
       <PatternLayout>
         <pattern>%d %p %C{1.} [%t] %m%n</pattern>
       </PatternLayout>
       <TimeBasedTriggeringPolicy />
     </RollingFile>
   </appenders>
   <loggers>
     <root level="error">
       <appender-ref ref="RollingFile"/>
     </root>
   </loggers>
 </configuration>
   ]]></source>
           </p>
         </subsection>
         <a name="ThreadContextMapFilter"/>
         <subsection name="ThreadContextMapFilter">
           <p>
             The ThreadContextMapFilter allows filtering against data elements that are in the ThreadContext Map.
           </p>
           <table border="1" width="100%">
             <tr>
               <th>Parameter Name</th>
               <th>Type</th>
               <th>Description</th>
             </tr>
             <tr>
               <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.</td>
             </tr>
             <tr>
               <td>operator</td>
               <td>String</td>
               <td>If the operator is "or" 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>
               <td>omMatch</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>
               <td>omMismatch</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>
             <caption align="top">ThreadContext Map Filter Parameters</caption>
           </table>
            <p>
             A configuration containing the ThreadContextMapFilter might look like:

             <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <configuration status="warn" name="MyApp" packages="">
   <DynamicThresholdFilter key="loginId" defaultThreshold="ERROR" onMatch="ACCEPT" onMismatch="NEUTRAL">
     <KeyValuePair key="User1" value="DEBUG"/>
   </DynamicThresholdFilter>
   <appenders>
     <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
       <BurstFilter level="INFO" rate="16" maxBurst="100"/>
       <PatternLayout>
         <pattern>%d %p %C{1.} [%t] %m%n</pattern>
       </PatternLayout>
       <TimeBasedTriggeringPolicy />
     </RollingFile>
   </appenders>
   <loggers>
     <root level="error">
       <appender-ref ref="RollingFile"/>
     </root>
   </loggers>
 </configuration>
   ]]></source>
           </p>
         </subsection>
         <a name="ThresholdFilter"/>
         <subsection name="ThresholdFilter">
            <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="1" width="100%">
             <tr>
               <th>Parameter Name</th>
               <th>Type</th>
               <th>Description</th>
             </tr>
             <tr>
               <td>level</td>
               <td>String</td>
               <td>
                 A valid Level name to match on.
               </td>
             </tr>
             <tr>
               <td>omMatch</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>
               <td>omMismatch</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>
             <caption align="top">Threshold Filter Parameters</caption>
           </table>
            <p>
              A sample configuration that only allows the event to be written by the appender if the level matches:

             <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <configuration status="warn" name="MyApp" packages="">
   <appenders>
     <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
       <ThresholdFilter level="TRACE" onMatch="ACCEPT" onMismatch="DENY"/>
       <PatternLayout>
         <pattern>%d %p %C{1.} [%t] %m%n</pattern>
       </PatternLayout>
       <TimeBasedTriggeringPolicy />
     </RollingFile>
   </appenders>
   <loggers>
     <root level="error">
       <appender-ref ref="RollingFile"/>
     </root>
   </loggers>
 </configuration>
   ]]></source>
           </p>
         </subsection>
         <a name="TimeFilter"/>
         <subsection name="TimeFilter">
            <p>
             The time filter can be used to restrict filter to only a certain portion of the day.
           </p>
           <table border="1" width="100%">
             <tr>
               <th>Parameter Name</th>
               <th>Type</th>
               <th>Description</th>
             </tr>
             <tr>
               <td>start</td>
               <td>String</td>
               <td>
                 A time in HH:mm:ss format.
               </td>
             </tr>
             <tr>
               <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>
               <td>timezone</td>
               <td>String</td>
               <td>
                 The timezone to use when comparing to the event timestamp.
               </td>
             </tr>
             <tr>
               <td>omMatch</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>
               <td>omMismatch</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>
             <caption align="top">Time Filter Parameters</caption>
           </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:

             <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <configuration status="warn" name="MyApp" packages="">
   <appenders>
     <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
       <TiemFilter start="05:00:00" end="05:30:00" onMatch="ACCEPT" onMismatch="DENY"/>
       <PatternLayout>
         <pattern>%d %p %C{1.} [%t] %m%n</pattern>
       </PatternLayout>
       <TimeBasedTriggeringPolicy />
     </RollingFile>
   </appenders>
   <loggers>
     <root level="error">
       <appender-ref ref="RollingFile"/>
     </root>
   </loggers>
 </configuration>
   ]]></source>
           </p>
         </subsection>
       </section>
     </body>
 </document>
	<?xml version="1.0"?>
	<!--
	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.
	-->

	<document>
	<properties>
	<title>Log4J 2 Filters</title>
	<author email="rgoers@apache.org">Ralph Goers</author>
	</properties>

	<body>
	<section name="Filters">
	<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 three locations;
	<ol>
	<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>
	</ol>
	</p>
	<a name="BurstFilter"/>
	<subsection name="BurstFilter">
	<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="1" width="100%">
	<tr>
	<th>Parameter Name</th>
	<th>Type</th>
	<th>Description</th>
	</tr>
	<tr>
	<td>level</td>
	<td>String</td>
	<td>Level of messages to be filtered. Anything at or below this level will be
	filtered out if <code>maxBurst</code> 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>
	<td>rate</td>
	<td>float</td>
	<td>The average number of events per second to allow.</td>
	</tr>
	<tr>
	<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>
	<td>omMatch</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>
	<td>omMismatch</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>
	<caption align="top">Burst Filter Parameters</caption>
	</table>
	<p>
	A configuration containing the BurstFilter might look like:

	<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
	<configuration status="warn" name="MyApp" packages="">
	<appenders>
	<RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
	<BurstFilter level="INFO" rate="16" maxBurst="100"/>
	<PatternLayout>
	<pattern>%d %p %C{1.} [%t] %m%n</pattern>
	</PatternLayout>
	<TimeBasedTriggeringPolicy />
	</RollingFile>
	</appenders>
	<loggers>
	<root level="error">
	<appender-ref ref="RollingFile"/>
	</root>
	</loggers>
	</configuration>
	]]></source>
	</p>
	</subsection>
	<a name="CompositeFilter"/>
	<subsection name="CompositeFilter">
	<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:

	<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
	<configuration status="warn" name="MyApp" packages="">
	<filters>
	<Marker marker="EVENT" onMatch="ACCEPT" onMismatch="NETURAL"/>
	<DynamicThresholdFilter key="loginId" defaultThreshold="ERROR" onMatch="ACCEPT" onMismatch="NEUTRAL">
	<KeyValuePair key="User1" value="DEBUG"/>
	</DynamicThresholdFilter>
	</filters>
	<appenders>
	<File name="Audit" fileName="logs/audit.log">
	<PatternLayout>
	<pattern>%d %p %C{1.} [%t] %m%n</pattern>
	</PatternLayout>
	</File>
	<RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
	<BurstFilter level="INFO" rate="16" maxBurst="100"/>
	<PatternLayout>
	<pattern>%d %p %C{1.} [%t] %m%n</pattern>
	</PatternLayout>
	<TimeBasedTriggeringPolicy />
	</RollingFile>
	</appenders>
	<loggers>
	<logger name="EventLogger" level="info">
	<appender-ref ref="Audit"/>
	</logger>
	<root level="error">
	<appender-ref ref="RollingFile"/>
	</root>
	</loggers>
	</configuration>
	]]></source>
	</p>
	</subsection>
	<a name="DynamicThresholdFilter"/>
	<subsection name="DynamicThresholdFilter">
	<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="1" width="100%">
	<tr>
	<th>Parameter Name</th>
	<th>Type</th>
	<th>Description</th>
	</tr>
	<tr>
	<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>
	<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>
	<td>omMatch</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>
	<td>omMismatch</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>
	<caption align="top">Dynamic Threshold Filter Parameters</caption>
	</table>
	<p>
	Here is a sample configuration containing the DynamicThresholdFilter:

	<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
	<configuration status="warn" name="MyApp" packages="">
	<DynamicThresholdFilter key="loginId" defaultThreshold="ERROR" onMatch="ACCEPT" onMismatch="NEUTRAL">
	<KeyValuePair key="User1" value="DEBUG"/>
	</DynamicThresholdFilter>
	<appenders>
	<RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
	<BurstFilter level="INFO" rate="16" maxBurst="100"/>
	<PatternLayout>
	<pattern>%d %p %C{1.} [%t] %m%n</pattern>
	</PatternLayout>
	<TimeBasedTriggeringPolicy />
	</RollingFile>
	</appenders>
	<loggers>
	<root level="error">
	<appender-ref ref="RollingFile"/>
	</root>
	</loggers>
	</configuration>
	]]></source>
	</p>
	</subsection>
	<a name="MapFilter"/>
	<subsection name="MapFilter">
	<p>
	The MapFilter allows filtering against data elements that are in a MapMessage.
	</p>
	<table border="1" width="100%">
	<tr>
	<th>Parameter Name</th>
	<th>Type</th>
	<th>Description</th>
	</tr>
	<tr>
	<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.</td>
	</tr>
	<tr>
	<td>operator</td>
	<td>String</td>
	<td>If the operator is "or" 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>
	<td>omMatch</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>
	<td>omMismatch</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>
	<caption align="top">Map Filter Parameters</caption>
	</table>
	<p>
	As in this configuration, the MapFilter can be used to log particular events:

	<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
	<configuration status="warn" name="MyApp" packages="">
	<MapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
	<KeyValuePair key="eventId" value="Login"/>
	<KeyValuePari key="eventId" value="Logout"/>
	</MapFilter>
	<appenders>
	<RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
	<BurstFilter level="INFO" rate="16" maxBurst="100"/>
	<PatternLayout>
	<pattern>%d %p %C{1.} [%t] %m%n</pattern>
	</PatternLayout>
	<TimeBasedTriggeringPolicy />
	</RollingFile>
	</appenders>
	<loggers>
	<root level="error">
	<appender-ref ref="RollingFile"/>
	</root>
	</loggers>
	</configuration>
	]]></source>
	</p>
	</subsection>
	<a name="MarkerFilter"/>
	<subsection name="MarkerFilter">
	<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="1" width="100%">
	<tr>
	<th>Parameter Name</th>
	<th>Type</th>
	<th>Description</th>
	</tr>
	<tr>
	<td>marker</td>
	<td>String</td>
	<td>
	The name of the Marker to compare.
	</td>
	</tr>
	<tr>
	<td>omMatch</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>
	<td>omMismatch</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>
	<caption align="top">Marker Filter Parameters</caption>
	</table>
	<p>
	A sample configuration that only allows the event to be written by the appender if the Marker matches:

	<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
	<configuration status="warn" name="MyApp" packages="">
	<appenders>
	<RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
	<MarkerFilter marker="FLOW" onMatch="ACCEPT" onMismatch="DENY"/>
	<PatternLayout>
	<pattern>%d %p %C{1.} [%t] %m%n</pattern>
	</PatternLayout>
	<TimeBasedTriggeringPolicy />
	</RollingFile>
	</appenders>
	<loggers>
	<root level="error">
	<appender-ref ref="RollingFile"/>
	</root>
	</loggers>
	</configuration>
	]]></source>
	</p>
	</subsection>
	<a name="RegexFilter"/>
	<subsection name="RegexFilter">
	<p>
	The RegexFilter allows the formatted or unformatted message to be compared against a regular expression.
	</p>
	<table border="1" width="100%">
	<tr>
	<th>Parameter Name</th>
	<th>Type</th>
	<th>Description</th>
	</tr>
	<tr>
	<td>regex</td>
	<td>String</td>
	<td>
	The regular expression.
	</td>
	</tr>
	<tr>
	<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>
	<td>omMatch</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>
	<td>omMismatch</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>
	<caption align="top">Regex Filter Parameters</caption>
	</table>
	<p>
	A sample configuration that only allows the event to be written by the appender if it contains the word "test":

	<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
	<configuration status="warn" name="MyApp" packages="">
	<appenders>
	<RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
	<RegexFilter regex=".* test .*" onMatch="ACCEPT" onMismatch="DENY"/>
	<PatternLayout>
	<pattern>%d %p %C{1.} [%t] %m%n</pattern>
	</PatternLayout>
	<TimeBasedTriggeringPolicy />
	</RollingFile>
	</appenders>
	<loggers>
	<root level="error">
	<appender-ref ref="RollingFile"/>
	</root>
	</loggers>
	</configuration>
	]]></source>
	</p>
	</subsection>
	<a name="StructuredDataFilter"/>
	<subsection name="StructuredDataFilter">
	<p>
	The StructuredDataFilter is a MapFilter that also allows filtering on the event id, type and message.
	</p>
	<table border="1" width="100%">
	<tr>
	<th>Parameter Name</th>
	<th>Type</th>
	<th>Description</th>
	</tr>
	<tr>
	<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. "id",
	"id.name", "type", and "message" should be used to match on the StructuredDataId, the name
	portion of the StructuredDataId, the type, and the formatted message respectively.
	</td>
	</tr>
	<tr>
	<td>operator</td>
	<td>String</td>
	<td>If the operator is "or" 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>
	<td>omMatch</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>
	<td>omMismatch</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>
	<caption align="top">StructuredData Filter Parameters</caption>
	</table>
	<p>
	As in this configuration, the StructuredDataFilter can be used to log particular events:

	<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
	<configuration status="warn" name="MyApp" packages="">
	<StructuredDataFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
	<KeyValuePair key="id" value="Login"/>
	<KeyValuePari key="id" value="Logout"/>
	</StructuredDataFilter>
	<appenders>
	<RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
	<BurstFilter level="INFO" rate="16" maxBurst="100"/>
	<PatternLayout>
	<pattern>%d %p %C{1.} [%t] %m%n</pattern>
	</PatternLayout>
	<TimeBasedTriggeringPolicy />
	</RollingFile>
	</appenders>
	<loggers>
	<root level="error">
	<appender-ref ref="RollingFile"/>
	</root>
	</loggers>
	</configuration>
	]]></source>
	</p>
	</subsection>
	<a name="ThreadContextMapFilter"/>
	<subsection name="ThreadContextMapFilter">
	<p>
	The ThreadContextMapFilter allows filtering against data elements that are in the ThreadContext Map.
	</p>
	<table border="1" width="100%">
	<tr>
	<th>Parameter Name</th>
	<th>Type</th>
	<th>Description</th>
	</tr>
	<tr>
	<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.</td>
	</tr>
	<tr>
	<td>operator</td>
	<td>String</td>
	<td>If the operator is "or" 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>
	<td>omMatch</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>
	<td>omMismatch</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>
	<caption align="top">ThreadContext Map Filter Parameters</caption>
	</table>
	<p>
	A configuration containing the ThreadContextMapFilter might look like:

	<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
	<configuration status="warn" name="MyApp" packages="">
	<DynamicThresholdFilter key="loginId" defaultThreshold="ERROR" onMatch="ACCEPT" onMismatch="NEUTRAL">
	<KeyValuePair key="User1" value="DEBUG"/>
	</DynamicThresholdFilter>
	<appenders>
	<RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
	<BurstFilter level="INFO" rate="16" maxBurst="100"/>
	<PatternLayout>
	<pattern>%d %p %C{1.} [%t] %m%n</pattern>
	</PatternLayout>
	<TimeBasedTriggeringPolicy />
	</RollingFile>
	</appenders>
	<loggers>
	<root level="error">
	<appender-ref ref="RollingFile"/>
	</root>
	</loggers>
	</configuration>
	]]></source>
	</p>
	</subsection>
	<a name="ThresholdFilter"/>
	<subsection name="ThresholdFilter">
	<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="1" width="100%">
	<tr>
	<th>Parameter Name</th>
	<th>Type</th>
	<th>Description</th>
	</tr>
	<tr>
	<td>level</td>
	<td>String</td>
	<td>
	A valid Level name to match on.
	</td>
	</tr>
	<tr>
	<td>omMatch</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>
	<td>omMismatch</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>
	<caption align="top">Threshold Filter Parameters</caption>
	</table>
	<p>
	A sample configuration that only allows the event to be written by the appender if the level matches:

	<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
	<configuration status="warn" name="MyApp" packages="">
	<appenders>
	<RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
	<ThresholdFilter level="TRACE" onMatch="ACCEPT" onMismatch="DENY"/>
	<PatternLayout>
	<pattern>%d %p %C{1.} [%t] %m%n</pattern>
	</PatternLayout>
	<TimeBasedTriggeringPolicy />
	</RollingFile>
	</appenders>
	<loggers>
	<root level="error">
	<appender-ref ref="RollingFile"/>
	</root>
	</loggers>
	</configuration>
	]]></source>
	</p>
	</subsection>
	<a name="TimeFilter"/>
	<subsection name="TimeFilter">
	<p>
	The time filter can be used to restrict filter to only a certain portion of the day.
	</p>
	<table border="1" width="100%">
	<tr>
	<th>Parameter Name</th>
	<th>Type</th>
	<th>Description</th>
	</tr>
	<tr>
	<td>start</td>
	<td>String</td>
	<td>
	A time in HH:mm:ss format.
	</td>
	</tr>
	<tr>
	<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>
	<td>timezone</td>
	<td>String</td>
	<td>
	The timezone to use when comparing to the event timestamp.
	</td>
	</tr>
	<tr>
	<td>omMatch</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>
	<td>omMismatch</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>
	<caption align="top">Time Filter Parameters</caption>
	</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:

	<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
	<configuration status="warn" name="MyApp" packages="">
	<appenders>
	<RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz">
	<TiemFilter start="05:00:00" end="05:30:00" onMatch="ACCEPT" onMismatch="DENY"/>
	<PatternLayout>
	<pattern>%d %p %C{1.} [%t] %m%n</pattern>
	</PatternLayout>
	<TimeBasedTriggeringPolicy />
	</RollingFile>
	</appenders>
	<loggers>
	<root level="error">
	<appender-ref ref="RollingFile"/>
	</root>
	</loggers>
	</configuration>
	]]></source>
	</p>
	</subsection>
	</section>
	</body>
	</document>