| <?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="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> |
