AsyncAppender

The AsyncAppender accepts references to other Appenders and causes LogEvents to be written to them on a separate Thread. Note that exceptions while writing to those Appenders will be hidden from the application. The AsyncAppender should be configured after the appenders it references to allow it to shut down properly.

A typical AsyncAppender configuration might look like:

<?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>
    <Async name="Async">
      <appender-ref ref="MyFile"/>
    </Async>
  </appenders>
  <loggers>
    <root level="error">
      <appender-ref ref="Async"/>
    </root>
  </loggers>
</configuration>

ConsoleAppender

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.

A typical Console configuration might look like:

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

FailoverAppender

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.

A Failover configuration might look like:

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

FileAppender

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.

Here is a sample File configuration:

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

FlumeAppender

This is an optional component supplied in a separate jar.

Apache Flume 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.

The Flume Appender supports three modes of operation.

1. It can act as a remote Flume client which sends Flume events via Avro to a Flume Agent configured with an Avro Source.
2. It can act as an embedded Flume Agent where Flume events pass directly into Flume for processing.
3. It can persist events to a local BerkeleyDB datastore and then asynchronously send the events to Flume, similar to the embedded Flume Agent but without most of the Flume dependencies.

A sample FlumeAppender configuration that is configured with a primary and a secondary agent, compresses the body, and formats the body using the RFC5424Layout:

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

A sample FlumeAppender configuration that is configured with a primary and a secondary agent, compresses the body, formats the body using the RFC5424Layout, and persists encrypted events to disk:

<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
  <appenders>
    <Flume name="eventLogger" suppressExceptions="false" compress="true" type="persistent" dataDir="./logData">
      <Agent host="192.168.10.101" port="8800"/>
      <Agent host="192.168.10.102" port="8800"/>
      <RFC5424Layout enterpriseNumber="18060" includeMDC="true" appName="MyApp"/>
      <Property name="keyProvider">MySecretProvider</Property>
    </Flume>
  </appenders>
  <loggers>
    <root level="error">
      <appender-ref ref="eventLogger"/>
    </root>
  </loggers>
</configuration>

A sample FlumeAppender configuration that is configured with a primary and a secondary agent, compresses the body, formats the body using RFC5424Layout and passes the events to an embedded Flume Agent.

<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
  <appenders>
    <Flume name="eventLogger" suppressExceptions="false" compress="true" type="Embedded">
      <Agent host="192.168.10.101" port="8800"/>
      <Agent host="192.168.10.102" port="8800"/>
      <RFC5424Layout enterpriseNumber="18060" includeMDC="true" appName="MyApp"/>
    </Flume>
    <Console name="STDOUT">
      <PatternLayout pattern="%d [%p] %c %m%n"/>
    </Console>
  </appenders>
  <loggers>
    <logger name="EventLogger" level="info">
      <appender-ref ref="eventLogger"/>
    </logger>
    <root level="warn">
      <appender-ref ref="STDOUT"/>
    </root>
  </loggers>
</configuration>

A sample FlumeAppender configuration that is configured with a primary and a secondary agent using Flume configuration properties, compresses the body, formats the body using RFC5424Layout and passes the events to an embedded Flume Agent.

