<?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 xmlns="http://maven.apache.org/XDOC/2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
    <properties>
        <title>Log4j 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 of 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>
          <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"/>
        <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>
            <caption align="top">Burst Filter Parameters</caption>
            <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>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>
              <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>
          <pre class="prettyprint linenums"><![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">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>
        </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:
          </p>
          <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <Filters>
    <MarkerFilter marker="EVENT" onMatch="ACCEPT" onMismatch="NEUTRAL"/>
    <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">
      <AppenderRef ref="Audit"/>
    </Logger>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>
        </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. If the log event does not contain the specified ThreadContext item
            NEUTRAL will be returned.
          </p>
          <table>
            <caption align="top">Dynamic Threshold Filter Parameters</caption>
            <tr>
              <th>Parameter Name</th>
              <th>Type</th>
              <th>Description</th>
            </tr>
            <tr>
              <td>key</td>
              <td>String</td>
              <td>The name of the item in the ThreadContext Map to compare.</td>
            </tr>
            <tr>
              <td>defaultThreshold</td>
              <td>String</td>
              <td>Level of messages to be filtered. The default threshold only applies if the log event contains
                the specified ThreadContext Map item and its value does not match any key in
                the key/value pairs.
              </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>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>
              <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>
          <pre class="prettyprint linenums"><![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">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>
        </subsection>
        <a name="MapFilter"/>
        <subsection name="MapFilter">
          <p>
            The MapFilter allows filtering against data elements that are in a MapMessage.
          </p>
          <table>
            <caption align="top">Map Filter Parameters</caption>
            <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. If the
              same key is specified more than once then the check for that key will automatically be an "or" since
              a Map can only contain a single value.</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>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>
              <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>
          <pre class="prettyprint linenums"><![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"/>
    <KeyValuePair 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">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>
          <p>
            This sample configuration will exhibit the same behavior as the preceding example since the only
            logger configured is the root.
          </p>
          <pre class="prettyprint linenums"><![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">
      <MapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
        <KeyValuePair key="eventId" value="Login"/>
        <KeyValuePair key="eventId" value="Logout"/>
      </MapFilter>
      <AppenderRef ref="RollingFile">
      </AppenderRef>
    </Root>
  </Loggers>
</Configuration>]]></pre>
          <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>
          <pre class="prettyprint linenums"><![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">
      <AppenderRef ref="RollingFile">
        <MapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
          <KeyValuePair key="eventId" value="Login"/>
          <KeyValuePair key="eventId" value="Logout"/>
        </MapFilter>
      </AppenderRef>
    </Root>
  </Loggers>
</Configuration>]]></pre>
        </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>
            <caption align="top">Marker Filter Parameters</caption>
            <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>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>
              <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>
          <pre class="prettyprint linenums"><![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">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>
        </subsection>
        <a name="MutableThreadContextMapFilter"/>
        <subsection name="MutableThreadContextMapFilter (or MutableContextMapFilter)">
          <p>
            The MutableThreadContextMapFilter or MutableContextMapFilter allows filtering against data elements that are in the
            current context. By default this is the ThreadContext Map. The values to compare are defined externally and
            can be periodically polled for changes.
          </p>
          <table>
            <caption align="top">Mutable Context Map Filter Parameters</caption>
            <tr>
              <th>Parameter Name</th>
              <th>Type</th>
              <th>Description</th>
            </tr>
            <tr>
              <td>configLocation</td>
              <td>String</td>
              <td>A file path or URI that points to the configuration. See below for a sample configuration.</td>
            </tr>
            <tr>
              <td>pollInterval</td>
              <td>int</td>
              <td>The number of seconds to wait before checking to see if the configuration has been modified. When
                using HTTP or HTTPS the server must support the If-Modified-Since header and return a Last-Modified
                header containing the date and time the file was last modified. Note that by default only the https,
                file, and jar protocols are allowed. Support for other protocols can be enabled by specifying them
                in the log4j2.Configuration.allowedProtocols system property</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>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>
              <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 MutableContextMapFilter might look like:
          </p>
          <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <MutableContextMapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or"
    configLocation="http://localhost:8080/threadContextFilter.json" pollInterval="300">
  </MutableContextMapFilter>
  <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">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>
          <p>
            The configuration file supplied to the filter should look similar to:
          </p>
          <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
{
  "configs": {
    "loginId": ["rgoers@apache.org", "logging@apache.org"],
    "accountNumber": ["30510263"]
  }
}
  ]]></pre>
        </subsection>
        <a name="NoMarkerFilter"/>
        <subsection name="NoMarkerFilter">
          <p>
          The NoMarkerFilter checks that there is no marker included in the LogEvent. A match occurs when there is no
          marker in the Log Event.</p>
          <table>
          <caption align="top">No Marker Filter Parameters</caption>
          <tr>
            <th>Parameter Name</th>
            <th>Type</th>
            <th>Description</th>
          </tr>
          <tr>
            <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>
              <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 no marker is there:</p>
          <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<?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">
      <NoMarkerFilter onMatch="ACCEPT" onMismatch="DENY"/>
      <PatternLayout pattern="%d %p %c{1.} [%t] %m%n"/>
      <TimeBasedTriggeringPolicy />
    </RollingFile>
  </Appenders>
  <Loggers>
    <Root level="error">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>
        </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>
            <caption align="top">Regex Filter Parameters</caption>
            <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>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>
              <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
            "test":
          </p>
          <pre class="prettyprint linenums"><![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">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>
        </subsection>
        <a name="Script"/>
        <subsection name="Script">
          <p>
            The ScriptFilter executes a script that returns true or false.
          </p>
          <table>
            <caption align="top">Script Filter Parameters</caption>
            <tr>
              <th>Parameter Name</th>
              <th>Type</th>
              <th>Description</th>
            </tr>
            <tr>
              <td>script</td>
              <td>Script, ScriptFile or ScriptRef</td>
              <td>The Script element that specifies the logic to be executed.
              </td>
            </tr>
            <tr>
              <td>onMatch</td>
              <td>String</td>
              <td>Action to take when the script returns true. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td>
            </tr>
            <tr>
              <td>onMismatch</td>
              <td>String</td>
              <td>Action to take when the filter returns false. May be ACCEPT, DENY or NEUTRAL. The default value is
                DENY.</td>
            </tr>
          </table>
          <table>
            <caption align="top">Script Parameters</caption>
            <tr>
              <th>Parameter Name</th>
              <th>Type</th>
              <th>Description</th>
            </tr>
            <tr>
              <td>configuration</td>
              <td>Configuration</td>
              <td>The Configuration that owns this ScriptFilter.</td>
            </tr>
            <tr>
              <td>level</td>
              <td>Level</td>
              <td>The logging Level associated with the event. Only present when configured as a global filter.</td>
            </tr>
            <tr>
              <td>loggerName</td>
              <td>String</td>
              <td>The name of the logger. Only present when configured as a global filter.</td>
            </tr>
            <tr>
              <td>logEvent</td>
              <td>LogEvent</td>
              <td>The LogEvent being processed. Not present when configured as a global filter.</td>
            </tr>
            <tr>
              <td>marker</td>
              <td>Marker</td>
              <td>The Marker passed on the logging call, if any. Only present when configured as a global filter.</td>
            </tr>
            <tr>
              <td>message</td>
              <td>Message</td>
              <td>The Message associated with the logging call. Only present when configured as a global filter.</td>
            </tr>
            <tr>
              <td>parameters</td>
              <td>Object[]</td>
              <td>The parameters passed to the logging call. Only present when configured as a global filter.
                Some Messages include the parameters as part of the Message.
              </td>
            </tr>
            <tr>
              <td>throwable</td>
              <td>Throwable</td>
              <td>The Throwable passed to the logging call, if any. Only present when configured as a global filter.
                Som Messages include Throwable as part of the Message.
              </td>
            </tr>
            <tr>
              <td>substitutor</td>
              <td>StrSubstitutor</td>
              <td>The StrSubstitutor used to replace lookup variables.</td>
            </tr>
          </table>
          <p>
            The sample below shows how to declare script fields and then reference them in specific components.
            See <a href="appenders.html#ScriptCondition">ScriptCondition</a> for an example of how the
            <tt>Script</tt> element can be used to embed script code directly in the configuration.
          </p>
          <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="ERROR">
  <Scripts>
    <ScriptFile name="filter.js" language="JavaScript" path="src/test/resources/scripts/filter.js" charset="UTF-8" />
    <ScriptFile name="filter.groovy" language="groovy" path="src/test/resources/scripts/filter.groovy" charset="UTF-8" />
  </Scripts>
  <Appenders>
    <List name="List">
      <PatternLayout pattern="[%-5level] %c{1.} %msg%n"/>
    </List>
  </Appenders>
  <Loggers>
    <Logger name="TestJavaScriptFilter" level="trace" additivity="false">
      <AppenderRef ref="List">
        <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY">
          <ScriptRef ref="filter.js" />
        </ScriptFilter>
      </AppenderRef>
    </Logger>
    <Logger name="TestGroovyFilter" level="trace" additivity="false">
      <AppenderRef ref="List">
        <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY">
          <ScriptRef ref="filter.groovy" />
        </ScriptFilter>
      </AppenderRef>
    </Logger>
    <Root level="trace">
      <AppenderRef ref="List" />
    </Root>
  </Loggers>
</Configuration>
          ]]></pre>
        </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>
            <caption align="top">StructuredData Filter Parameters</caption>
            <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. If the
                same key is specified more than once then the check for that key will automatically be an "or" since
                a Map can only contain a single value.
              </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>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>
              <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>
          <pre class="prettyprint linenums"><![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"/>
    <KeyValuePair 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">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>
        </subsection>
        <a name="ThreadContextMapFilter"/>
        <subsection name="ThreadContextMapFilter (or ContextMapFilter)">
          <p>
            The ThreadContextMapFilter or ContextMapFilter allows filtering against data elements that are in the
            current context. By default this is the ThreadContext Map.
          </p>
          <table>
            <caption align="top">Context Map Filter Parameters</caption>
            <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. If the
                same key is specified more than once then the check for that key will automatically be an "or" since
                a Map can only contain a single value.</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>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>
              <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 ContextMapFilter might look like:
          </p>
          <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp" packages="">
  <ContextMapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
    <KeyValuePair key="User1" value="DEBUG"/>
    <KeyValuePair key="User2" value="WARN"/>
  </ContextMapFilter>
  <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">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>
          <p>
            The ContextMapFilter can also be applied to a logger for filtering:
          </p>
          <pre class="prettyprint linenums"><![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">
      <AppenderRef ref="RollingFile"/>
      <ContextMapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or">
        <KeyValuePair key="foo" value="bar"/>
        <KeyValuePair key="User2" value="WARN"/>
      </ContextMapFilter>
    </Root>
  </Loggers>
</Configuration>
  ]]></pre>
        </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>
            <caption align="top">Threshold Filter Parameters</caption>
            <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>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>
              <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>
          <pre class="prettyprint linenums"><![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">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>
        </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>
            <caption align="top">Time Filter Parameters</caption>
            <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>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>
              <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>
          <pre class="prettyprint linenums"><![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">
      <TimeFilter 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">
      <AppenderRef ref="RollingFile"/>
    </Root>
  </Loggers>
</Configuration>]]></pre>
        </subsection>
      </section>
    </body>
</document>
