| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <document> |
| <properties> |
| <title>Log4j 2 Appenders</title> |
| <author email="rgoers@apache.org">Ralph Goers</author> |
| </properties> |
| |
| <body> |
| <section name="Appenders"> |
| <p> |
| Appenders are the component responsible for delivering LogEvents to their destination. Every Appender must |
| implement the <a href="../log4j2-core/apidocs/org/apache/logging/log4j/core/Appender.html">Appender</a> |
| interface. Most Appenders will extend |
| <a href="../log4j2-core/apidocs/org/apache/logging/log4j/core/appender/AppenderBase.html">AppenderBase</a> |
| which adds <a href="../log4j2-core/apidocs/org/apache/logging/log4j/core/Lifecycle.html">Lifecycle</a> |
| and <a href="../log4j2-core/apidocs/org/apache/logging/log4j/core/filter/Filterable">Filterable</a> |
| support. Lifecycle allows components to finish initialization after configuration has completed and to |
| perform cleanup during shutdown. Filterable allows the component to have Filters attached to it which are |
| evaluated during event processing. |
| </p> |
| <p> |
| Appenders usually are only responsible for writing the event data to the target destination. In most cases |
| they delegate responsibility for formatting the event to a <a href="../layouts.html">layout</a>. Some |
| appenders wrap other appenders so that they can modify the LogEvent, handle a failure in an Appender, |
| route the event to a subordinate Appender based on advanced Filter criteria or provide similar functionality |
| that does not directly format the event for viewing. |
| </p> |
| <p> |
| Appenders always have a name so that they can be referenced from Loggers. |
| </p> |
| <a name="ConsoleAppender"/> |
| <subsection name="ConsoleAppender"> |
| <p> |
| As one might expect, the ConsoleAppender writes its output to either System.err or System.out with System.err |
| being the default target. A Layout must be provided to format the LogEvent. |
| </p> |
| <table border="1" width="100%"> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>filter</td> |
| <td>Filter</td> |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| <tr> |
| <td>layout</td> |
| <td>Layout</td> |
| <td>The Layout to use to format the LogEvent. If no layout is supplied the default pattern layout |
| of "%m%n" will be used.</td> |
| </tr> |
| <tr> |
| <td>name</td> |
| <td>String</td> |
| <td>The name of the Appender.</td> |
| </tr> |
| <tr> |
| <td>suppressExceptions</td> |
| <td>boolean</td> |
| <td>The default is true, causing exceptions to be internally logged and then ignored. When set to |
| false exceptions will be percolated to the caller.</td> |
| </tr> |
| <tr> |
| <td>target</td> |
| <td>String</td> |
| <td>Either "SYSTEM_OUT" or "SYSTEM_ERR". The default is "SYSTEM_ERR".</td> |
| </tr> |
| <caption align="top">ConsoleAppender Parameters</caption> |
| </table> |
| <p> |
| A typical Console configuration might look like: |
| |
| <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> |
| <configuration status="warn" name="MyApp" packages=""> |
| <appenders> |
| <Console name="STDOUT" target="SYSTEM_OUT"> |
| <PatternLayout pattern="%m%n"/> |
| </Console> |
| </appenders> |
| <loggers> |
| <root level="error"> |
| <appender-ref ref="STDOUT"/> |
| </root> |
| </loggers> |
| </configuration> |
| ]]></source> |
| </p> |
| </subsection> |
| <a name="FailoverAppender"/> |
| <subsection name="FailoverAppender"> |
| <p>The FailoverAppender wraps a set of appenders. If the primary Appender fails the secondary appenders will be |
| tried in order until one succeeds or there are no more secondaries to try.</p> |
| <table border="1" width="100%"> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>filter</td> |
| <td>Filter</td> |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| <tr> |
| <td>primary</td> |
| <td>String</td> |
| <td>The name of the primary Appender to use.</td> |
| </tr> |
| <tr> |
| <td>failovers</td> |
| <td>String[]</td> |
| <td>The names of the secondary Appenders to use.</td> |
| </tr> |
| |
| <tr> |
| <td>name</td> |
| <td>String</td> |
| <td>The name of the Appender.</td> |
| </tr> |
| <tr> |
| <td>suppressExceptions</td> |
| <td>boolean</td> |
| <td>The default is true, causing exceptions to be internally logged and then ignored. When set to |
| false exceptions will be percolated to the caller.</td> |
| </tr> |
| <tr> |
| <td>target</td> |
| <td>String</td> |
| <td>Either "SYSTEM_OUT" or "SYSTEM_ERR". The default is "SYSTEM_ERR".</td> |
| </tr> |
| <caption align="top">FailoverAppender Parameters</caption> |
| </table> |
| <p> |
| A Failover configuration might look like: |
| |
| <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> |
| <configuration status="warn" name="MyApp" packages=""> |
| <appenders> |
| <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz"> |
| <PatternLayout> |
| <pattern>%d %p %C{1.} [%t] %m%n</pattern> |
| </PatternLayout> |
| <TimeBasedTriggeringPolicy /> |
| </RollingFile> |
| <Console name="STDOUT" target="SYSTEM_OUT"> |
| <PatternLayout pattern="%m%n"/> |
| </Console> |
| <Failover name="Failover" primary="RollingFile" suppressExceptions="false"> |
| <Failovers> |
| <appender-ref ref="Console"/> |
| </Failovers> |
| </Failover> |
| </appenders> |
| <loggers> |
| <root level="error"> |
| <appender-ref ref="Failover"/> |
| </root> |
| </loggers> |
| </configuration> |
| ]]></source> |
| </p> |
| </subsection> |
| <a name="FileAppender"/> |
| <subsection name="FileAppender"> |
| <p>The FileAppender is an OutputStreamAppender that writes to the File named in the fileName parameter. The |
| FileAppender uses a FileManager (which extends OutputStreamManager) to actually perform the file I/O. While |
| FileAppenders from different Configurations cannot be shared, the FileManagers can be if the Manager is |
| accessible. For example, two webapps in a servlet container can have their own configuration and safely |
| write to the same file if Log4J is in a ClassLoader that is common to both of them.</p> |
| <table border="1" width="100%"> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>append</td> |
| <td>boolean</td> |
| <td>When true - the default, records will be appended to the end of the file. When set to false, |
| the file will be cleared before new reocrds are written.</td> |
| </tr> |
| <tr> |
| <td>bufferedIO</td> |
| <td>boolean</td> |
| <td>When true - the default, records will be written to a buffer and the data will be written to |
| disk when the buffer is full or, if immediateFlush is set, when the record is written. |
| File locking cannot be used with bufferedIO. Performance tests have shown that using buffered I/O |
| significantly improves performance, even if immediateFlush is enabled.</td> |
| </tr> |
| <tr> |
| <td>filter</td> |
| <td>Filter</td> |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| <tr> |
| <td>fileName</td> |
| <td>String</td> |
| <td>The name of the file to write to. If the file, or any of its parent directories, do not exist, |
| they will be created.</td> |
| </tr> |
| <tr> |
| <td>immediateFlush</td> |
| <td>boolean</td> |
| <td>When set to true, each write will be followed by a flush. This will guarantee the data is written |
| to disk but could impact performance.</td> |
| </tr> |
| <tr> |
| <td>layout</td> |
| <td>Layout</td> |
| <td>The Layout to use to format the LogEvent</td> |
| </tr> |
| <tr> |
| <td>locking</td> |
| <td>boolean</td> |
| <td>When set to true, I/O operations will occur only while the file lock is held allowing FileAppenders |
| in multiple JVMs and potentially multiple hosts to write to the same file simultaneously. This |
| will significantly impact performance so should be used carefully. Furthermore, on many systems |
| the file lock is "advisory" meaning that other applications can perform operations on the file |
| without acquiring a lock. The default value is false.</td> |
| </tr> |
| |
| <tr> |
| <td>name</td> |
| <td>String</td> |
| <td>The name of the Appender.</td> |
| </tr> |
| <tr> |
| <td>suppressExceptions</td> |
| <td>boolean</td> |
| <td>The default is true, causing exceptions to be internally logged and then ignored. When set to |
| false exceptions will be percolated to the caller.</td> |
| </tr> |
| <caption align="top">FileAppender Parameters</caption> |
| </table> |
| <p> |
| Here is a sample File configuration: |
| |
| <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> |
| <configuration status="warn" name="MyApp" packages=""> |
| <appenders> |
| <File name="MyFile" fileName="logs/app.log"> |
| <PatternLayout> |
| <pattern>%d %p %C{1.} [%t] %m%n</pattern> |
| </PatternLayout> |
| </File> |
| </appenders> |
| <loggers> |
| <root level="error"> |
| <appender-ref ref="MyFile"/> |
| </root> |
| </loggers> |
| </configuration> |
| ]]></source> |
| </p> |
| </subsection> |
| <a name="FlumeAvroAppender"/> |
| <subsection name="FlumeAvroAppender"> |
| <p><i>This is an optional component supplied in a separate jar.</i></p> |
| <p><a href="http://incubator.apache.org/projects/flume.html">Apache Flume</a> is a distributed, reliable, |
| and available system for efficiently collecting, aggregating, and moving large amounts of log data |
| from many different sources to a centralized data store. The FlumeAppender takes LogEvents and sends |
| them to a Flume agent as serialized Avro events for consumption.</p> |
| <p> |
| There are two versions of the Flume Appender available. The first is for "Flume OG", the original |
| version of Flume before it became an Apache project. The second is for "Flume NG", which is |
| maintained by the Apache Flume project. |
| </p> |
| <table border="1" width="100%"> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>agents</td> |
| <td>Agent[]</td> |
| <td>An array of Agents to which the logging events should be sent. If more than one agent is specified |
| the first Agent will be the primary and subsequent Agents will be used in the order specified as |
| secondaries should the primary Agent fail. Each Agent definition supplies the Agents host and port.</td> |
| </tr> |
| <tr> |
| <td>agentRetries</td> |
| <td>integer</td> |
| <td>The number of times the agent should be retried before failing to a secondary.</td> |
| </tr> |
| <tr> |
| <td>batchSize</td> |
| <td>integer</td> |
| <td>Specifies the number of events that should be sent as a batch. The default is 1. <i>This |
| parameter only applies to the Flume NG Appender.</i></td> |
| </tr> |
| <tr> |
| <td>compress</td> |
| <td>boolean</td> |
| <td>When set to true the message body will be compressed using gzip</td> |
| </tr> |
| <tr> |
| <td>filter</td> |
| <td>Filter</td> |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| <tr> |
| <td>eventPrefix</td> |
| <td>String</td> |
| <td>The character string to prepend to each event attribute in order to distinguish it from MDC attributes. |
| The default is an empty string.</td> |
| </tr> |
| <tr> |
| <td>flumeEventFactory</td> |
| <td>FlumeEventFactory</td> |
| <td>Factory that generates the Flume events from Log4j events. The default factory is the |
| FlumeAvroAppender itself.</td> |
| </tr> |
| <tr> |
| <td>layout</td> |
| <td>Layout</td> |
| <td>The Layout to use to format the LogEvent. If no layout is specified RFC5424Layout will be used.</td> |
| </tr> |
| <tr> |
| <td>mdcExcludes</td> |
| <td>String</td> |
| <td>A comma separated list of mdc keys that should be excluded from the FlumeEvent. This is mutually |
| exclusive with the mdcIncludes attribute.</td> |
| </tr> |
| <tr> |
| <td>mdcIncludes</td> |
| <td>String</td> |
| <td>A comma separated list of mdc keys that should be included in the FlumeEvent. Any keys in the MDC |
| not found in the list will be excluded. This option is mutually exclusive with the mdcExcludes |
| attribute.</td> |
| </tr> |
| <tr> |
| <td>mdcRequired</td> |
| <td>String</td> |
| <td>A comma separated list of mdc keys that must be present in the MDC. If a key is not present a |
| LoggingException will be thrown.</td> |
| </tr> |
| <tr> |
| <td>mdcPrefix</td> |
| <td>String</td> |
| <td>A string that should be prepended to each MDC key in order to distinguish it from event attributes. |
| The default string is "mdc:".</td> |
| </tr> |
| <tr> |
| <td>name</td> |
| <td>String</td> |
| <td>The name of the Appender.</td> |
| </tr> |
| <tr> |
| <td>reconnectionDelay</td> |
| <td>integer</td> |
| <td>The number of milliseconds the application should wait before trying again to connect to the |
| agent.</td> |
| </tr> |
| |
| <tr> |
| <td>suppressExceptions</td> |
| <td>boolean</td> |
| <td>The default is true, causing exceptions to be internally logged and then ignored. When set to |
| false exceptions will be percolated to the caller.</td> |
| </tr> |
| <caption align="top">FlumeAvroAppender Parameters</caption> |
| </table> |
| <p> |
| A sample FlumeAvroAppender configuration that is configured with a primary and a secondary agent, |
| compresses the body, and formats the body using the RFC5424Layout: |
| |
| <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> |
| <configuration status="warn" name="MyApp" packages=""> |
| <appenders> |
| <Flume name="eventLogger" suppressExceptions="false" compress="true"> |
| <Agent host="192.168.10.101" port="8800"/> |
| <Agent host="192.168.10.102" port="8800"/> |
| <RFC5424Layout enterpriseNumber="18060" includeMDC="true" appName="MyApp"/> |
| </Flume> |
| </appenders> |
| <loggers> |
| <root level="error"> |
| <appender-ref ref="eventLogger"/> |
| </root> |
| </loggers> |
| </configuration> |
| ]]></source> |
| </p> |
| </subsection> |
| <a name="JMSQueueAppender"/> |
| <subsection name="JMSQueueAppender"> |
| <p>The JMSQueueAppender sends the formatted log event to a JMS Queue.</p> |
| <table border="1" width="100%"> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>factoryBindingName</td> |
| <td>String</td> |
| <td>The name to locate in the Context that provides the |
| <a href="http://download.oracle.com/javaee/5/api/javax/jms/QueueConnectionFactory.html">QueueConnectionFactory</a>.</td> |
| </tr> |
| <tr> |
| <td>factoryName</td> |
| <td>String</td> |
| <td>The fully qualified class name that should be used to define the Initial Context Factory as |
| defined in <a href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#INITIAL_CONTEXT_FACTORY">INITIAL_CONTEXT_FACTORY</a>. |
| If no value is provided the |
| default InitialContextFactory will be used. If a factoryName is specified without a providerURL |
| a warning message will be logged as this is likely to cause problems.</td> |
| </tr> |
| <tr> |
| <td>filter</td> |
| <td>Filter</td> |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| <tr> |
| <td>layout</td> |
| <td>Layout</td> |
| <td>The Layout to use to format the LogEvent. If no layout is specified SerializedLayout will be used.</td> |
| </tr> |
| <tr> |
| <td>name</td> |
| <td>String</td> |
| <td>The name of the Appender.</td> |
| </tr> |
| <tr> |
| <td>password</td> |
| <td>String</td> |
| <td>The password to use to create the queue connection.</td> |
| </tr> |
| <tr> |
| <td>providerURL</td> |
| <td>String</td> |
| <td>The URL of the provider to use as defined by |
| <a href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#PROVIDER_URL">PROVIDER_URL</a>. |
| If this value is null the default system provider will be used.</td> |
| </tr> |
| <tr> |
| <td>queueBindingName</td> |
| <td>String</td> |
| <td>The name to use to locate the <a href="http://download.oracle.com/javaee/5/api/javax/jms/Queue.html">Queue</a>.</td> |
| </tr> |
| <tr> |
| <td>securityPrincipalName</td> |
| <td>String</td> |
| <td>The name of the identity of the Principal as specified by |
| <a href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#SECURITY_PRINCIPAL">SECURITY_PRINCIPAL</a>. |
| If a securityPrincipalName is specified without securityCredentials a warning message will be |
| logged as this is likely to cause problems.</td> |
| </tr> |
| <tr> |
| <td>securityCredentials</td> |
| <td>String</td> |
| <td>The security credentials for the principal as specified by |
| <a href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#SECURITY_CREDENTIALS">SECURITY_CREDENTIALS</a>.</td> |
| </tr> |
| <tr> |
| <td>suppressExceptions</td> |
| <td>boolean</td> |
| <td>The default is true, causing exceptions to be internally logged and then ignored. When set to |
| false exceptions will be percolated to the caller.</td> |
| </tr> |
| <tr> |
| <td>urlPkgPrefixes</td> |
| <td>String</td> |
| <td>A colon-separated list of package prefixes for the class name of the factory class that will create |
| a URL context factory as defined by |
| <a href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#URL_PKG_PREFIXES">URL_PKG_PREFIXES</a>.</td> |
| </tr> |
| <tr> |
| <td>userName</td> |
| <td>String</td> |
| <td>The user id used to create the queue connection.</td> |
| </tr> |
| <caption align="top">JMSQueueAppender Parameters</caption> |
| </table> |
| <p> |
| Here is a sample JMSQueueAppender configuration: |
| |
| <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> |
| <configuration status="warn" name="MyApp" packages=""> |
| <appenders> |
| <JMSQueue name="jmsQueue" queueBindingName="MyQueue" factoryBindingName="MyQueueConnectionFactory"/> |
| </appenders> |
| <loggers> |
| <root level="error"> |
| <appender-ref ref="jmsQueue"/> |
| </root> |
| </loggers> |
| </configuration> |
| ]]></source> |
| </p> |
| </subsection> |
| <a name="JMSTopicAppender"/> |
| <subsection name="JMSTopicAppender"> |
| <p>The JMSTopicAppender sends the formatted log event to a JMS Topic.</p> |
| <table border="1" width="100%"> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>factoryBindingName</td> |
| <td>String</td> |
| <td>The name to locate in the Context that provides the |
| <a href="http://download.oracle.com/javaee/5/api/javax/jms/TopicConnectionFactory.html">TopicConnectionFactory</a>.</td> |
| </tr> |
| <tr> |
| <td>factoryName</td> |
| <td>String</td> |
| <td>The fully qualified class name that should be used to define the Initial Context Factory as |
| defined in <a href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#INITIAL_CONTEXT_FACTORY">INITIAL_CONTEXT_FACTORY</a>. |
| If no value is provided the |
| default InitialContextFactory will be used. If a factoryName is specified without a providerURL |
| a warning message will be logged as this is likely to cause problems.</td> |
| </tr> |
| <tr> |
| <td>filter</td> |
| <td>Filter</td> |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| <tr> |
| <td>layout</td> |
| <td>Layout</td> |
| <td>The Layout to use to format the LogEvent. If no layout is specified SerializedLayout will be used.</td> |
| </tr> |
| <tr> |
| <td>name</td> |
| <td>String</td> |
| <td>The name of the Appender.</td> |
| </tr> |
| <tr> |
| <td>password</td> |
| <td>String</td> |
| <td>The password to use to create the queue connection.</td> |
| </tr> |
| <tr> |
| <td>providerURL</td> |
| <td>String</td> |
| <td>The URL of the provider to use as defined by |
| <a href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#PROVIDER_URL">PROVIDER_URL</a>. |
| If this value is null the default system provider will be used.</td> |
| </tr> |
| <tr> |
| <td>topicBindingName</td> |
| <td>String</td> |
| <td>The name to use to locate the |
| <a href="http://download.oracle.com/javaee/5/api/javax/jms/Topic.html">Topic</a>.</td> |
| </tr> |
| <tr> |
| <td>securityPrincipalName</td> |
| <td>String</td> |
| <td>The name of the identity of the Principal as specified by |
| <a href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#SECURITY_PRINCIPAL">SECURITY_PRINCIPAL</a>. |
| If a securityPrincipalName is specified without securityCredentials a warning message will be |
| logged as this is likely to cause problems.</td> |
| </tr> |
| <tr> |
| <td>securityCredentials</td> |
| <td>String</td> |
| <td>The security credentials for the principal as specified by |
| <a href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#SECURITY_CREDENTIALS">SECURITY_CREDENTIALS</a>.</td> |
| </tr> |
| <tr> |
| <td>suppressExceptions</td> |
| <td>boolean</td> |
| <td>The default is true, causing exceptions to be internally logged and then ignored. When set to |
| false exceptions will be percolated to the caller.</td> |
| </tr> |
| <tr> |
| <td>urlPkgPrefixes</td> |
| <td>String</td> |
| <td>A colon-separated list of package prefixes for the class name of the factory class that will create |
| a URL context factory as defined by |
| <a href="http://download.oracle.com/javase/6/docs/api/javax/naming/Context.html#URL_PKG_PREFIXES">URL_PKG_PREFIXES</a>.</td> |
| </tr> |
| <tr> |
| <td>userName</td> |
| <td>String</td> |
| <td>The user id used to create the queue connection.</td> |
| </tr> |
| <caption align="top">JMSTopicAppender Parameters</caption> |
| </table> |
| <p> |
| Here is a sample JMSTopicAppender configuration: |
| |
| <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> |
| <configuration status="warn" name="MyApp" packages=""> |
| <appenders> |
| <JMSTopic name="jmsTopic" topicBindingName="MyTopic" factoryBindingName="MyTopicConnectionFactory"/> |
| </appenders> |
| <loggers> |
| <root level="error"> |
| <appender-ref ref="jmsQueue"/> |
| </root> |
| </loggers> |
| </configuration> |
| ]]></source> |
| </p> |
| </subsection> |
| <a name="OutputStreamAppender"/> |
| <subsection name="OutputStreamAppender"> |
| The OutputStreamAppender provides the base for many of the other Appenders such as the File and Socket |
| appenders that write the event to an Output Stream. It cannot be directly configured. Support for |
| immediateFlush and buffering is provided by the OutputStreamAppender. The OutputStreamAppender uses an |
| OutputStreamManager to handle the actual I/O, allowing the stream to be shared by Appenders in multiple |
| configurations. |
| </subsection> |
| <a name="RewriteAppender"/> |
| <subsection name="RewriteAppender"> |
| <p> |
| The RewriteAppender allows the LogEvent to manipulated before it is processed by another Appender. This |
| can be used to mask sensitive information such as passwords or to inject information into each event. |
| The RewriteAppender must be configured with a <a href="RewritePolicy">RewritePolicy</a>. |
| </p> |
| <table border="1" width="100%"> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>appender-ref</td> |
| <td>String</td> |
| <td>The name of the Appender to call after the LogEvent has been manipulated.</td> |
| </tr> |
| <tr> |
| <td>filter</td> |
| <td>Filter</td> |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| <tr> |
| <td>name</td> |
| <td>String</td> |
| <td>The name of the Appender.</td> |
| </tr> |
| <tr> |
| <td>rewritePolicy</td> |
| <td>RewritePolciy</td> |
| <td>The RewritePolicy that will manipulate the LogEvent.</td> |
| </tr> |
| <tr> |
| <td>suppressExceptions</td> |
| <td>boolean</td> |
| <td>The default is true, causing exceptions to be internally logged and then ignored. When set to |
| false exceptions will be percolated to the caller.</td> |
| </tr> |
| <caption align="top">RewriteAppender Parameters</caption> |
| </table> |
| <h4>RewritePolicy</h4> |
| <p> |
| RewritePolicy is an interface that allows implementations to inspect and possibly modify LogEvents |
| before they are passed to Appender. RewritePolicy declares a single method named rewrite that must |
| be implemented. The method is passed the LogEvent and can return the same event or create a new one. |
| </p> |
| <h5>MapRewritePolicy</h5> |
| <p> |
| MapRewritePolicy will evaluate LogEvents that contain a MapMessage and will add or update |
| elements of the Map. |
| </p> |
| <table border="1" width="100%"> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>mode</td> |
| <td>String</td> |
| <td>"Add" or "Update"</td> |
| </tr> |
| <tr> |
| <td>keyValuePair</td> |
| <td>KeyValuePair[]</td> |
| <td>An array of keys and their values.</td> |
| </tr> |
| </table> |
| <p> |
| The following configuration shows a RewriteAppender configured to add a product key and its value |
| to the MapMessage.: |
| |
| <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> |
| <configuration status="warn" name="MyApp" packages=""> |
| <appenders> |
| <Console name="STDOUT" target="SYSTEM_OUT"> |
| <PatternLayout pattern="%m%n"/> |
| </Console> |
| <Rewrite name="rewrite"> |
| <appender-ref ref="STDOUT"/> |
| <MapRewritePolicy mode="Add"> |
| <KeyValuePair key="product" value="TestProduct"/> |
| </MapRewritePolicy> |
| </Rewrite> |
| </appenders> |
| <loggers> |
| <root level="error"> |
| <appender-ref ref="Rewrite"/> |
| </root> |
| </loggers> |
| </configuration> |
| ]]></source> |
| </p> |
| </subsection> |
| <a name="RollingFileAppender"/> |
| <subsection name="RollingFileAppender"> |
| <p>The RollingFileAppender is an OutputStreamAppender that writes to the File named in the fileName parameter |
| and rolls the file over according the TriggeringPolicy and the RolloverPolicy. The |
| RollingFileAppender uses a RollingFileManager (which extends OutputStreamManager) to actually perform the |
| file I/O and perform the rollover. While RolloverFileAppenders from different Configurations cannot be |
| shared, the RollingFileManagers can be if the Manager is accessible. For example, two webapps in a |
| servlet container can have their own configuration and safely |
| write to the same file if Log4J is in a ClassLoader that is common to both of them.</p> |
| <p> |
| A RollingFileAppender requires a <a href="#TriggeringPolicies">TriggeringPolicy</a> and a |
| <a href="#RolloverStrategies">RolloverStrategy</a>. The triggering policy determines if a rollover should |
| be performed while the RolloverStrategy defines how the rollover should be done. If no RolloverStrategy |
| is configured, RollingFileAppender will use the <a href="DefaultRolloverStrategy">DefaultRolloverStrategy</a>. |
| </p> |
| <p> |
| File locking is not supported by the RollingFileAppender. |
| </p> |
| <table border="1" width="100%"> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>append</td> |
| <td>boolean</td> |
| <td>When true - the default, records will be appended to the end of the file. When set to false, |
| the file will be cleared before new reocrds are written.</td> |
| </tr> |
| <tr> |
| <td>bufferedIO</td> |
| <td>boolean</td> |
| <td>When true - the default, records will be written to a buffer and the data will be written to |
| disk when the buffer is full or, if immediateFlush is set, when the record is written. |
| File locking cannot be used with bufferedIO. Performance tests have shown that using buffered I/O |
| significantly improves performance, even if immediateFlush is enabled.</td> |
| </tr> |
| <tr> |
| <td>filter</td> |
| <td>Filter</td> |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| <tr> |
| <td>fileName</td> |
| <td>String</td> |
| <td>The name of the file to write to. If the file, or any of its parent directories, do not exist, |
| they will be created.</td> |
| </tr> |
| <tr> |
| <td>filePattern</td> |
| <td>String</td> |
| <td>The pattern of the file name of the archived log file. The format of the pattern should is |
| dependent on the RolloverPolicy that is used. The DefaultRolloverPolicy will accept both |
| a date/time pattern compatible with |
| <a href="http://download.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat</a> |
| and and/or a %d which represents an integer counter. The pattern also supports interpolation at |
| runtime so any of the Lookups (such as the <a href="./lookups.html#DateLookup">DateLookup</a> can |
| be included in the pattern.</td> |
| </tr> |
| <tr> |
| <td>immediateFlush</td> |
| <td>boolean</td> |
| <td>When set to true, each write will be followed by a flush. This will guarantee the data is written |
| to disk but could impact performance.</td> |
| </tr> |
| <tr> |
| <td>layout</td> |
| <td>Layout</td> |
| <td>The Layout to use to format the LogEvent</td> |
| </tr> |
| |
| <tr> |
| <td>name</td> |
| <td>String</td> |
| <td>The name of the Appender.</td> |
| </tr> |
| <tr> |
| <td>policy</td> |
| <td>TriggeringPolicy</td> |
| <td>The policy to use to determine if a rollover should occur.</td> |
| </tr> |
| <tr> |
| <td>strategy</td> |
| <td>RolloverStrategy</td> |
| <td>The strategy to use to determine the name and location of the archive file.</td> |
| </tr> |
| <tr> |
| <td>suppressExceptions</td> |
| <td>boolean</td> |
| <td>The default is true, causing exceptions to be internally logged and then ignored. When set to |
| false exceptions will be percolated to the caller.</td> |
| </tr> |
| <caption align="top">RollingFileAppender Parameters</caption> |
| </table> |
| <a name="TriggeringPolicies"/> |
| <h4>Triggering Policies</h4> |
| <h5>Composite Triggering Policy</h5> |
| <p> |
| The CompositeTriggeringPolicy combines multiple triggering policies and returns true if any |
| of the configured policies return true. The CompositeTriggeringPolicy is configured simply |
| by wrapping other policies in a "Policies" element. |
| </p> |
| <h5>OnStartup Triggering Policy</h5> |
| <p> |
| The OnStartup policy takes no parameters and causes a rollover if the log file is older than the |
| current JVM's start time. |
| </p> |
| <h5>SizeBased Triggering Policy</h5> |
| <p> |
| Causes a rollover once the file has reached the specified size. The size can be specified in bytes, |
| KB, MB or GB. |
| </p> |
| <h5>TimeBased Triggering Policy</h5> |
| <p> |
| Causes a rollover once the date/time pattern no longer applies to the active file. This policy |
| takes no parameters. |
| </p> |
| <a name="RolloverStrategies"/> |
| <h4>Rollover Strategies</h4> |
| <a name="DefaultRolloverStrategy"/> |
| <h5>Default Rollover Strategy</h5> |
| <p> |
| The default rollover strategy accepts both a date/time pattern and an integer. If the date/time pattern |
| is present it will be replaced with the current date and time values. If the pattern contains an integer |
| it will be incremented on each rollover. If the pattern contains both a date/time and integer |
| in the pattern the integer will be incremented until the result of the date/time pattern changes. If |
| the file pattern ends with ".gz" or ".zip" the resulting archive will be compressed using the |
| compression scheme that matches the suffix. The pattern may also contain lookup references that |
| can be resolved at runtime such as is shown in the example below. |
| </p> |
| <table border="1" width="100%"> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>min</td> |
| <td>integer</td> |
| <td>The minimum value of the counter. The default value is 1.</td> |
| </tr> |
| <tr> |
| <td>max</td> |
| <td>integer</td> |
| <td>The maximum value of the counter. Once this values is reached. Older archives will be |
| deleted on subsequent rollovers.</td> |
| </tr> |
| <caption align="top">DefaultRolloverStrategy Parameters</caption> |
| </table> |
| <p> |
| Below is a sample configuration that uses a RollingFileAppender with both the time and size based |
| triggering policies, will create up to 7 archives on the same day (1-7) that are stored in a directory |
| based on the current year and month, and will compress each |
| archive using gzip: |
| |
| <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> |
| <configuration status="warn" name="MyApp" packages=""> |
| <appenders> |
| <RollingFile name="RollingFile" fileName="logs/app.log" |
| filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%d.log.gz"> |
| <PatternLayout> |
| <pattern>%d %p %C{1.} [%t] %m%n</pattern> |
| </PatternLayout> |
| <Policies> |
| <TimeBasedTriggeringPolicy /> |
| <SizeBasedTriggeringPolicy size="250 MB"/> |
| </Policies> |
| </RollingFile> |
| </appenders> |
| <loggers> |
| <root level="error"> |
| <appender-ref ref="RollingFile"/> |
| </root> |
| </loggers> |
| </configuration> |
| ]]></source> |
| </p> |
| </subsection> |
| <a name="RoutingAppender"/> |
| <subsection name="RoutingAppender"> |
| <p> |
| The RoutingAppender evaluates LogEvents and then routes them to a subordinate Appender. The target |
| Appender may be an appender previously configured and may be referenced by its name or the |
| Appender can be dynamically created as needed. |
| </p> |
| <table border="1" width="100%"> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>filter</td> |
| <td>Filter</td> |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| <tr> |
| <td>name</td> |
| <td>String</td> |
| <td>The name of the Appender.</td> |
| </tr> |
| <tr> |
| <td>rewritePolicy</td> |
| <td>RewritePolciy</td> |
| <td>The RewritePolicy that will manipulate the LogEvent.</td> |
| </tr> |
| <tr> |
| <td>routes</td> |
| <td>Routes</td> |
| <td>Contains one or more Route declarations to identify the criteria for choosing Appenders.</td> |
| </tr> |
| <tr> |
| <td>suppressExceptions</td> |
| <td>boolean</td> |
| <td>The default is true, causing exceptions to be internally logged and then ignored. When set to |
| false exceptions will be percolated to the caller.</td> |
| </tr> |
| <caption align="top">RoutingAppender Parameters</caption> |
| </table> |
| <h4>Routes</h4> |
| <p> |
| The Routes element accepts a single, required attribute named "pattern". The pattern is evaluated |
| against all the registered Lookups and the result is used to select a Route. Each Route may be |
| configured with a key. If the key matches the result of evaluating the pattern then that Route |
| will be selected. If no key is specified on a Route then that Route is the default. Only one Route |
| can be configured as the default. |
| </p> |
| <p> |
| Each Route must reference an Appender. If the Route contains an appender-ref attribute then the |
| Route will reference an Appender that was defined in the configuration. If the Route contains an |
| Appender definition then an Appender will be created within the context of the RoutingAppender and |
| will be reused each time a matching Appender name is referenced through a Route. |
| </p> |
| <p> |
| Below is a sample configuration that uses a RoutingFileAppender to route all Audit events to |
| a FlumeAppender and all other events will be routed to a RollingFileAppender that captures only |
| the specific event type. Note that the AuditAppender was predefined while the RoutingFileAppenders |
| are created as needed. |
| |
| <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> |
| <configuration status="warn" name="MyApp" packages=""> |
| <appenders> |
| <Flume name="AuditLogger" suppressExceptions="false" compress="true"> |
| <Agent host="192.168.10.101" port="8800"/> |
| <Agent host="192.168.10.102" port="8800"/> |
| <RFC5424Layout enterpriseNumber="18060" includeMDC="true" appName="MyApp"/> |
| </Flume> |
| <Routing name="Routing"> |
| <Routes pattern="$${sd:type}"> |
| <Route> |
| <RollingFile name="Rolling-${sd:type}" fileName="${sd:type}.log" |
| filePattern="${sd:type}.%i.log.gz"> |
| <PatternLayout> |
| <pattern>%d %p %C{1.} [%t] %m%n</pattern> |
| </PatternLayout> |
| <SizeBasedTriggeringPolicy size="500" /> |
| </RollingFile> |
| </Route> |
| <Route appender-ref="AuditLogger" key="Audit"/> |
| </Routes> |
| </Routing> |
| </appenders> |
| <loggers> |
| <root level="error"> |
| <appender-ref ref="Routing"/> |
| </root> |
| </loggers> |
| </configuration> |
| ]]></source> |
| </p> |
| </subsection> |
| <a name="SocketAppender"/> |
| <subsection name="SocketAppender"> |
| <p> |
| The SocketAppender is an OutputStreamAppender that writes its output to a remote destination |
| specified by a host and port. The data can be sent over either TCP or UDP and can be sent in any format. |
| The default format is to send a Serialized LogEvent. Log4j 2.0 contains a SocketServer which is capable |
| of receiving serialized LogEvents and routing them through the logging system on the server. |
| </p> |
| <table border="1" width="100%"> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>filter</td> |
| <td>Filter</td> |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| <tr> |
| <td>host</td> |
| <td>String</td> |
| <td>The name or address of the system that is listening for log events. This parameter is required.</td> |
| </tr> |
| <tr> |
| <td>immediateFlush</td> |
| <td>boolean</td> |
| <td>When set to true, each write will be followed by a flush. This will guarantee the data is written |
| to disk but could impact performance.</td> |
| </tr> |
| <tr> |
| <td>layout</td> |
| <td>Layout</td> |
| <td>The Layout to use to format the LogEvent. The default is SerializedLayout.</td> |
| </tr> |
| <tr> |
| <td>name</td> |
| <td>String</td> |
| <td>The name of the Appender.</td> |
| </tr> |
| <tr> |
| <td>port</td> |
| <td>integer</td> |
| <td>The port on the host that is listening for log events. This parameter must be specified.</td> |
| </tr> |
| <tr> |
| <td>protocol</td> |
| <td>String</td> |
| <td>"TCP" or "UDP". This parameter is required.</td> |
| </tr> |
| <tr> |
| <td>reconnectionDelay</td> |
| <td>integer</td> |
| <td>If set to a value greater than 0, after an error the SocketManager will attempt to reconnect to |
| the server after waiting the specified number of milliseconds. If the reconnect fails then |
| an exception will be thrown (which can be caught by the application if suppressExceptions is |
| set to false).</td> |
| </tr> |
| <tr> |
| <td>suppressExceptions</td> |
| <td>boolean</td> |
| <td>The default is true, causing exceptions to be internally logged and then ignored. When set to |
| false exceptions will be percolated to the caller.</td> |
| </tr> |
| <caption align="top">SocketAppender Parameters</caption> |
| </table> |
| </subsection> |
| <a name="SyslogAppender"/> |
| <subsection name="SyslogAppender"> |
| <p> |
| The SyslogAppender is a SocketAppender that writes its output to a remote destination |
| specified by a host and port in a format that conforms with either the BSD Syslog format or the RFC 5424 |
| format. The data can be sent over either TCP or UDP. |
| </p> |
| <table border="1" width="100%"> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Type</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>appName</td> |
| <td>String</td> |
| <td>The value to use as the APP-NAME in the RFC 5424 syslog record.</td> |
| </tr> |
| <tr> |
| <td>charset</td> |
| <td>String</td> |
| <td>The character set to use when converting the syslog String to a byte array. The String must be |
| a valid <a href="http://download.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html">Charset</a>. |
| If not specified, the default system Charset will be used.</td> |
| </tr> |
| <tr> |
| <td>enterpriseNumber</td> |
| <td>integer</td> |
| <td>The IANA enterprise number as described in |
| <a href="http://tools.ietf.org/html/rfc5424#section-7.2.2">RFC 5424</a></td> |
| </tr> |
| <tr> |
| <td>filter</td> |
| <td>Filter</td> |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| <tr> |
| <td>facility</td> |
| <td>String</td> |
| <td>The facility is used to try to classify the message. The facility option must be set to one of |
| "KERN", "USER", "MAIL", "DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV", |
| "FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2", "LOCAL3", "LOCAL4", "LOCAL5", |
| "LOCAL6", or "LOCAL7". These values may be specified as upper or lower case characters.</td> |
| </tr> |
| <tr> |
| <td>format</td> |
| <td>String</td> |
| <td>If set to "RFC5424" the data will be formatted in accordance with RFC 5424. Otherwise, it will |
| be formatted as a BSD Syslog record. Note that although BSD Syslog records are required to be |
| 1024 bytes or shorter the SyslogLayout does not truncate them. The RFC5424Layout also does not |
| truncate records since the receiver must accept records of up to 2048 bytes and may accept records |
| that are longer.</td> |
| </tr> |
| <tr> |
| <td>host</td> |
| <td>String</td> |
| <td>The name or address of the system that is listening for log events. This parameter is required.</td> |
| </tr> |
| <tr> |
| <td>id</td> |
| <td>String</td> |
| <td>The default structured data id to use when formatting according to RFC 5424. If the LogEvent contains |
| a StructuredDataMessage the id from the Message will be used instead of this value.</td> |
| </tr> |
| <tr> |
| <td>immediateFlush</td> |
| <td>boolean</td> |
| <td>When set to true, each write will be followed by a flush. This will guarantee the data is written |
| to disk but could impact performance.</td> |
| </tr> |
| <tr> |
| <td>includeMDC</td> |
| <td>boolean</td> |
| <td>Indicates whether data from the ThreadContextMap will be included in the RFC 5424 Syslog record. |
| Defaults to true.</td> |
| </tr> |
| <tr> |
| <td>mdcExcludes</td> |
| <td>String</td> |
| <td>A comma separated list of mdc keys that should be excluded from the LogEvent. This is mutually |
| exclusive with the mdcIncludes attribute. This attribute only applies to RFC 5424 syslog records.</td> |
| </tr> |
| <tr> |
| <td>mdcIncludes</td> |
| <td>String</td> |
| <td>A comma separated list of mdc keys that should be included in the FlumeEvent. Any keys in the MDC |
| not found in the list will be excluded. This option is mutually exclusive with the mdcExcludes |
| attribute. This attribute only applies to RFC 5424 syslog records.</td> |
| </tr> |
| <tr> |
| <td>mdcRequired</td> |
| <td>String</td> |
| <td>A comma separated list of mdc keys that must be present in the MDC. If a key is not present a |
| LoggingException will be thrown. This attribute only applies to RFC 5424 syslog records.</td> |
| </tr> |
| <tr> |
| <td>mdcPrefix</td> |
| <td>String</td> |
| <td>A string that should be prepended to each MDC key in order to distinguish it from event attributes. |
| The default string is "mdc:". This attribute only applies to RFC 5424 syslog records.</td> |
| </tr> |
| <tr> |
| <td>messageId</td> |
| <td>String</td> |
| <td>The default value to be used in the MSGID field of RFC 5424 syslog records. </td> |
| </tr> |
| <tr> |
| <td>name</td> |
| <td>String</td> |
| <td>The name of the Appender.</td> |
| </tr> |
| <tr> |
| <td>newLine</td> |
| <td>boolean</td> |
| <td>If true, a newline will be appended to the end of the syslog record. The default is false.</td> |
| </tr> |
| <tr> |
| <td>port</td> |
| <td>integer</td> |
| <td>The port on the host that is listening for log events. This parameter must be specified.</td> |
| </tr> |
| |
| <tr> |
| <td>protocol</td> |
| <td>String</td> |
| <td>"TCP" or "UDP". This parameter is required.</td> |
| </tr> |
| <tr> |
| <td>reconnectionDelay</td> |
| <td>integer</td> |
| <td>If set to a value greater than 0, after an error the SocketManager will attempt to reconnect to |
| the server after waiting the specified number of milliseconds. If the reconnect fails then |
| an exception will be thrown (which can be caught by the application if suppressExceptions is |
| set to false).</td> |
| </tr> |
| <tr> |
| <td>suppressExceptions</td> |
| <td>boolean</td> |
| <td>The default is true, causing exceptions to be internally logged and then ignored. When set to |
| false exceptions will be percolated to the caller.</td> |
| </tr> |
| <caption align="top">SyslogAppender Parameters</caption> |
| </table> |
| <p> |
| A sample syslogAppender configuration that is configured with two SyslogAppenders, one using the BSD |
| format and one using RFC 5424. |
| |
| <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> |
| <configuration status="warn" name="MyApp" packages=""> |
| <appenders> |
| <Syslog name="bsd" host="localhost" port="514" protocol="TCP"/> |
| <Syslog name="RFC5424" format="RFC5424" host="localhost" port="8514" protocol="TCP" appName="MyApp" includeMDC="true" |
| facility="LOCAL0" enterpriseNumber="18060" newLine="true" messageId="Audit" id="App"/> |
| </appenders> |
| <loggers> |
| <logger name="com.mycorp" level="error"> |
| <appender-ref ref="RFC5424"/> |
| </logger> |
| <root level="error"> |
| <appender-ref ref="bsd"/> |
| </root> |
| </loggers> |
| </configuration> |
| ]]></source> |
| </p> |
| </subsection> |
| </section> |
| </body> |
| </document> |