<?xml version="1.0" encoding="UTF-8"?>
<configuration status="error" name="MyApp" packages="">
  <appenders>
    <Flume name="eventLogger" suppressExceptions="false" compress="true" type="Embedded">
      <Property name="channels">file</Property>
      <Property name="channels.file.type">file</Property>
      <Property name="channels.file.checkpointDir">target/file-channel/checkpoint</Property>
      <Property name="channels.file.dataDirs">target/file-channel/data</Property>
      <Property name="sinks">agent1 agent2</Property>
      <Property name="sinks.agent1.channel">file</Property>
      <Property name="sinks.agent1.type">avro</Property>
      <Property name="sinks.agent1.hostname">192.168.10.101</Property>
      <Property name="sinks.agent1.port">8800</Property>
      <Property name="sinks.agent1.batch-size">100</Property>
      <Property name="sinks.agent2.channel">file</Property>
      <Property name="sinks.agent2.type">avro</Property>
      <Property name="sinks.agent2.hostname">192.168.10.102</Property>
      <Property name="sinks.agent2.port">8800</Property>
      <Property name="sinks.agent2.batch-size">100</Property>
      <Property name="sinkgroups">group1</Property>
      <Property name="sinkgroups.group1.sinks">agent1 agent2</Property>
      <Property name="sinkgroups.group1.processor.type">failover</Property>
      <Property name="sinkgroups.group1.processor.priority.agent1">10</Property>
      <Property name="sinkgroups.group1.processor.priority.agent2">5</Property>
      <RFC5424Layout enterpriseNumber="18060" includeMDC="true" appName="MyApp"/>
    </Flume>
    <Console name="STDOUT">
      <PatternLayout pattern="%d [%p] %c %m%n"/>
    </Console>
  </appenders>
  <loggers>
    <logger name="EventLogger" level="info">
      <appender-ref ref="eventLogger"/>
    </logger>
    <root level="warn">
      <appender-ref ref="STDOUT"/>
    </root>
  </loggers>
</configuration>

JMSQueueAppender

The JMSQueueAppender sends the formatted log event to a JMS Queue.

Here is a sample JMSQueueAppender configuration:

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

JMSTopicAppender

The JMSTopicAppender sends the formatted log event to a JMS Topic.

Here is a sample JMSTopicAppender configuration:

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

OutputStreamAppender

RewriteAppender

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 RewritePolicy. The RewriteAppender should be configured after any Appenders it references to allow it to shut down properly.

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

<?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"/>
      <PropertiesRewritePolicy>
        <Property key="user">${sys:user.name}</Property>
        <Property key="env">${sys:environment}</Property>
      </PropertiesRewritePolicy>
    </Rewrite>
  </appenders>
  <loggers>
    <root level="error">
      <appender-ref ref="Rewrite"/>
    </root>
  </loggers>
</configuration>

RollingFileAppender

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.

A RollingFileAppender requires a TriggeringPolicy and a RolloverStrategy. 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 DefaultRolloverStrategy.

File locking is not supported by the RollingFileAppender.

<?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}-%i.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>

<?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}-%i.log.gz">
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <Policies>
        <TimeBasedTriggeringPolicy />
        <SizeBasedTriggeringPolicy size="250 MB"/>
      </Policies>
      <DefaultRolloverStrategy max="20"/>
    </RollingFile>
  </appenders>
  <loggers>
    <root level="error">
      <appender-ref ref="RollingFile"/>
    </root>
  </loggers>
</configuration>

<?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{yyyy-MM-dd-HH}-%i.log.gz">
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <Policies>
        <TimeBasedTriggeringPolicy interval="6" modulate="true"/>
        <SizeBasedTriggeringPolicy size="250 MB"/>
      </Policies>
    </RollingFile>
  </appenders>
  <loggers>
    <root level="error">
      <appender-ref ref="RollingFile"/>
    </root>
  </loggers>
</configuration>

FastFileAppender

Experimental, may replace FileAppender in a future release.

The FastFileAppender is similar to the standard FileAppender except it is always buffered (this cannot be switched off) and internally it uses a ByteBuffer + RandomAccessFile instead of a BufferedOutputStream. We saw a 20-200% performance improvement compared to FileAppender with "bufferedIO=true" in our measurements. Similar to the FileAppender, FastFileAppender uses a FastFileManager to actually perform the file I/O. While FastFileAppender from different Configurations cannot be shared, the FastFileManagers 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.

Here is a sample FastFile configuration:

<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
  <appenders>
    <FastFile name="MyFile" fileName="logs/app.log">
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
    </FastFile>
  </appenders>
  <loggers>
    <root level="error">
      <appender-ref ref="MyFile"/>
    </root>
  </loggers>
</configuration>

FastRollingFileAppender

Experimental, may replace RollingFileAppender in a future release.

