| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- |
| | (Unfortunately) copied from the Fluido skin to allow the footer to be centered. |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <title> |
| Log4J2 Filters</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| |
| |
| <script type="text/javascript" src="../js/apache-maven-fluido.min.js"></script> |
| |
| |
| <meta name="author" content="Ralph Goers" /> |
| <meta name="Date-Revision-yyyymmdd" content="20120729" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| </head> |
| <body class="topBarDisabled"> |
| |
| |
| |
| |
| <div class="container-fluid"> |
| <div id="banner"> |
| <div class="pull-left"> |
| <a href="../../../" id="bannerLeft"> |
| <img src="../images/ls-logo.jpg" alt="Apache Logging Services™"/> |
| </a> |
| </div> |
| <div class="pull-right"> <div id="bannerRight"> |
| <img src="../images/logo.jpg" /> |
| </div> |
| </div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| |
| |
| <li id="publishDate">Last Published: 2012-07-29</li> |
| <li class="divider">|</li> <li id="projectVersion">Version: 2.0-alpha1</li> |
| |
| |
| |
| |
| |
| <li class="pull-right"> <a href="../../../" title="Logging Services">Logging Services</a> |
| </li> |
| |
| <li class="divider pull-right">|</li> |
| |
| <li class="pull-right"> <a href="http://www.apache.org/" class="externalLink" title="Apache">Apache</a> |
| </li> |
| |
| <li class="divider pull-right">|</li> |
| |
| <li class="pull-right"> <a href="http://wiki.apache.org/logging" class="externalLink" title="Logging Wiki">Logging Wiki</a> |
| </li> |
| |
| </ul> |
| </div> |
| |
| <div class="row-fluid"> |
| <div id="leftColumn" class="span2"> |
| <div class="well sidebar-nav"> |
| |
| |
| <h3>Apache Log4j™ 2</h3> |
| <ul> |
| <li class="none"> |
| <a href="../index.html" title="About">About</a> |
| </li> |
| <li class="none"> |
| <a href="../download.html" title="Download">Download</a> |
| </li> |
| <li class="none"> |
| <a href="../build.html" title="Build and Install">Build and Install</a> |
| </li> |
| <li class="none"> |
| <a href="../changelog.html" title="Changelog">Changelog</a> |
| </li> |
| </ul> |
| <h3>Manual</h3> |
| <ul> |
| <li class="none"> |
| <a href="../manual/index.html" title="Introduction">Introduction</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/architecture.html" title="Architecture">Architecture</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/api.html" title="API">API</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/configuration.html" title="Configuration">Configuration</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/plugins.html" title="Plugins">Plugins</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/lookups.html" title="Lookups">Lookups</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/appenders.html" title="Appenders">Appenders</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/layouts.html" title="Layouts">Layouts</a> |
| </li> |
| <li class="expanded"> |
| <strong>Filters</strong> |
| <ul> |
| <li class="none"> |
| <a href="../manual/filters.html#BurstFilter" title="Burst">Burst</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/filters.html#CompositeFilter" title="CompositeFilter">CompositeFilter</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/filters.html#DynamicThresholdFilter" title="DynamicThreshold">DynamicThreshold</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/filters.html#MapFilter" title="Map">Map</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/filters.html#MarkerFilter" title="Marker">Marker</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/filters.html#RegexFilter" title="Regex">Regex</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/filters.html#StructuredDataFilter" title="StructuredData">StructuredData</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/filters.html#ThreadContextMapFilter" title="ThreadContextMap">ThreadContextMap</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/filters.html#ThresholdFilter" title="Threshold">Threshold</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/filters.html#TimeFilter" title="Time">Time</a> |
| </li> |
| </ul> |
| </li> |
| <li class="none"> |
| <a href="../manual/jmx.html" title="JMX">JMX</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/logsep.html" title="Logging Separation">Logging Separation</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/extending.html" title="Extending Log4j">Extending Log4j</a> |
| </li> |
| </ul> |
| <h3>Logging Adapters</h3> |
| <ul> |
| <li class="none"> |
| <a href="../log4j12-api/api.html" title="Log4j 1.x API">Log4j 1.x API</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j2-jcl/api.html" title="Commons Logging">Commons Logging</a> |
| </li> |
| <li class="none"> |
| <a href="../slf4j-impl/api.html" title="SLF4J">SLF4J</a> |
| </li> |
| </ul> |
| <h3>Components</h3> |
| <ul> |
| <li class="none"> |
| <a href="../log4j-api/index.html" title="API">API</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-core/index.html" title="Impl">Impl</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j12-api/index.html" title="Log4J 1.2 API">Log4J 1.2 API</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-jcl/index.html" title="Commons Logging Bridge">Commons Logging Bridge</a> |
| </li> |
| <li class="none"> |
| <a href="../slf4j-impl/index.html" title="SLF4J Binding">SLF4J Binding</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-flume-ng/index.html" title="Apache Flume">Apache Flume</a> |
| </li> |
| </ul> |
| <h3>Site Documentation</h3> |
| <ul> |
| <li class="collapsed"> |
| <a href="../project-info.html" title="Project Information">Project Information</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../project-reports.html" title="Project Reports">Project Reports</a> |
| </li> |
| </ul> |
| |
| |
| |
| <hr class="divider" /> |
| |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="poweredBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /> |
| </a> |
| </div> |
| </div> |
| </div> |
| |
| <div id="bodyColumn" class="span10" > |
| |
| <!-- Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. --> |
| |
| <div class="section"><h2>Filters<a name="Filters"></a></h2> |
| <p> |
| Filters allow Log Events to be evaluated to determine if or how they should be published. A Filter |
| will be called on one if its filter methods and will return a Result, which is an Enum that has |
| one of 3 values - ACCEPT, DENY or NEUTRAL. |
| </p> |
| <p> |
| Filters may be configured in one of four locations; |
| </p><ol style="list-style-type: decimal"> |
| <li>Context-wide Filters are configured directly in the configuration. Events that are |
| rejected by these filters will not be passed to loggers for further processing. Once an |
| event has been accepted by a Context-wide filter it will not be evaluated by any other |
| Context-wide Filters nor will the Logger's Level be used to filter the event. The event |
| will be evaluated by Logger and Appender Filters however.</li> |
| <li>Logger Filters are configured on a specified Logger. These are evaluated after the |
| Context-wide Filters and the Log Level for the Logger. Events that are rejected by these |
| filters will be discarded and the event will not be passed to a parent Logger regardless |
| of the additivity setting.</li> |
| <li>Appender Filters are used to determine if a specific Appender should handle the |
| formatting and publication of the event.</li> |
| <li>Appender Reference Filters are used to determine if a Logger should route the event to |
| an appender.</li> |
| </ol> |
| |
| <a name="BurstFilter"></a> |
| <div class="section"><h3>BurstFilter<a name="BurstFilter"></a></h3> |
| <p> |
| The BurstFilter provides a mechanism to control the rate at which LogEvents are processed by |
| silently discarding events after the maximum limit has been reached. |
| </p> |
| <table class="table table-striped" border="1" width="100%"><caption align="top">Burst Filter Parameters</caption> |
| <tr class="a"> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr class="b"> |
| <td>level</td> |
| <td>String</td> |
| <td>Level of messages to be filtered. Anything at or below this level will be |
| filtered out if <tt>maxBurst</tt> has been exceeded. The default is |
| WARN meaning any messages that are higher than warn will be logged |
| regardless of the size of a burst. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>rate</td> |
| <td>float</td> |
| <td>The average number of events per second to allow.</td> |
| </tr> |
| <tr class="b"> |
| <td>maxBurst</td> |
| <td>integer</td> |
| <td>The maximum number of events that can occur before events are filtered for exceeding the |
| average rate. The default is 10 times the rate.</td> |
| </tr> |
| <tr class="a"> |
| <td>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 class="b"> |
| <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> |
| |
| </table> |
| <p> |
| A configuration containing the BurstFilter might look like: |
| |
| </p><div class="source"><pre class="prettyprint"><?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> |
| </pre></div> |
| |
| </div> |
| <a name="CompositeFilter"></a> |
| <div class="section"><h3>CompositeFilter<a name="CompositeFilter"></a></h3> |
| <p> |
| The CompositeFilter provides a way to specify more than one filter. It is added to the |
| configuration as a filters element and contains other filters to be evaluated. The filters |
| element accepts no parameters. |
| </p> |
| <p> |
| A configuration containing the CompositeFilter might look like: |
| |
| </p><div class="source"><pre class="prettyprint"><?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> |
| </pre></div> |
| |
| </div> |
| <a name="DynamicThresholdFilter"></a> |
| <div class="section"><h3>DynamicThresholdFilter<a name="DynamicThresholdFilter"></a></h3> |
| <p> |
| The DynamicThresholdFilter allows filtering by log level based on specific attributes. For example, |
| if the user's loginid is being captured in the ThreadContext Map then it is possible to enable |
| debug logging for only that user. |
| </p> |
| <table class="table table-striped" border="1" width="100%"><caption align="top">Dynamic Threshold Filter Parameters</caption> |
| <tr class="a"> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr class="b"> |
| <td>defaultThreshold</td> |
| <td>String</td> |
| <td>Level of messages to be filtered. If there is no matching key in the key/value pairs |
| then this level will be compared against the event's level. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>keyValuePair</td> |
| <td>KeyValuePair[]</td> |
| <td>One or more KeyValuePair elements that define the matching value for the key and the Level |
| to evaluate when the key matches.</td> |
| </tr> |
| <tr class="b"> |
| <td>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 class="a"> |
| <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> |
| |
| </table> |
| <p> |
| Here is a sample configuration containing the DynamicThresholdFilter: |
| |
| </p><div class="source"><pre class="prettyprint"><?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> |
| </pre></div> |
| |
| </div> |
| <a name="MapFilter"></a> |
| <div class="section"><h3>MapFilter<a name="MapFilter"></a></h3> |
| <p> |
| The MapFilter allows filtering against data elements that are in a MapMessage. |
| </p> |
| <table class="table table-striped" border="1" width="100%"><caption align="top">Map Filter Parameters</caption> |
| <tr class="a"> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr class="b"> |
| <td>keyValuePair</td> |
| <td>KeyValuePair[]</td> |
| <td>One or more KeyValuePair elements that define the key in the map and the value to match on.</td> |
| </tr> |
| <tr class="a"> |
| <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 class="b"> |
| <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 class="a"> |
| <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> |
| |
| </table> |
| <p> |
| As in this configuration, the MapFilter can be used to log particular events: |
| |
| </p><div class="source"><pre class="prettyprint"><?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> |
| </pre></div> |
| |
| <p> |
| This sample configuration will exhibit the same behavior as the preceding example since the only |
| logger configured is the root. |
| |
| </p><div class="source"><pre class="prettyprint"><?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"/> |
| <KeyValuePari key="eventId" value="Logout"/> |
| </MapFilter> |
| <appender-ref ref="RollingFile"> |
| </appender-ref> |
| </root> |
| </loggers> |
| </configuration> |
| </pre></div> |
| |
| <p> |
| This third sample configuration will exhibit the same behavior as the preceding examples since the only |
| logger configured is the root and the root is only configured with a single appender reference. |
| |
| </p><div class="source"><pre class="prettyprint"><?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"> |
| <MapFilter onMatch="ACCEPT" onMismatch="NEUTRAL" operator="or"> |
| <KeyValuePair key="eventId" value="Login"/> |
| <KeyValuePari key="eventId" value="Logout"/> |
| </MapFilter> |
| </appender-ref> |
| </root> |
| </loggers> |
| </configuration> |
| </pre></div> |
| |
| </div> |
| <a name="MarkerFilter"></a> |
| <div class="section"><h3>MarkerFilter<a name="MarkerFilter"></a></h3> |
| <p> |
| The MarkerFilter compares the configured Marker value against the Marker that is included |
| in the LogEvent. A match occurs when the Marker name matches either the Log Event's Marker |
| or one of its parents. |
| </p> |
| <table class="table table-striped" border="1" width="100%"><caption align="top">Marker Filter Parameters</caption> |
| <tr class="a"> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr class="b"> |
| <td>marker</td> |
| <td>String</td> |
| <td> |
| The name of the Marker to compare. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>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 class="b"> |
| <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> |
| |
| </table> |
| <p> |
| A sample configuration that only allows the event to be written by the appender if the Marker matches: |
| |
| </p><div class="source"><pre class="prettyprint"><?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> |
| </pre></div> |
| |
| </div> |
| <a name="RegexFilter"></a> |
| <div class="section"><h3>RegexFilter<a name="RegexFilter"></a></h3> |
| <p> |
| The RegexFilter allows the formatted or unformatted message to be compared against a regular expression. |
| </p> |
| <table class="table table-striped" border="1" width="100%"><caption align="top">Regex Filter Parameters</caption> |
| <tr class="a"> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr class="b"> |
| <td>regex</td> |
| <td>String</td> |
| <td> |
| The regular expression. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>useRawMsg</td> |
| <td>boolean</td> |
| <td>If true the unformatted message will be used, otherwise the formatted message will be used. The |
| default value is false.</td> |
| </tr> |
| <tr class="b"> |
| <td>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 class="a"> |
| <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> |
| |
| </table> |
| <p> |
| A sample configuration that only allows the event to be written by the appender if it contains the word "test": |
| |
| </p><div class="source"><pre class="prettyprint"><?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> |
| </pre></div> |
| |
| </div> |
| <a name="StructuredDataFilter"></a> |
| <div class="section"><h3>StructuredDataFilter<a name="StructuredDataFilter"></a></h3> |
| <p> |
| The StructuredDataFilter is a MapFilter that also allows filtering on the event id, type and message. |
| </p> |
| <table class="table table-striped" border="1" width="100%"><caption align="top">StructuredData Filter Parameters</caption> |
| <tr class="a"> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr class="b"> |
| <td>keyValuePair</td> |
| <td>KeyValuePair[]</td> |
| <td>One or more KeyValuePair elements that define the key in the map and the value to match on. "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 class="a"> |
| <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 class="b"> |
| <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 class="a"> |
| <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> |
| |
| </table> |
| <p> |
| As in this configuration, the StructuredDataFilter can be used to log particular events: |
| |
| </p><div class="source"><pre class="prettyprint"><?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> |
| </pre></div> |
| |
| </div> |
| <a name="ThreadContextMapFilter"></a> |
| <div class="section"><h3>ThreadContextMapFilter<a name="ThreadContextMapFilter"></a></h3> |
| <p> |
| The ThreadContextMapFilter allows filtering against data elements that are in the ThreadContext Map. |
| </p> |
| <table class="table table-striped" border="1" width="100%"><caption align="top">ThreadContext Map Filter Parameters</caption> |
| <tr class="a"> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr class="b"> |
| <td>keyValuePair</td> |
| <td>KeyValuePair[]</td> |
| <td>One or more KeyValuePair elements that define the key in the map and the value to match on.</td> |
| </tr> |
| <tr class="a"> |
| <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 class="b"> |
| <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 class="a"> |
| <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> |
| |
| </table> |
| <p> |
| A configuration containing the ThreadContextMapFilter might look like: |
| |
| </p><div class="source"><pre class="prettyprint"><?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> |
| </pre></div> |
| |
| </div> |
| <a name="ThresholdFilter"></a> |
| <div class="section"><h3>ThresholdFilter<a name="ThresholdFilter"></a></h3> |
| <p> |
| This filter returns the onMatch result if the level in the LogEvent is the same or more specific |
| than the configured level and the onMismatch value otherwise. For example, if the ThresholdFilter |
| is configured with Level ERROR and the LogEvent contains Level DEBUG then the onMismatch value will |
| be returned since ERROR events are more specific than DEBUG. |
| </p> |
| <table class="table table-striped" border="1" width="100%"><caption align="top">Threshold Filter Parameters</caption> |
| <tr class="a"> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr class="b"> |
| <td>level</td> |
| <td>String</td> |
| <td> |
| A valid Level name to match on. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>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 class="b"> |
| <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> |
| |
| </table> |
| <p> |
| A sample configuration that only allows the event to be written by the appender if the level matches: |
| |
| </p><div class="source"><pre class="prettyprint"><?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> |
| </pre></div> |
| |
| </div> |
| <a name="TimeFilter"></a> |
| <div class="section"><h3>TimeFilter<a name="TimeFilter"></a></h3> |
| <p> |
| The time filter can be used to restrict filter to only a certain portion of the day. |
| </p> |
| <table class="table table-striped" border="1" width="100%"><caption align="top">Time Filter Parameters</caption> |
| <tr class="a"> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr class="b"> |
| <td>start</td> |
| <td>String</td> |
| <td> |
| A time in HH:mm:ss format. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>end</td> |
| <td>String</td> |
| <td> |
| A time in HH:mm:ss format. Specifying an end time less than the start time will result in no |
| log entries being written. |
| </td> |
| </tr> |
| <tr class="b"> |
| <td>timezone</td> |
| <td>String</td> |
| <td> |
| The timezone to use when comparing to the event timestamp. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>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 class="b"> |
| <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> |
| |
| </table> |
| <p> |
| A sample configuration that only allows the event to be written by the appender from 5:00 to 5:30 am each |
| day using the default timezone: |
| |
| </p><div class="source"><pre class="prettyprint"><?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> |
| </pre></div> |
| |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| |
| <hr/> |
| |
| <footer> |
| <div class="container-fluid"> |
| <div class="row footer">Copyright © 1999-2012 <a href="http://www.apache.org">Apache Software Foundation</a>. All Rights Reserved.</br /> |
| Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</div> |
| </div> |
| </footer> |
| </body> |
| </html> |
