| <!DOCTYPE html> |
| |
| |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.11.1 from target/generated-sources/site/xdoc/manual/filters.xml at 2024-03-06 |
| | Rendered using Apache Maven Fluido Skin 1.11.2 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> |
| <meta name="author" content="Ralph Goers" /> |
| <title>Log4j – Log4j Filters</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.11.2.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script src="../js/apache-maven-fluido-1.11.2.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="../../.." id="bannerLeft"><img src="../images/ls-logo.jpg" alt="" style="" /></a></div> |
| <div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/logo.png" alt="" style="" /></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2024-03-06<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 2.23.1</li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://github.com/apache/logging-log4j2" class="externalLink" title="GitHub">GitHub</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="../../../" title="Logging Services">Logging Services</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://www.apache.org/" class="externalLink" title="Apache">Apache</a></li> |
| <li class="pull-right"><a href="https://cwiki.apache.org/confluence/display/LOGGING/Log4j" class="externalLink" title="Logging Wiki">Logging Wiki</a></li> |
| </ul> |
| </div> |
| </header> |
| <div class="row-fluid"> |
| <header id="leftColumn" class="span2"> |
| <nav class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/home.png" alt="Apache Log4j™ 2" style="border: 0;" /> Apache Log4j™ 2</li> |
| <li><a href="../index.html" title="About"><span class="none"></span>About</a></li> |
| <li><a href="../download.html" title="Download"><span class="none"></span>Download</a></li> |
| <li><a href="../support.html" title="Support"><span class="none"></span>Support</a></li> |
| <li><a href="../maven-artifacts.html" title="Maven, Ivy, Gradle Artifacts"><span class="icon-chevron-right"></span>Maven, Ivy, Gradle Artifacts</a></li> |
| <li><a href="../release-notes.html" title="Release Notes"><span class="none"></span>Release Notes</a></li> |
| <li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a></li> |
| <li><a href="../performance.html" title="Performance"><span class="icon-chevron-right"></span>Performance</a></li> |
| <li><a href="../articles.html" title="Articles and Tutorials"><span class="none"></span>Articles and Tutorials</a></li> |
| <li><a href="../security.html" title="Security"><span class="icon-chevron-right"></span>Security</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/book.png" alt="Manual" style="border: 0;" /> Manual</li> |
| <li><a href="../manual/index.html" title="Introduction"><span class="none"></span>Introduction</a></li> |
| <li><a href="../manual/architecture.html" title="Architecture"><span class="none"></span>Architecture</a></li> |
| <li><a href="../manual/api-separation.html" title="API Separation"><span class="none"></span>API Separation</a></li> |
| <li><a href="../manual/migration.html" title="Log4j 1.x Migration"><span class="icon-chevron-right"></span>Log4j 1.x Migration</a></li> |
| <li><a href="../manual/api.html" title="Java API"><span class="icon-chevron-right"></span>Java API</a></li> |
| <li><a href="../../kotlin" title="Kotlin API"><span class="none"></span>Kotlin API</a></li> |
| <li><a href="../../scala" title="Scala API"><span class="none"></span>Scala API</a></li> |
| <li><a href="../manual/configuration.html" title="Configuration"><span class="icon-chevron-right"></span>Configuration</a></li> |
| <li><a href="../manual/usage.html" title="Usage"><span class="icon-chevron-right"></span>Usage</a></li> |
| <li><a href="../manual/webapp.html" title="Web Applications and JSPs"><span class="icon-chevron-right"></span>Web Applications and JSPs</a></li> |
| <li><a href="../manual/lookups.html" title="Lookups"><span class="icon-chevron-right"></span>Lookups</a></li> |
| <li><a href="../manual/appenders.html" title="Appenders"><span class="icon-chevron-right"></span>Appenders</a></li> |
| <li><a href="../manual/layouts.html" title="Layouts"><span class="icon-chevron-right"></span>Layouts</a></li> |
| <li class="active"><a><span class="icon-chevron-down"></span>Filters</a> |
| <ul class="nav nav-list"> |
| <li><a href="../manual/filters.html#BurstFilter" title="Burst"><span class="none"></span>Burst</a></li> |
| <li><a href="../manual/filters.html#CompositeFilter" title="Composite Filter"><span class="none"></span>Composite Filter</a></li> |
| <li><a href="../manual/filters.html#DynamicThresholdFilter" title="Dynamic Threshold"><span class="none"></span>Dynamic Threshold</a></li> |
| <li><a href="../manual/filters.html#MapFilter" title="Map"><span class="none"></span>Map</a></li> |
| <li><a href="../manual/filters.html#MarkerFilter" title="Marker"><span class="none"></span>Marker</a></li> |
| <li><a href="../manual/filters.html#RegexFilter" title="Regex"><span class="none"></span>Regex</a></li> |
| <li><a href="../manual/filters.html#Script" title="Script"><span class="none"></span>Script</a></li> |
| <li><a href="../manual/filters.html#StructuredDataFilter" title="Structured Data"><span class="none"></span>Structured Data</a></li> |
| <li><a href="../manual/filters.html#ThreadContextMapFilter" title="Thread Context Map"><span class="none"></span>Thread Context Map</a></li> |
| <li><a href="../manual/filters.html#ThresholdFilter" title="Threshold"><span class="none"></span>Threshold</a></li> |
| <li><a href="../manual/filters.html#TimeFilter" title="Time"><span class="none"></span>Time</a></li> |
| </ul></li> |
| <li><a href="../manual/async.html" title="Async Loggers"><span class="icon-chevron-right"></span>Async Loggers</a></li> |
| <li><a href="../manual/garbagefree.html" title="Garbage-free Logging"><span class="icon-chevron-right"></span>Garbage-free Logging</a></li> |
| <li><a href="../manual/jmx.html" title="JMX"><span class="none"></span>JMX</a></li> |
| <li><a href="../manual/logsep.html" title="Logging Separation"><span class="none"></span>Logging Separation</a></li> |
| <li><a href="../manual/extending.html" title="Extending Log4j"><span class="icon-chevron-right"></span>Extending Log4j</a></li> |
| <li><a href="../manual/plugins.html" title="Plugins"><span class="icon-chevron-right"></span>Plugins</a></li> |
| <li><a href="../manual/customconfig.html" title="Programmatic Log4j Configuration"><span class="icon-chevron-right"></span>Programmatic Log4j Configuration</a></li> |
| <li><a href="../manual/customloglevels.html" title="Custom Log Levels"><span class="icon-chevron-right"></span>Custom Log Levels</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/pencil.png" alt="For Contributors" style="border: 0;" /> For Contributors</li> |
| <li><a href="../guidelines.html" title="Guidelines"><span class="none"></span>Guidelines</a></li> |
| <li><a href="../javastyle.html" title="Style Guide"><span class="none"></span>Style Guide</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/cog.png" alt="Components" style="border: 0;" /> Components</li> |
| <li><a href="../log4j-api.html" title="API"><span class="none"></span>API</a></li> |
| <li><a href="../log4j-jcl.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li> |
| <li><a href="../log4j-1.2-api.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li> |
| <li><a href="../log4j-slf4j-impl.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li> |
| <li><a href="../log4j-jul.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li> |
| <li><a href="../log4j-jpl.html" title="JDK Platform Logger"><span class="none"></span>JDK Platform Logger</a></li> |
| <li><a href="../log4j-to-slf4j.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li> |
| <li><a href="../log4j-flume-ng.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li> |
| <li><a href="../log4j-taglib.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li> |
| <li><a href="../log4j-jmx-gui.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li> |
| <li><a href="../log4j-web.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li> |
| <li><a href="../log4j-jakarta-web.html" title="Log4j Jakarta Web Application Support"><span class="none"></span>Log4j Jakarta Web Application Support</a></li> |
| <li><a href="../log4j-appserver.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li> |
| <li><a href="../log4j-couchdb.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li> |
| <li><a href="../log4j-mongodb3.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li> |
| <li><a href="../log4j-mongodb4.html" title="Log4j MongoDB4 appender"><span class="none"></span>Log4j MongoDB4 appender</a></li> |
| <li><a href="../log4j-cassandra.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li> |
| <li><a href="../log4j-iostreams.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li> |
| <li><a href="../log4j-docker.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li> |
| <li><a href="../log4j-kubernetes.html" title="Log4j Kubernetes Support"><span class="none"></span>Log4j Kubernetes Support</a></li> |
| <li><a href="../log4j-spring-boot.html" title="Log4j Spring Boot"><span class="none"></span>Log4j Spring Boot</a></li> |
| <li><a href="../log4j-spring-cloud-config-client.html" title="Log4j Spring Cloud Config Client"><span class="none"></span>Log4j Spring Cloud Config Client</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/tag.png" alt="Related Projects" style="border: 0;" /> Related Projects</li> |
| <li><a href="../../../chainsaw/2.x/index.html" title="Chainsaw"><span class="none"></span>Chainsaw</a></li> |
| <li><a href="../../../log4cxx/latest_stable/index.html" title="Log4Cxx"><span class="none"></span>Log4Cxx</a></li> |
| <li><a href="../../../log4j-audit/latest/index.html" title="Log4j Audit"><span class="none"></span>Log4j Audit</a></li> |
| <li><a href="../../kotlin" title="Log4j Kotlin"><span class="none"></span>Log4j Kotlin</a></li> |
| <li><a href="../../scala" title="Log4j Scala"><span class="none"></span>Log4j Scala</a></li> |
| <li><a href="../../transform" title="Log4j Transform"><span class="none"></span>Log4j Transform</a></li> |
| <li><a href="../../../log4net/index.html" title="Log4Net"><span class="none"></span>Log4Net</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/link.png" alt="Legacy Sites" style="border: 0;" /> Legacy Sites</li> |
| <li><a href="../../log4j-2.12.4/" title="Log4j 2.12.4 - Java 7"><span class="none"></span>Log4j 2.12.4 - Java 7</a></li> |
| <li><a href="../../log4j-2.3.2/" title="Log4j 2.3.2 - Java 6"><span class="none"></span>Log4j 2.3.2 - Java 6</a></li> |
| <li><a href="../../1.2/" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/info.png" alt="Project Information" style="border: 0;" /> Project Information</li> |
| <li><a href="../team.html" title="Project Team"><span class="none"></span>Project Team</a></li> |
| <li><a href="https://www.apache.org/licenses/LICENSE-2.0" class="externalLink" title="Project License"><span class="none"></span>Project License</a></li> |
| <li><a href="https://github.com/apache/logging-log4j2" class="externalLink" title="Source Repository"><span class="none"></span>Source Repository</a></li> |
| <li><a href="../runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li> |
| <li><a href="../javadoc.html" title="Javadoc"><span class="none"></span>Javadoc</a></li> |
| <li><a href="../thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <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="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </header> |
| <main id="bodyColumn" class="span10" > |
| |
| |
| <section> |
| <h2><a name="Filters"></a>Filters</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 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 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> |
| <section> |
| <h3><a name="BurstFilter"></a>BurstFilter</h3> |
| |
| <p> |
| The BurstFilter provides a mechanism to control the rate at which LogEvents are processed by |
| silently discarding events after the maximum limit has been reached. |
| </p> |
| |
| <table border="0" class="table table-striped"><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 align="left">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 class="a"> |
| |
| <td align="left">rate</td> |
| |
| <td>float</td> |
| |
| <td>The average number of events per second to allow.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">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 align="left">onMatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">onMismatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is |
| DENY.</td> |
| </tr> |
| </table> |
| |
| <p> |
| A configuration containing the BurstFilter might look like: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></div> |
| </section> |
| <a name="CompositeFilter"></a> |
| <section> |
| <h3><a name="CompositeFilter"></a>CompositeFilter</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> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></div> |
| </section> |
| <a name="DynamicThresholdFilter"></a> |
| <section> |
| <h3><a name="DynamicThresholdFilter"></a>DynamicThresholdFilter</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. If the log event does not contain the specified ThreadContext item |
| NEUTRAL will be returned. |
| </p> |
| |
| <table border="0" class="table table-striped"><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 align="left">key</td> |
| |
| <td>String</td> |
| |
| <td>The name of the item in the ThreadContext Map to compare.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">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 class="b"> |
| |
| <td align="left">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="a"> |
| |
| <td align="left">onMatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">onMismatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is |
| DENY.</td> |
| </tr> |
| </table> |
| |
| <p> |
| Here is a sample configuration containing the DynamicThresholdFilter: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" > |
| <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></div> |
| </section> |
| |
| <a name="LevelRangeFilter"></a> |
| <section> |
| <h3><a name="LevelRangeFilter"></a>LevelRangeFilter</h3> |
| |
| <p> |
| <code>LevelRangeFilter</code> allows filtering against a level range, where levels get compared by their associated integral values; <code>OFF</code> has an integral value of 0, <code>FATAL</code> 100, <code>ERROR</code> 200, and so on. |
| </p> |
| |
| <table border="0" class="table table-striped"><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 align="left"><code>minLevel</code></td> |
| |
| <td><code>Level</code></td> |
| |
| <td>the minimum level threshold (defaults to <code>OFF</code>, which has an integral value of 0)</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><code>maxLevel</code></td> |
| |
| <td><code>Level</code></td> |
| |
| <td>the maximum level threshold (defaults to <code>ALL</code>, which has an integral value of <code>Integer.MAX_VALUE</code>)</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><code>onMatch</code></td> |
| |
| <td><code>Filter.Result</code></td> |
| |
| <td>the result to return on a match, where allowed values are <code>ACCEPT</code>, <code>DENY</code> or <code>NEUTRAL</code> (default)</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><code>onMismatch</code></td> |
| |
| <td><code>Filter.Result</code></td> |
| |
| <td>the result to return on a mismatch, where allowed values are <code>ACCEPT</code>, <code>DENY</code> (default) or <code>NEUTRAL</code></td> |
| </tr> |
| </table> |
| |
| <p> |
| In the following example configuration, a <code>LevelRangeFilter</code> is configured with <code>maxLevel</code> set to <code>INFO</code>. |
| The filter will return <code>onMismatch</code> result (i.e., <code>DENY</code>, the default) for log events of level with higher integral values than <code>INFO</code>; i.e., <code>DEBUG</code>, <code>TRACE</code>, etc. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="WARN" name="MyApp"> |
| <Appenders> |
| <Console name="STDOUT"> |
| <LevelRangeFilter maxLevel="INFO"/> |
| <PatternLayout pattern="%d %p %c{1.} [%t] %m%n"/> |
| </Console> |
| </Appenders> |
| <Loggers> |
| <Root level="ERROR"> |
| <AppenderRef ref="STDOUT"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section> |
| |
| <a name="MapFilter"></a> |
| <section> |
| <h3><a name="MapFilter"></a>MapFilter</h3> |
| |
| <p> |
| The MapFilter allows filtering against data elements that are in a MapMessage. |
| </p> |
| |
| <table border="0" class="table table-striped"><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 align="left">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 class="a"> |
| |
| <td align="left">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 align="left">onMatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">onMismatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is |
| DENY.</td> |
| </tr> |
| </table> |
| |
| <p> |
| As in this configuration, the MapFilter can be used to log particular events: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></div> |
| |
| <p> |
| This sample configuration will exhibit the same behavior as the preceding example since the only |
| logger configured is the root. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></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> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></div> |
| </section> |
| <a name="MarkerFilter"></a> |
| <section> |
| <h3><a name="MarkerFilter"></a>MarkerFilter</h3> |
| |
| <p> |
| The MarkerFilter compares the configured Marker value against the Marker that is included |
| in the LogEvent. A match occurs when the Marker name matches either the Log Event's Marker |
| or one of its parents. |
| </p> |
| |
| <table border="0" class="table table-striped"><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 align="left">marker</td> |
| |
| <td>String</td> |
| |
| <td> |
| The name of the Marker to compare. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">onMatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">onMismatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is |
| DENY.</td> |
| </tr> |
| </table> |
| |
| <p> |
| A sample configuration that only allows the event to be written by the appender if the Marker matches: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></div> |
| </section> |
| <a name="MutableThreadContextMapFilter"></a> |
| <section> |
| <h3><a name="MutableThreadContextMapFilter_.28or_MutableContextMapFilter.29"></a>MutableThreadContextMapFilter (or MutableContextMapFilter)</h3> |
| |
| <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 border="0" class="table table-striped"><caption align="top">Mutable Context Map Filter Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">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 class="a"> |
| |
| <td align="left">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 class="b"> |
| |
| <td align="left">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="a"> |
| |
| <td align="left">onMatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">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> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></div> |
| |
| <p> |
| The configuration file supplied to the filter should look similar to: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| { |
| "configs": { |
| "loginId": ["rgoers@apache.org", "logging@apache.org"], |
| "accountNumber": ["30510263"] |
| } |
| } |
| </pre></div> |
| </section> |
| <a name="NoMarkerFilter"></a> |
| <section> |
| <h3><a name="NoMarkerFilter"></a>NoMarkerFilter</h3> |
| |
| <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 border="0" class="table table-striped"><caption align="top">No Marker Filter Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">onMatch</td> |
| |
| <td>string</td> |
| |
| <td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is |
| NEUTRAL.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">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> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></div> |
| </section> |
| <a name="RegexFilter"></a> |
| <section> |
| <h3><a name="RegexFilter"></a>RegexFilter</h3> |
| |
| <p> |
| The RegexFilter allows the formatted or unformatted message to be compared against a regular expression. |
| </p> |
| |
| <table border="0" class="table table-striped"><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 align="left">regex</td> |
| |
| <td>String</td> |
| |
| <td> |
| The regular expression. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">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 align="left">onMatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">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> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></div> |
| </section> |
| <a name="Script"></a> |
| <section> |
| <h3><a name="Script"></a>Script</h3> |
| |
| <p> |
| The ScriptFilter executes a script that returns true or false. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">Script Filter Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">script</td> |
| |
| <td>Script, ScriptFile or ScriptRef</td> |
| |
| <td>The Script element that specifies the logic to be executed. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">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 class="b"> |
| |
| <td align="left">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 border="0" class="table table-striped"><caption align="top">Script Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">configuration</td> |
| |
| <td>Configuration</td> |
| |
| <td>The Configuration that owns this ScriptFilter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">level</td> |
| |
| <td>Level</td> |
| |
| <td>The logging Level associated with the event. Only present when configured as a global filter.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">loggerName</td> |
| |
| <td>String</td> |
| |
| <td>The name of the logger. Only present when configured as a global filter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">logEvent</td> |
| |
| <td>LogEvent</td> |
| |
| <td>The LogEvent being processed. Not present when configured as a global filter.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">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 class="a"> |
| |
| <td align="left">message</td> |
| |
| <td>Message</td> |
| |
| <td>The Message associated with the logging call. Only present when configured as a global filter.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">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 class="a"> |
| |
| <td align="left">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 class="b"> |
| |
| <td align="left">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 |
| <code>Script</code> element can be used to embed script code directly in the configuration. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?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></div> |
| </section> |
| <a name="StructuredDataFilter"></a> |
| <section> |
| <h3><a name="StructuredDataFilter"></a>StructuredDataFilter</h3> |
| |
| <p> |
| The StructuredDataFilter is a MapFilter that also allows filtering on the event id, type and message. |
| </p> |
| |
| <table border="0" class="table table-striped"><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 align="left">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 class="a"> |
| |
| <td align="left">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 align="left">onMatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">onMismatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is |
| DENY.</td> |
| </tr> |
| </table> |
| |
| <p> |
| As in this configuration, the StructuredDataFilter can be used to log particular events: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></div> |
| </section> |
| <a name="ThreadContextMapFilter"></a> |
| <section> |
| <h3><a name="ThreadContextMapFilter_.28or_ContextMapFilter.29"></a>ThreadContextMapFilter (or ContextMapFilter)</h3> |
| |
| <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 border="0" class="table table-striped"><caption align="top">Context Map Filter Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">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 class="a"> |
| |
| <td align="left">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 align="left">onMatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">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> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></div> |
| |
| <p> |
| The ContextMapFilter can also be applied to a logger for filtering: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></div> |
| </section> |
| <a name="ThresholdFilter"></a> |
| <section> |
| <h3><a name="ThresholdFilter"></a>ThresholdFilter</h3> |
| |
| <p> |
| This filter returns the onMatch result if the level in the LogEvent is the same or more specific |
| than the configured level and the onMismatch value otherwise. For example, if the ThresholdFilter |
| is configured with Level ERROR and the LogEvent contains Level DEBUG then the onMismatch value will |
| be returned since ERROR events are more specific than DEBUG. |
| </p> |
| |
| <table border="0" class="table table-striped"><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 align="left">level</td> |
| |
| <td>String</td> |
| |
| <td> |
| A valid Level name to match on. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">onMatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">onMismatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is |
| DENY.</td> |
| </tr> |
| </table> |
| |
| <p> |
| A sample configuration that only allows the event to be written by the appender if the level matches: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></div> |
| </section> |
| <a name="TimeFilter"></a> |
| <section> |
| <h3><a name="TimeFilter"></a>TimeFilter</h3> |
| |
| <p> |
| The time filter can be used to restrict filter to only a certain portion of the day. |
| </p> |
| |
| <table border="0" class="table table-striped"><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 align="left">start</td> |
| |
| <td>String</td> |
| |
| <td> |
| A time in HH:mm:ss format. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">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 align="left">timezone</td> |
| |
| <td>String</td> |
| |
| <td> |
| The timezone to use when comparing to the event timestamp. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">onMatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter matches. May be ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">onMismatch</td> |
| |
| <td>String</td> |
| |
| <td>Action to take when the filter does not match. May be ACCEPT, DENY or NEUTRAL. The default value is |
| DENY.</td> |
| </tr> |
| </table> |
| |
| <p> |
| A sample configuration that only allows the event to be written by the appender from 5:00 to 5:30 am each |
| day using the default timezone: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <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></div> |
| </section> |
| </section> |
| |
| |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p align="center">Copyright © 1999-2024 <a class="external" href="https://www.apache.org">The 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.</p> |
| </div> |
| </div> |
| </footer> |
| <script> |
| if(anchors) { |
| anchors.add(); |
| } |
| </script> |
| </body> |
| </html> |