The FastRollingFileAppender is similar to the standard RollingFileAppender except it is always buffered (this cannot be switched off) and internally it uses a ByteBuffer + RandomAccessFile instead of a BufferedOutputStream. We saw a 20-200% performance improvement compared to RollingFileAppender with "bufferedIO=true" in our measurements. The FastRollingFileAppender writes to the File named in the fileName parameter and rolls the file over according the TriggeringPolicy and the RolloverPolicy. Similar to the RollingFileAppender, FastRollingFileAppender uses a FastRollingFileManager to actually perform the file I/O and perform the rollover. While FastRollingFileAppender from different Configurations cannot be shared, the FastRollingFileManagers 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.

A FastRollingFileAppender requires a TriggeringPolicy and a RolloverStrategy. 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, FastRollingFileAppender will use the DefaultRolloverStrategy.

File locking is not supported by the FastRollingFileAppender.

<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
  <appenders>
    <FastRollingFile name="FastRollingFile" fileName="logs/app.log"
                 filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log.gz">
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <Policies>
        <TimeBasedTriggeringPolicy />
        <SizeBasedTriggeringPolicy size="250 MB"/>
      </Policies>
    </FastRollingFile>
  </appenders>
  <loggers>
    <root level="error">
      <appender-ref ref="FastRollingFile"/>
    </root>
  </loggers>
</configuration>

<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
  <appenders>
    <FastRollingFile name="FastRollingFile" fileName="logs/app.log"
                 filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log.gz">
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <Policies>
        <TimeBasedTriggeringPolicy />
        <SizeBasedTriggeringPolicy size="250 MB"/>
      </Policies>
      <DefaultRolloverStrategy max="20"/>
    </FastRollingFile>
  </appenders>
  <loggers>
    <root level="error">
      <appender-ref ref="FastRollingFile"/>
    </root>
  </loggers>
</configuration>

<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
  <appenders>
    <FastRollingFile name="FastRollingFile" fileName="logs/app.log"
                 filePattern="logs/$${date:yyyy-MM}/app-%d{yyyy-MM-dd-HH}-%i.log.gz">
      <PatternLayout>
        <pattern>%d %p %c{1.} [%t] %m%n</pattern>
      </PatternLayout>
      <Policies>
        <TimeBasedTriggeringPolicy interval="6" modulate="true"/>
        <SizeBasedTriggeringPolicy size="250 MB"/>
      </Policies>
    </FastRollingFile>
  </appenders>
  <loggers>
    <root level="error">
      <appender-ref ref="FastRollingFile"/>
    </root>
  </loggers>
</configuration>

RoutingAppender

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. The RoutingAppender should be configured after any Appenders it references to allow it to shut down properly.

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

SMTPAppender

Sends an e-mail when a specific logging event occurs, typically on errors or fatal errors.

The number of logging events delivered in this e-mail depend on the value of BufferSize option. The SMTPAppender keeps only the last BufferSize logging events in its cyclic buffer. This keeps memory requirements at a reasonable level while still delivering useful application context.

The default behavior is to trigger sending an email whenever an ERROR or higher severity event is logged and to format it as HTML. The circumstances on when the email is sent can be controlled by setting one or more filters on the Appender. As with other Appenders, the formatting can be controlled by specifying a Layout for the Appender.

<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
  <appenders>
    <SMTP name="Mail" suppressExceptions="false" subject="Error Log" to="errors@logging.apache.org"
      from="test@logging.apache.org" smtpHost="localhost" smtpPort="25" bufferSize="50">
    </SMTP>
  </appenders>
  <loggers>
    <root level="error">
      <appender-ref ref="Mail"/>
    </root>
  </loggers>
</configuration>

SocketAppender

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 contains a SocketServer which is capable of receiving serialized LogEvents and routing them through the logging system on the server.

<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" name="MyApp" packages="">
  <appenders>
    <Socket name="socket" host="localhost" port="9500">
      <SerializedLayout />
    </Socket>
  </appenders>
  <loggers>
    <root level="error">
      <appender-ref ref="socket"/>
    </root>
  </loggers>
</configuration>

SyslogAppender

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.

A sample syslogAppender configuration that is configured with two SyslogAppenders, one using the BSD format and one using RFC 5424.

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