http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/0c47af7f/src/site/asciidoc/manual/appenders.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/appenders.adoc 
b/src/site/asciidoc/manual/appenders.adoc
new file mode 100644
index 0000000..b37af23
--- /dev/null
+++ b/src/site/asciidoc/manual/appenders.adoc
@@ -0,0 +1,4483 @@
+= Appenders
+Ralph Goers; Gary Gregory; Nick Williams; Matt Sicker
+
+Appenders are responsible for delivering LogEvents to their destination.
+Every Appender must implement the
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/Appender.html[`Appender`]
+interface. Most Appenders will extend
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/appender/AbstractAppender.html[`AbstractAppender`]
+which adds
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/LifeCycle.html[`Lifecycle`]
+and
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/filter/Filterable.html[`Filterable`]
+support. `Lifecycle` allows components to finish initialization after
+configuration has completed and to perform cleanup during shutdown.
+`Filterable` allows the component to have `Filter`s attached to it which are
+evaluated during event processing.
+
+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 link:layouts.html[layout]. 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.
+
+Appenders always have a name so that they can be referenced from
+Loggers.
+
+In the tables below, the "Type" column corresponds to the Java type
+expected. For non-JDK classes, these should usually be in
+link:../log4j-core/apidocs/index.html[Log4j Core] unless otherwise
+noted.
+
+[#AsyncAppender]
+== 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.
+
+By default, AsyncAppender uses
+https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ArrayBlockingQueue.html[`java.util.concurrent.ArrayBlockingQueue`]
+which does not require any external libraries. Note that multi-threaded
+applications should exercise care when using this appender as such: the
+blocking queue is susceptible to lock contention and our
+link:../performance.html#asyncLogging[tests showed] performance may
+become worse when more threads are logging concurrently. Consider using
+link:async.html[lock-free Async Loggers] for optimal performance.
+
+.AsyncAppender Parameters
+[width="100%",cols="34%,33%,33%",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|AppenderRef |String |The name of the Appenders to invoke
+asynchronously. Multiple AppenderRef elements can be configured.
+
+|blocking |boolean |If true, the appender will wait until there are free
+slots in the queue. If false, the event will be written to the error
+appender if the queue is full. The default is true.
+
+|shutdownTimeout |integer |How many milliseconds the Appender should
+wait to flush outstanding log events in the queue on shutdown. The
+default is zero which means to wait forever.
+
+|bufferSize |integer a|
+Specifies the maximum number of events that can be queued. The default
+is 1024. Note that when using a disruptor-style `BlockingQueue`, this
+buffer size must be a power of 2.
+
+When the application is logging faster than the underlying appender can
+keep up with for a long enough time to fill up the queue, the behavious
+is determined by the
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.html[`AsyncQueueFullPolicy`].
+
+|errorRef |String |The name of the Appender to invoke if none of the
+appenders can be called, either due to errors in the appenders or
+because the queue is full. If not specified then errors will be ignored.
+
+|filter |Filter |A Filter to determine if the event should be handled by
+this Appender. More than one Filter may be used by using a
+CompositeFilter.
+
+|name |String |The name of the Appender.
+
+|ignoreExceptions |boolean |The default is `true`, causing exceptions
+encountered while appending events to be internally logged and then
+ignored. When set to `false` exceptions will be propagated to the
+caller, instead. You must set this to `false` when wrapping this
+Appender in a link:#FailoverAppender[FailoverAppender].
+
+|includeLocation |boolean |Extracting location is an expensive operation
+(it can make logging 5 - 20 times slower). To improve performance,
+location is not included by default when adding a log event to the
+queue. You can change this by setting includeLocation="true".
+
+|BlockingQueueFactory |BlockingQueueFactory |This element overrides what
+type of `BlockingQueue` to use. See link:#BlockingQueueFactory[below
+documentation] for more details.
+|=======================================================================
+
+There are also a few system properties that can be used to maintain
+application throughput even when the underlying appender cannot keep up
+with the logging rate and the queue is filling up. See the details for
+system properties
+link:configuration.html#log4j2.AsyncQueueFullPolicy[`log4j2.AsyncQueueFullPolicy`
+and `log4j2.DiscardThreshold`].
+
+A typical AsyncAppender configuration might look like:
+
+[source,xml]
+----
+<?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">
+      <AppenderRef ref="MyFile"/>
+    </Async>
+  </Appenders>
+  <Loggers>
+    <Root level="error">
+      <AppenderRef ref="Async"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+[[BlockingQueueFactory]] Starting in Log4j 2.7, a custom implementation
+of `BlockingQueue` or `TransferQueue` can be specified using a
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/async/BlockingQueueFactory.html[`BlockingQueueFactory`]
+plugin. To override the default `BlockingQueueFactory`, specify the
+plugin inside an `<Async/>` element like so:
+
+[source,xml]
+----
+<Configuration name="LinkedTransferQueueExample">
+  <Appenders>
+    <List name="List"/>
+    <Async name="Async" bufferSize="262144">
+      <AppenderRef ref="List"/>
+      <LinkedTransferQueue/>
+    </Async>
+  </Appenders>
+  <Loggers>
+    <Root>
+      <AppenderRef ref="Async"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+Log4j ships with the following implementations:
+
+.BlockingQueueFactory Implementations
+[cols=",",options="header",]
+|=======================================================================
+|Plugin Name |Description
+|ArrayBlockingQueue |This is the default implementation that uses
+https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ArrayBlockingQueue.html[`ArrayBlockingQueue`].
+
+|DisruptorBlockingQueue |This uses the
+https://github.com/conversant/disruptor[Conversant Disruptor]
+implementation of `BlockingQueue`. This plugin takes a single optional
+attribute, `spinPolicy`, which corresponds to the `SpinPolicy` enum.
+
+|JCToolsBlockingQueue |This uses
+https://jctools.github.io/JCTools/[JCTools], specifically the MPSC
+bounded lock-free queue.
+
+|LinkedTransferQueue |This uses the new in Java 7 implementation
+https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/LinkedTransferQueue.html[`LinkedTransferQueue`].
+Note that this queue does not use the `bufferSize` configuration
+attribute from AsyncAppender as `LinkedTransferQueue` does not support a
+maximum capacity.
+|=======================================================================
+
+[#CassandraAppender]
+== CassandraAppender
+
+The CassandraAppender writes its output to an
+https://cassandra.apache.org/[Apache Cassandra] database. A keyspace and
+table must be configured ahead of time, and the columns of that table
+are mapped in a configuration file. Each column can specify either a
+link:layouts.html[StringLayout] (e.g., a
+link:layouts.html#PatternLayout[PatternLayout]) along with an optional
+conversion type, or only a conversion type for
+`org.apache.logging.log4j.spi.ThreadContextMap` or
+`org.apache.logging.log4j.spi.ThreadContextStack` to store the
+link:thread-context.html[MDC or NDC] in a map or list column
+respectively. A conversion type compatible with `java.util.Date` will
+use the log event timestamp converted to that type (e.g., use
+`java.util.Date` to fill a `timestamp` column type in Cassandra).
+
+.CassandraAppender Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|batched |boolean |Whether or not to use batch statements to write log
+messages to Cassandra. By default, this is `false`.
+
+|batchType
+|http://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/BatchStatement.Type.html[`BatchStatement.Type`]
+|The batch type to use when using batched writes. By default, this is
+`LOGGED`.
+
+|bufferSize |int |The number of log messages to buffer or batch before
+writing. By default, no buffering is done.
+
+|clusterName |String |The name of the Cassandra cluster to connect to.
+
+|columns |ColumnMapping[] |A list of column mapping configurations. Each
+column must specify a column name. Each column can have a conversion
+type specified by its fully qualified class name. By default, the
+conversion type is `String`. If the configured type is
+assignment-compatible with
+link:../log4j-api/apidocs/org/apache/logging/log4j/util/ReadOnlyStringMap.html[`ReadOnlyStringMap`]
+/
+link:../log4j-api/apidocs/org/apache/logging/log4j/spi/ThreadContextMap.html[`ThreadContextMap`]
+or
+link:../log4j-api/apidocs/org/apache/logging/log4j/spi/ThreadContextStack.html[`ThreadContextStack`],
+then that column will be populated with the MDC or NDC respectively. If
+the configured type is assignment-compatible with `java.util.Date`, then
+the log timestamp will be converted to that configured date type. If a
+`literal` attribute is given, then its value will be used as is in the
+`INSERT` query without any escaping. Otherwise, the layout or pattern
+specified will be converted into the configured type and stored in that
+column.
+
+|contactPoints |SocketAddress[] |A list of hosts and ports of Cassandra
+nodes to connect to. These must be valid hostnames or IP addresses. By
+default, if a port is not specified for a host or it is set to 0, then
+the default Cassandra port of 9042 will be used. By default,
+`localhost:9042` will be used.
+
+|filter |Filter |A Filter to determine if the event should be handled by
+this Appender. More than one Filter may be used by using a
+CompositeFilter.
+
+|ignoreExceptions |boolean |The default is `true`, causing exceptions
+encountered while appending events to be internally logged and then
+ignored. When set to `false` exceptions will be propagated to the
+caller, instead. You must set this to `false` when wrapping this
+Appender in a link:#FailoverAppender[FailoverAppender].
+
+|keyspace |String |The name of the keyspace containing the table that
+log messages will be written to.
+
+|name |String |The name of the Appender.
+
+|password |String |The password to use (along with the username) to
+connect to Cassandra.
+
+|table |String |The name of the table to write log messages to.
+
+|useClockForTimestampGenerator |boolean |Whether or not to use the
+configured `org.apache.logging.log4j.core.time.Clock` as a
+http://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/TimestampGenerator.html[`TimestampGenerator`].
+By default, this is `false`.
+
+|username |String |The username to use to connect to Cassandra. By
+default, no username or password is used.
+
+|useTls |boolean |Whether or not to use TLS/SSL to connect to Cassandra.
+This is `false` by default.
+|=======================================================================
+
+Here is an example CassandraAppender configuration:
+
+[source,xml]
+----
+<Configuration name="CassandraAppenderTest">
+  <Appenders>
+    <Cassandra name="Cassandra" clusterName="Test Cluster" keyspace="test" 
table="logs" bufferSize="10" batched="true">
+      <SocketAddress host="localhost" port="9042"/>
+      <ColumnMapping name="id" pattern="%uuid{TIME}" type="java.util.UUID"/>
+      <ColumnMapping name="timeid" literal="now()"/>
+      <ColumnMapping name="message" pattern="%message"/>
+      <ColumnMapping name="level" pattern="%level"/>
+      <ColumnMapping name="marker" pattern="%marker"/>
+      <ColumnMapping name="logger" pattern="%logger"/>
+      <ColumnMapping name="timestamp" type="java.util.Date"/>
+      <ColumnMapping name="mdc" 
type="org.apache.logging.log4j.spi.ThreadContextMap"/>
+      <ColumnMapping name="ndc" 
type="org.apache.logging.log4j.spi.ThreadContextStack"/>
+    </Cassandra>
+  </Appenders>
+  <Loggers>
+    <Logger name="org.apache.logging.log4j.cassandra" level="DEBUG">
+      <AppenderRef ref="Cassandra"/>
+    </Logger>
+    <Root level="ERROR"/>
+  </Loggers>
+</Configuration>
+----
+
+This example configuration uses the following table schema:
+
+[source,sql]
+----
+CREATE TABLE logs (
+    id timeuuid PRIMARY KEY,
+    timeid timeuuid,
+    message text,
+    level text,
+    marker text,
+    logger text,
+    timestamp timestamp,
+    mdc map<text,text>,
+    ndc list<text>
+);
+----
+
+[#ConsoleAppender]
+== ConsoleAppender
+
+As one might expect, the ConsoleAppender writes its output to either
+System.out or System.err with System.out being the default target. A
+Layout must be provided to format the LogEvent.
+
+.ConsoleAppender Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|filter |Filter |A Filter to determine if the event should be handled by
+this Appender. More than one Filter may be used by using a
+CompositeFilter.
+
+|layout |Layout |The Layout to use to format the LogEvent. If no layout
+is supplied the default pattern layout of "%m%n" will be used.
+
+|follow |boolean |Identifies whether the appender honors reassignments
+of System.out or System.err via System.setOut or System.setErr made
+after configuration. Note that the follow attribute cannot be used with
+Jansi on Windows. Cannot be used with `direct`.
+
+|direct |boolean |Write directly to `java.io.FileDescriptor` and bypass
+`java.lang.System.out/.err`. Can give up to 10x performance boost when
+the output is redirected to file or other process. Cannot be used with
+Jansi on Windows. Cannot be used with `follow`. Output will not respect
+`java.lang.System.setOut()/.setErr()` and may get intertwined with other
+output to `java.lang.System.out/.err` in a multi-threaded application.
+_New since 2.6.2. Be aware that this is a new addition, and it has only
+been tested with Oracle JVM on Linux and Windows so far._
+
+|name |String |The name of the Appender.
+
+|ignoreExceptions |boolean |The default is `true`, causing exceptions
+encountered while appending events to be internally logged and then
+ignored. When set to `false` exceptions will be propagated to the
+caller, instead. You must set this to `false` when wrapping this
+Appender in a link:#FailoverAppender[FailoverAppender].
+
+|target |String |Either "SYSTEM_OUT" or "SYSTEM_ERR". The default is
+"SYSTEM_OUT".
+|=======================================================================
+
+A typical Console configuration might look like:
+
+[source,prettyprint,linenums]
+----
+<?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">
+      <AppenderRef ref="STDOUT"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+[#FailoverAppender]
+== 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.
+
+.FailoverAppender Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|filter |Filter |A Filter to determine if the event should be handled by
+this Appender. More than one Filter may be used by using a
+CompositeFilter.
+
+|primary |String |The name of the primary Appender to use.
+
+|failovers |String[] |The names of the secondary Appenders to use.
+
+|name |String |The name of the Appender.
+
+|retryIntervalSeconds |integer |The number of seconds that should pass
+before retrying the primary Appender. The default is 60.
+
+|ignoreExceptions |boolean |The default is `true`, causing exceptions
+encountered while appending events to be internally logged and then
+ignored. When set to `false` exceptions will be propagated to the
+caller, instead.
+
+|target |String |Either "SYSTEM_OUT" or "SYSTEM_ERR". The default is
+"SYSTEM_ERR".
+|=======================================================================
+
+A Failover configuration might look like:
+
+[source,xml]
+----
+<?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"
+                 ignoreExceptions="false">
+      <PatternLayout>
+        <Pattern>%d %p %c{1.} [%t] %m%n</Pattern>
+      </PatternLayout>
+      <TimeBasedTriggeringPolicy />
+    </RollingFile>
+    <Console name="STDOUT" target="SYSTEM_OUT" ignoreExceptions="false">
+      <PatternLayout pattern="%m%n"/>
+    </Console>
+    <Failover name="Failover" primary="RollingFile">
+      <Failovers>
+        <AppenderRef ref="Console"/>
+      </Failovers>
+    </Failover>
+  </Appenders>
+  <Loggers>
+    <Root level="error">
+      <AppenderRef ref="Failover"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+[#FileAppender]
+== 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 web
+applications 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.
+
+.FileAppender Parameters
+[width="100%",cols="34%,33%,33%",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|append |boolean |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 records are written.
+
+|bufferedIO |boolean |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.
+
+|bufferSize |int |When bufferedIO is true, this is the buffer size, the
+default is 8192 bytes.
+
+|createOnDemand |boolean |The appender creates the file on-demand. The
+appender only creates the file when a log event passes all filters and
+is routed to this appender. Defaults to false.
+
+|filter |Filter |A Filter to determine if the event should be handled by
+this Appender. More than one Filter may be used by using a
+CompositeFilter.
+
+|fileName |String |The name of the file to write to. If the file, or any
+of its parent directories, do not exist, they will be created.
+
+|immediateFlush |boolean a|
+When set to true - the default, each write will be followed by a flush.
+This will guarantee the data is written to disk but could impact
+performance.
+
+Flushing after every write is only useful when using this appender with
+synchronous loggers. Asynchronous loggers and appenders will
+automatically flush at the end of a batch of events, even if
+immediateFlush is set to false. This also guarantees the data is written
+to disk but is more efficient.
+
+|layout |Layout |The Layout to use to format the LogEvent. If no layout
+is supplied the default pattern layout of "%m%n" will be used.
+
+|locking |boolean |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.
+
+|name |String |The name of the Appender.
+
+|ignoreExceptions |boolean |The default is `true`, causing exceptions
+encountered while appending events to be internally logged and then
+ignored. When set to `false` exceptions will be propagated to the
+caller, instead. You must set this to `false` when wrapping this
+Appender in a link:#FailoverAppender[FailoverAppender].
+
+|filePermissions |String a|
+File attribute permissions in POSIX format to apply whenever the file is
+created.
+
+Underlying files system shall support
+https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html[POSIX]
+file attribute view.
+
+Examples: `rw-------` or `rw-rw-rw-` etc...
+
+|fileOwner |String a|
+File owner to define whenever the file is created.
+
+Changing file's owner may be restricted for security reason and
+Operation not permitted IOException thrown. Only processes with an
+effective user ID equal to the user ID of the file or with appropriate
+privileges may change the ownership of a file if
+http://www.gnu.org/software/libc/manual/html_node/Options-for-Files.html[_POSIX_CHOWN_RESTRICTED]
+is in effect for path.
+
+Underlying files system shall support file
+https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/FileOwnerAttributeView.html[owner]
+attribute view.
+
+|fileGroup |String a|
+File group to define whenever the file is created.
+
+Underlying files system shall support
+https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html[POSIX]
+file attribute view.
+
+|=======================================================================
+
+Here is a sample File configuration:
+
+[source,xml]
+----
+<?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">
+      <AppenderRef ref="MyFile"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+[#FlumeAppender]
+== FlumeAppender
+
+_This is an optional component supplied in a separate jar._
+
+http://flume.apache.org/index.html[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 data store and then
+asynchronously send the events to Flume, similar to the embedded Flume
+Agent but without most of the Flume dependencies.
+
+Usage as an embedded agent will cause the messages to be directly passed
+to the Flume Channel and then control will be immediately returned to
+the application. All interaction with remote agents will occur
+asynchronously. Setting the "type" attribute to "Embedded" will force
+the use of the embedded agent. In addition, configuring agent properties
+in the appender configuration will also cause the embedded agent to be
+used.
+
+.FlumeAppender Parameters
+[width="100%",cols="34%,33%,33%",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|agents |Agent[] |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. The specification of agents and
+properties are mutually exclusive. If both are configured an error will
+result.
+
+|agentRetries |integer |The number of times the agent should be retried
+before failing to a secondary. This parameter is ignored when
+type="persistent" is specified (agents are tried once before failing to
+the next).
+
+|batchSize |integer |Specifies the number of events that should be sent
+as a batch. The default is 1. _This parameter only applies to the Flume
+Appender._
+
+|compress |boolean |When set to true the message body will be compressed
+using gzip
+
+|connectTimeoutMillis |integer |The number of milliseconds Flume will
+wait before timing out the connection.
+
+|dataDir |String |Directory where the Flume write ahead log should be
+written. Valid only when embedded is set to true and Agent elements are
+used instead of Property elements.
+
+|filter |Filter |A Filter to determine if the event should be handled by
+this Appender. More than one Filter may be used by using a
+CompositeFilter.
+
+|eventPrefix |String |The character string to prepend to each event
+attribute in order to distinguish it from MDC attributes. The default is
+an empty string.
+
+|flumeEventFactory |FlumeEventFactory |Factory that generates the Flume
+events from Log4j events. The default factory is the FlumeAvroAppender
+itself.
+
+|layout |Layout |The Layout to use to format the LogEvent. If no layout
+is specified RFC5424Layout will be used.
+
+|lockTimeoutRetries |integer |The number of times to retry if a
+LockConflictException occurs while writing to Berkeley DB. The default
+is 5.
+
+|maxDelayMillis |integer |The maximum number of milliseconds to wait for
+batchSize events before publishing the batch.
+
+|mdcExcludes |String |A comma separated list of mdc keys that should be
+excluded from the FlumeEvent. This is mutually exclusive with the
+mdcIncludes attribute.
+
+|mdcIncludes |String |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.
+
+|mdcRequired |String |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.
+
+|mdcPrefix |String |A string that should be prepended to each MDC key in
+order to distinguish it from event attributes. The default string is
+"mdc:".
+
+|name |String |The name of the Appender.
+
+|properties |Property[] a|
+One or more Property elements that are used to configure the Flume
+Agent. The properties must be configured without the agent name (the
+appender name is used for this) and no sources can be configured.
+Interceptors can be specified for the source using
+"sources.log4j-source.interceptors". All other Flume configuration
+properties are allowed. Specifying both Agent and Property elements will
+result in an error.
+
+When used to configure in Persistent mode the valid properties are:
+
+1.  "keyProvider" to specify the name of the plugin to provide the
+secret key for encryption.
+
+|requestTimeoutMillis |integer |The number of milliseconds Flume will
+wait before timing out the request.
+
+|ignoreExceptions |boolean |The default is `true`, causing exceptions
+encountered while appending events to be internally logged and then
+ignored. When set to `false` exceptions will be propagated to the
+caller, instead. You must set this to `false` when wrapping this
+Appender in a link:#FailoverAppender[FailoverAppender].
+
+|type |enumeration |One of "Avro", "Embedded", or "Persistent" to
+indicate which variation of the Appender is desired.
+|=======================================================================
+
+A sample FlumeAppender configuration that is configured with a primary
+and a secondary agent, compresses the body, and formats the body using
+the RFC5424Layout:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="warn" name="MyApp">
+  <Appenders>
+    <Flume name="eventLogger" 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">
+      <AppenderRef 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:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="warn" name="MyApp" packages="">
+  <Appenders>
+    <Flume name="eventLogger" 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">
+      <AppenderRef 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.
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="warn" name="MyApp" packages="">
+  <Appenders>
+    <Flume name="eventLogger" 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">
+      <AppenderRef ref="eventLogger"/>
+    </Logger>
+    <Root level="warn">
+      <AppenderRef 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.
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="error" name="MyApp" packages="">
+  <Appenders>
+    <Flume name="eventLogger" 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">
+      <AppenderRef ref="eventLogger"/>
+    </Logger>
+    <Root level="warn">
+      <AppenderRef ref="STDOUT"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+[#JDBCAppender]
+== JDBCAppender
+
+As of Log4j 2.11.0, JDBC support has moved from the existing module
+`logj-core` to the new module `log4j-jdbc`.
+
+The JDBCAppender writes log events to a relational database table using
+standard JDBC. It can be configured to obtain JDBC connections using a
+JNDI `DataSource` or a custom factory method. Whichever approach you
+take, it *_must_* be backed by a connection pool. Otherwise, logging
+performance will suffer greatly. If batch statements are supported by
+the configured JDBC driver and a `bufferSize` is configured to be a
+positive number, then log events will be batched. Note that as of Log4j
+2.8, there are two ways to configure log event to column mappings: the
+original `ColumnConfig` style that only allows strings and timestamps,
+and the new `ColumnMapping` plugin that uses Log4j's built-in type
+conversion to allow for more data types (this is the same plugin as in
+the <<CassandraAppender>>).
+
+To get off the ground quickly during development, an alternative to
+using a connection source based on JNDI is to use the non-pooling
+`DriverManager` connection source. This connection source uses a JDBC
+connection string, a user name, and a password. Optionally, you can also
+use properties.
+
+.JDBCAppender Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|name |String |_Required._ The name of the Appender.
+
+|ignoreExceptions |boolean |The default is `true`, causing exceptions
+encountered while appending events to be internally logged and then
+ignored. When set to `false` exceptions will be propagated to the
+caller, instead. You must set this to `false` when wrapping this
+Appender in a link:#FailoverAppender[FailoverAppender].
+
+|filter |Filter |A Filter to determine if the event should be handled by
+this Appender. More than one Filter may be used by using a
+CompositeFilter.
+
+|bufferSize |int |If an integer greater than 0, this causes the appender
+to buffer log events and flush whenever the buffer reaches this size.
+
+|connectionSource |ConnectionSource |_Required._ The connections source
+from which database connections should be retrieved.
+
+|tableName |String |_Required._ The name of the database table to insert
+log events into.
+
+|columnConfigs |ColumnConfig[] |_Required (and/or columnMappings)._
+Information about the columns that log event data should be inserted
+into and how to insert that data. This is represented with multiple
+`<Column>` elements.
+
+|columnMappings |ColumnMapping[] |_Required (and/or columnConfigs)._ A
+list of column mapping configurations. Each column must specify a column
+name. Each column can have a conversion type specified by its fully
+qualified class name. By default, the conversion type is `String`. If
+the configured type is assignment-compatible with
+link:../log4j-api/apidocs/org/apache/logging/log4j/util/ReadOnlyStringMap.html[`ReadOnlyStringMap`]
+/
+link:../log4j-api/apidocs/org/apache/logging/log4j/spi/ThreadContextMap.html[`ThreadContextMap`]
+or
+link:../log4j-api/apidocs/org/apache/logging/log4j/spi/ThreadContextStack.html[`ThreadContextStack`],
+then that column will be populated with the MDC or NDC respectively
+(this is database-specific how they handle inserting a `Map` or `List`
+value). If the configured type is assignment-compatible with
+`java.util.Date`, then the log timestamp will be converted to that
+configured date type. If the configured type is assignment-compatible
+with `java.sql.Clob` or `java.sql.NClob`, then the formatted event will
+be set as a Clob or NClob respectively (similar to the traditional
+ColumnConfig plugin). If a `literal` attribute is given, then its value
+will be used as is in the `INSERT` query without any escaping.
+Otherwise, the layout or pattern specified will be converted into the
+configured type and stored in that column.
+|=======================================================================
+
+When configuring the JDBCAppender, you must specify a `ConnectionSource`
+implementation from which the Appender gets JDBC connections. You must
+use exactly one of the following nested elements:
+
+* link:#JDBCDataSource[`<DataSource>`]: Uses JNDI.
+* link:#JDBCConnectionFactory[`<ConnectionFactory>`]: Points to a
+class-method pair to provide JDBC connections.
+* link:#JDBCDriverManager[`<DriverManager>`]: A quick and dirty way to
+get off the ground, no connection pooling.
+* link:#JDBCPoolingDriver[`<PoolingDriver>`]: Uses Apache Commons DBCP
+to provide connection pooling.
+
+[#JDBCDataSource]
+.DataSource Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|jndiName |String |_Required._ The full, prefixed JNDI name that the
+`javax.sql.DataSource` is bound to, such as
+`java:/comp/env/jdbc/LoggingDatabase`. The `DataSource` must be backed
+by a connection pool; otherwise, logging will be very slow.
+|=======================================================================
+
+[#JDBCConnectionFactory]
+.ConnectionFactory Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|class |Class |_Required._ The fully qualified name of a class
+containing a static factory method for obtaining JDBC connections.
+
+|method |Method |_Required._ The name of a static factory method for
+obtaining JDBC connections. This method must have no parameters and its
+return type must be either `java.sql.Connection` or `DataSource`. If the
+method returns `Connection`s, it must obtain them from a connection pool
+(and they will be returned to the pool when Log4j is done with them);
+otherwise, logging will be very slow. If the method returns a
+`DataSource`, the `DataSource` will only be retrieved once, and it must
+be backed by a connection pool for the same reasons.
+|=======================================================================
+
+[#JDBCDriverManager]
+.DriverManager Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|connectionString |String |_Required._ The driver-specific JDBC
+connection string.
+
+|userName |String |The database user name. You cannot specify both
+properties and a user name or password.
+
+|password |String |The database password. You cannot specify both
+properties and a user name or password.
+
+|driverClassName |String |The JDBC driver class name. Some old JDBC
+Driver can only be discovered by explicitly loading them by class name.
+
+|properties |Property[] |A list of properties. You cannot specify both
+properties and a user name or password.
+|=======================================================================
+
+[#JDBCPoolingDriver]
+.PoolingDriver Parameters (Apache Commons DBCP)
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|DriverManager parameters |DriverManager parameters |This connection
+source inherits all parameter from the DriverManager connection source.
+
+|poolName |String |The pool name used to pool JDBC Connections. Defaults
+to `example`. You can use the JDBC connection string prefix
+`jdbc:apache:commons:dbcp:` followed by the pool name if you want to use
+a pooled connection elsewhere. For example:
+`jdbc:apache:commons:dbcp:example`.
+|=======================================================================
+
+When configuring the JDBCAppender, use the nested `<Column>` elements to
+specify which columns in the table should be written to and how to write
+to them. The JDBCAppender uses this information to formulate a
+`PreparedStatement` to insert records without SQL injection
+vulnerability.
+
+.Column Parameters
+[width="100%",cols="34%,33%,33%",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|name |String |_Required._ The name of the database column.
+
+|pattern |String |Use this attribute to insert a value or values from
+the log event in this column using a `PatternLayout` pattern. Simply
+specify any legal pattern in this attribute. Either this attribute,
+`literal`, or `isEventTimestamp="true"` must be specified, but not more
+than one of these.
+
+|literal |String |Use this attribute to insert a literal value in this
+column. The value will be included directly in the insert SQL, without
+any quoting (which means that if you want this to be a string, your
+value should contain single quotes around it like this:
+`literal="'Literal String'"`). This is especially useful for databases
+that don't support identity columns. For example, if you are using
+Oracle you could specify `literal="NAME_OF_YOUR_SEQUENCE.NEXTVAL"` to
+insert a unique ID in an ID column. Either this attribute, `pattern`, or
+`isEventTimestamp="true"` must be specified, but not more than one of
+these.
+
+|parameter |String a|
+Use this attribute to insert an expression with a parameter marker '?'
+in this column. The value will be included directly in the insert SQL,
+without any quoting (which means that if you want this to be a string,
+your value should contain single quotes around it like this:
+
+`<ColumnMapping name="instant" parameter="TIMESTAMPADD('MILLISECOND', ?, 
TIMESTAMP '1970-01-01')"/>`
+
+You can only specify one of `literal` or `parameter`.
+
+|isEventTimestamp |boolean |Use this attribute to insert the event
+timestamp in this column, which should be a SQL datetime. The value will
+be inserted as a `java.sql.Types.TIMESTAMP`. Either this attribute
+(equal to `true`), `pattern`, or `isEventTimestamp` must be specified,
+but not more than one of these.
+
+|isUnicode |boolean |This attribute is ignored unless `pattern` is
+specified. If `true` or omitted (default), the value will be inserted as
+unicode (`setNString` or `setNClob`). Otherwise, the value will be
+inserted non-unicode (`setString` or `setClob`).
+
+|isClob |boolean |This attribute is ignored unless `pattern` is
+specified. Use this attribute to indicate that the column stores
+Character Large Objects (CLOBs). If `true`, the value will be inserted
+as a CLOB (`setClob` or `setNClob`). If `false` or omitted (default),
+the value will be inserted as a VARCHAR or NVARCHAR (`setString` or
+`setNString`).
+|=======================================================================
+
+.ColumnMapping Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|name |String |_Required._ The name of the database column.
+
+|pattern |String |Use this attribute to insert a value or values from
+the log event in this column using a `PatternLayout` pattern. Simply
+specify any legal pattern in this attribute. Either this attribute,
+`literal`, or `isEventTimestamp="true"` must be specified, but not more
+than one of these.
+
+|literal |String |Use this attribute to insert a literal value in this
+column. The value will be included directly in the insert SQL, without
+any quoting (which means that if you want this to be a string, your
+value should contain single quotes around it like this:
+`literal="'Literal String'"`). This is especially useful for databases
+that don't support identity columns. For example, if you are using
+Oracle you could specify `literal="NAME_OF_YOUR_SEQUENCE.NEXTVAL"` to
+insert a unique ID in an ID column. Either this attribute, `pattern`, or
+`isEventTimestamp="true"` must be specified, but not more than one of
+these.
+
+|layout |Layout |The Layout to format the LogEvent.
+
+|type |String |Conversion type name, a fully-qualified class name.
+|=======================================================================
+
+Here are a couple sample configurations for the JDBCAppender, as well as
+a sample factory implementation that uses Commons Pooling and Commons
+DBCP to pool database connections:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="error">
+  <Appenders>
+    <JDBC name="databaseAppender" tableName="dbo.application_log">
+      <DataSource jndiName="java:/comp/env/jdbc/LoggingDataSource" />
+      <Column name="eventDate" isEventTimestamp="true" />
+      <Column name="level" pattern="%level" />
+      <Column name="logger" pattern="%logger" />
+      <Column name="message" pattern="%message" />
+      <Column name="exception" pattern="%ex{full}" />
+    </JDBC>
+  </Appenders>
+  <Loggers>
+    <Root level="warn">
+      <AppenderRef ref="databaseAppender"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="error">
+  <Appenders>
+    <JDBC name="databaseAppender" tableName="LOGGING.APPLICATION_LOG">
+      <ConnectionFactory class="net.example.db.ConnectionFactory" 
method="getDatabaseConnection" />
+      <Column name="EVENT_ID" 
literal="LOGGING.APPLICATION_LOG_SEQUENCE.NEXTVAL" />
+      <Column name="EVENT_DATE" isEventTimestamp="true" />
+      <Column name="LEVEL" pattern="%level" />
+      <Column name="LOGGER" pattern="%logger" />
+      <Column name="MESSAGE" pattern="%message" />
+      <Column name="THROWABLE" pattern="%ex{full}" />
+    </JDBC>
+  </Appenders>
+  <Loggers>
+    <Root level="warn">
+      <AppenderRef ref="databaseAppender"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+[source,java]
+----
+package net.example.db;
+
+import java.sql.Connection;
+import java.sql.SQLException;
+import java.util.Properties;
+
+import javax.sql.DataSource;
+
+import org.apache.commons.dbcp.DriverManagerConnectionFactory;
+import org.apache.commons.dbcp.PoolableConnection;
+import org.apache.commons.dbcp.PoolableConnectionFactory;
+import org.apache.commons.dbcp.PoolingDataSource;
+import org.apache.commons.pool.impl.GenericObjectPool;
+
+public class ConnectionFactory {
+    private static interface Singleton {
+        final ConnectionFactory INSTANCE = new ConnectionFactory();
+    }
+
+    private final DataSource dataSource;
+
+    private ConnectionFactory() {
+        Properties properties = new Properties();
+        properties.setProperty("user", "logging");
+        properties.setProperty("password", "abc123"); // or get properties 
from some configuration file
+
+        GenericObjectPool<PoolableConnection> pool = new 
GenericObjectPool<PoolableConnection>();
+        DriverManagerConnectionFactory connectionFactory = new 
DriverManagerConnectionFactory(
+                "jdbc:mysql://example.org:3306/exampleDb", properties
+        );
+        new PoolableConnectionFactory(
+                connectionFactory, pool, null, "SELECT 1", 3, false, false, 
Connection.TRANSACTION_READ_COMMITTED
+        );
+
+        this.dataSource = new PoolingDataSource(pool);
+    }
+
+    public static Connection getDatabaseConnection() throws SQLException {
+        return Singleton.INSTANCE.dataSource.getConnection();
+    }
+}
+----
+
+This appender is link:messages.html#MapMessage[`MapMessage`]-aware.
+
+The following configuration uses a `MessageLayout` to indicate that the
+Appender should match the keys of a `MapMessage` to the names of
+`ColumnMapping`s when setting the values of the Appender's SQL INSERT
+statement. This let you insert rows for custom values in a database
+table based on a Log4j `MapMessage` instead of values from `LogEvent`s.
+
+[source,xml]
+----
+<Configuration status="debug">
+
+  <Appenders>
+    <Console name="STDOUT">
+      <PatternLayout pattern="%C{1.} %m %level MDC%X%n"/>
+    </Console>
+    <Jdbc name="databaseAppender" tableName="dsLogEntry" 
ignoreExceptions="false">
+      <DataSource jndiName="java:/comp/env/jdbc/TestDataSourceAppender" />
+      <ColumnMapping name="Id" />
+      <ColumnMapping name="ColumnA" />
+      <ColumnMapping name="ColumnB" />
+      <MessageLayout />
+    </Jdbc>
+  </Appenders>
+
+  <Loggers>
+    <Logger name="org.apache.logging.log4j.core.appender.db" level="debug" 
additivity="false">
+      <AppenderRef ref="databaseAppender" />
+    </Logger>
+
+    <Root level="fatal">
+      <AppenderRef ref="STDOUT"/>
+    </Root>
+  </Loggers>
+
+</Configuration>
+----
+
+[#JMSAppender]
+== JMSAppender
+
+[[JMSQueueAppender]] [[JMSTopicAppender]]
+As of Log4j 2.11.0, JPA support has moved from the existing module
+`logj-core` to the new module `log4j-jms`.
+
+The JMS Appender sends the formatted log event to a JMS Destination.
+
+Note that in Log4j 2.0, this appender was split into a JMSQueueAppender
+and a JMSTopicAppender. Starting in Log4j 2.1, these appenders were
+combined into the JMS Appender which makes no distinction between queues
+and topics. However, configurations written for 2.0 which use the
+`<JMSQueue/>` or `<JMSTopic/>` elements will continue to work with the
+new `<JMS/>` configuration element.
+
+.JMS Appender Parameters
+[cols=",,,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Default |Description
+|factoryBindingName |String |_Required_ |The name to locate in the
+Context that provides the
+https://download.oracle.com/javaee/5/api/javax/jms/ConnectionFactory.html[`ConnectionFactory`].
+This can be any subinterface of `ConnectionFactory` as well.
+
+|factoryName |String |_Required_ |The fully qualified class name that
+should be used to define the Initial Context Factory as defined in
+https://download.oracle.com/javase/7/docs/api/javax/naming/Context.html#INITIAL_CONTEXT_FACTORY[`INITIAL_CONTEXT_FACTORY`].
+If a factoryName is specified without a providerURL a warning message
+will be logged as this is likely to cause problems.
+
+|filter |Filter |null |A Filter to determine if the event should be
+handled by this Appender. More than one Filter may be used by using a
+CompositeFilter.
+
+|layout |Layout |_Required_ |The Layout to use to format the LogEvent.
+_New since 2.9, in previous versions SerializedLayout was default._
+
+|name |String |_Required_ |The name of the Appender.
+
+|password |String |null |The password to use to create the JMS
+connection.
+
+|providerURL |String |_Required_ |The URL of the provider to use as
+defined by
+https://download.oracle.com/javase/7/docs/api/javax/naming/Context.html#PROVIDER_URL[`PROVIDER_URL`].
+
+|destinationBindingName |String |_Required_ |The name to use to locate
+the
+https://download.oracle.com/javaee/5/api/javax/jms/Destination.html[`Destination`].
+This can be a `Queue` or `Topic`, and as such, the attribute names
+`queueBindingName` and `topicBindingName` are aliases to maintain
+compatibility with the Log4j 2.0 JMS appenders.
+
+|securityPrincipalName |String |null |The name of the identity of the
+Principal as specified by
+https://download.oracle.com/javase/7/docs/api/javax/naming/Context.html#SECURITY_PRINCIPAL[`SECURITY_PRINCIPAL`].
+If a securityPrincipalName is specified without securityCredentials a
+warning message will be logged as this is likely to cause problems.
+
+|securityCredentials |String |null |The security credentials for the
+principal as specified by
+https://download.oracle.com/javase/7/docs/api/javax/naming/Context.html#SECURITY_CREDENTIALS[`SECURITY_CREDENTIALS`].
+
+|ignoreExceptions |boolean |true |When `true`, exceptions caught while
+appending events are internally logged and then ignored. When `false`
+exceptions are propagated to the caller. You must set this to `false`
+when wrapping this Appender in a
+link:#FailoverAppender[FailoverAppender].
+
+|immediateFail |boolean |false |When set to true, log events will not
+wait to try to reconnect and will fail immediately if the JMS resources
+are not available. New in 2.9.
+
+|reconnectIntervalMillis |long |5000 |If set to a value greater than 0,
+after an error, the JMSManager will attempt to reconnect to the broker
+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 `ignoreExceptions` is set to `false`). New in 2.9.
+
+|urlPkgPrefixes |String |null |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
+https://download.oracle.com/javase/7/docs/api/javax/naming/Context.html#URL_PKG_PREFIXES[`URL_PKG_PREFIXES`].
+
+|userName |String |null |The user id used to create the JMS connection.
+|=======================================================================
+
+Here is a sample JMS Appender configuration:
+
+[source,prettyprint,linenums]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="warn" name="MyApp">
+  <Appenders>
+    <JMS name="jmsQueue" destinationBindingName="MyQueue"
+         factoryBindingName="MyQueueConnectionFactory">
+      <JsonLayout properties="true"/>
+    </JMS>
+  </Appenders>
+  <Loggers>
+    <Root level="error">
+      <AppenderRef ref="jmsQueue"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+To map your Log4j `MapMessage`s to JMS `javax.jms.MapMessage`s, set the
+layout of the appender to `MessageLayout` with `<MessageLayout />`
+(Since 2.9.):
+
+[source,prettyprint,linenums]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="warn" name="MyApp">
+  <Appenders>
+    <JMS name="jmsQueue" destinationBindingName="MyQueue"
+         factoryBindingName="MyQueueConnectionFactory">
+      <MessageLayout />
+    </JMS>
+  </Appenders>
+  <Loggers>
+    <Root level="error">
+      <AppenderRef ref="jmsQueue"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+[#JPAAppender]
+== JPAAppender
+
+As of Log4j 2.11.0, JPA support has moved from the existing module
+`logj-core` to the new module `log4j-jpa`.
+
+The JPAAppender writes log events to a relational database table using
+the Java Persistence API 2.1. It requires the API and a provider
+implementation be on the classpath. It also requires a decorated entity
+configured to persist to the table desired. The entity should either
+extend
+`org.apache.logging.log4j.core.appender.db.jpa.BasicLogEventEntity` (if
+you mostly want to use the default mappings) and provide at least an
+`@Id` property, or
+`org.apache.logging.log4j.core.appender.db.jpa.AbstractLogEventWrapperEntity`
+(if you want to significantly customize the mappings). See the Javadoc
+for these two classes for more information. You can also consult the
+source code of these two classes as an example of how to implement the
+entity.
+
+.JPAAppender Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|name |String |_Required._ The name of the Appender.
+
+|ignoreExceptions |boolean |The default is `true`, causing exceptions
+encountered while appending events to be internally logged and then
+ignored. When set to `false` exceptions will be propagated to the
+caller, instead. You must set this to `false` when wrapping this
+Appender in a link:#FailoverAppender[FailoverAppender].
+
+|filter |Filter |A Filter to determine if the event should be handled by
+this Appender. More than one Filter may be used by using a
+CompositeFilter.
+
+|bufferSize |int |If an integer greater than 0, this causes the appender
+to buffer log events and flush whenever the buffer reaches this size.
+
+|entityClassName |String |_Required._ The fully qualified name of the
+concrete LogEventWrapperEntity implementation that has JPA annotations
+mapping it to a database table.
+
+|persistenceUnitName |String |_Required._ The name of the JPA
+persistence unit that should be used for persisting log events.
+|=======================================================================
+
+Here is a sample configuration for the JPAAppender. The first XML sample
+is the Log4j configuration file, the second is the `persistence.xml`
+file. EclipseLink is assumed here, but any JPA 2.1 or higher provider
+will do. You should _always_ create a _separate_ persistence unit for
+logging, for two reasons. First, `<shared-cache-mode>` _must_ be set to
+"NONE," which is usually not desired in normal JPA usage. Also, for
+performance reasons the logging entity should be isolated in its own
+persistence unit away from all other entities and you should use a
+non-JTA data source. Note that your persistence unit _must_ also contain
+`<class>` elements for all of the
+`org.apache.logging.log4j.core.appender.db.jpa.converter` converter
+classes.
+
+[source,prettyprint,linenums,lang-xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="error">
+  <Appenders>
+    <JPA name="databaseAppender" persistenceUnitName="loggingPersistenceUnit"
+         entityClassName="com.example.logging.JpaLogEntity" />
+  </Appenders>
+  <Loggers>
+    <Root level="warn">
+      <AppenderRef ref="databaseAppender"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+[source,prettyprint,linenums,lang-xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence";
+             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+             xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence
+                                 
http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd";
+             version="2.1">
+
+  <persistence-unit name="loggingPersistenceUnit" 
transaction-type="RESOURCE_LOCAL">
+    <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
+    
<class>org.apache.logging.log4j.core.appender.db.jpa.converter.ContextMapAttributeConverter</class>
+    
<class>org.apache.logging.log4j.core.appender.db.jpa.converter.ContextMapJsonAttributeConverter</class>
+    
<class>org.apache.logging.log4j.core.appender.db.jpa.converter.ContextStackAttributeConverter</class>
+    
<class>org.apache.logging.log4j.core.appender.db.jpa.converter.ContextStackJsonAttributeConverter</class>
+    
<class>org.apache.logging.log4j.core.appender.db.jpa.converter.MarkerAttributeConverter</class>
+    
<class>org.apache.logging.log4j.core.appender.db.jpa.converter.MessageAttributeConverter</class>
+    
<class>org.apache.logging.log4j.core.appender.db.jpa.converter.StackTraceElementAttributeConverter</class>
+    
<class>org.apache.logging.log4j.core.appender.db.jpa.converter.ThrowableAttributeConverter</class>
+    <class>com.example.logging.JpaLogEntity</class>
+    <non-jta-data-source>jdbc/LoggingDataSource</non-jta-data-source>
+    <shared-cache-mode>NONE</shared-cache-mode>
+  </persistence-unit>
+
+</persistence>
+----
+
+[source,prettyprint,linenums,lang-java]
+----
+package com.example.logging;
+...
+@Entity
+@Table(name="application_log", schema="dbo")
+public class JpaLogEntity extends BasicLogEventEntity {
+    private static final long serialVersionUID = 1L;
+    private long id = 0L;
+
+    public TestEntity() {
+        super(null);
+    }
+    public TestEntity(LogEvent wrappedEvent) {
+        super(wrappedEvent);
+    }
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @Column(name = "id")
+    public long getId() {
+        return this.id;
+    }
+
+    public void setId(long id) {
+        this.id = id;
+    }
+
+    // If you want to override the mapping of any properties mapped in 
BasicLogEventEntity,
+    // just override the getters and re-specify the annotations.
+}
+----
+
+[source,prettyprint,linenums,lang-java]
+----
+package com.example.logging;
+...
+@Entity
+@Table(name="application_log", schema="dbo")
+public class JpaLogEntity extends AbstractLogEventWrapperEntity {
+    private static final long serialVersionUID = 1L;
+    private long id = 0L;
+
+    public TestEntity() {
+        super(null);
+    }
+    public TestEntity(LogEvent wrappedEvent) {
+        super(wrappedEvent);
+    }
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @Column(name = "logEventId")
+    public long getId() {
+        return this.id;
+    }
+
+    public void setId(long id) {
+        this.id = id;
+    }
+
+    @Override
+    @Enumerated(EnumType.STRING)
+    @Column(name = "level")
+    public Level getLevel() {
+        return this.getWrappedEvent().getLevel();
+    }
+
+    @Override
+    @Column(name = "logger")
+    public String getLoggerName() {
+        return this.getWrappedEvent().getLoggerName();
+    }
+
+    @Override
+    @Column(name = "message")
+    @Convert(converter = MyMessageConverter.class)
+    public Message getMessage() {
+        return this.getWrappedEvent().getMessage();
+    }
+    ...
+}
+----
+
+[#HttpAppender]
+== HttpAppender
+
+The HttpAppender sends log events over HTTP. A Layout must be provided
+to format the LogEvent.
+
+Will set the `Content-Type` header according to the layout. Additional
+headers can be specified with embedded Property elements.
+
+Will wait for response from server, and throw error if no 2xx response
+is received.
+
+Implemented with
+https://docs.oracle.com/javase/7/docs/api/java/net/HttpURLConnection.html[HttpURLConnection].
+
+.HttpAppender Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|name |String |The name of the Appender.
+
+|filter |Filter |A Filter to determine if the event should be handled by
+this Appender. More than one Filter may be used by using a
+CompositeFilter.
+
+|layout |Layout |The Layout to use to format the LogEvent.
+
+|Ssl |SslConfiguration |Contains the configuration for the KeyStore and
+TrustStore for https. Optional, uses Java runtime defaults if not
+specified. See link:#SSL[SSL]
+
+|verifyHostname |boolean |Whether to verify server hostname against
+certificate. Only valid for https. Optional, defaults to true
+
+|url |string |The URL to use. The URL scheme must be "http" or "https".
+
+|method |string |The HTTP method to use. Optional, default is "POST".
+
+|connectTimeoutMillis |integer |The connect timeout in milliseconds.
+Optional, default is 0 (infinite timeout).
+
+|readTimeoutMillis |integer |The socket read timeout in milliseconds.
+Optional, default is 0 (infinite timeout).
+
+|headers |Property[] |Additional HTTP headers to use. The values support
+link:lookups.html[lookups].
+
+|ignoreExceptions |boolean |The default is `true`, causing exceptions
+encountered while appending events to be internally logged and then
+ignored. When set to `false` exceptions will be propagated to the
+caller, instead. You must set this to `false` when wrapping this
+Appender in a link:#FailoverAppender[FailoverAppender].
+|=======================================================================
+
+Here is a sample HttpAppender configuration snippet:
+
+[source,prettyprint,linenums]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+  ...
+  <Appenders>
+    <Http name="Http" url="https://localhost:9200/test/log4j/";>
+      <Property name="X-Java-Runtime" value="$${java:runtime}" />
+      <JsonLayout properties="true"/>
+      <SSL>
+        <KeyStore   location="log4j2-keystore.jks" 
passwordEnvironmentVariable="KEYSTORE_PASSWORD"/>
+        <TrustStore location="truststore.jks"      
passwordFile="${sys:user.home}/truststore.pwd"/>
+      </SSL>
+    </Http>
+  </Appenders>
+----
+
+[#KafkaAppender]
+== KafkaAppender
+
+As of Log4j 2.11.0, https://kafka.apache.org/[Apache Kafka] support has
+moved from the existing module `logj-core` to the new module
+`log4j-kafka`.
+
+The KafkaAppender logs events to an https://kafka.apache.org/[Apache
+Kafka] topic. Each log event is sent as a Kafka record.
+
+.KafkaAppender Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|topic |String |The Kafka topic to use. Required.
+
+|key |String |The key that will be sent to Kafka with every message.
+Optional value defaulting to `null`. Any of the
+link:./lookups.html[Lookups]) can be included.
+
+|filter |Filter |A Filter to determine if the event should be handled by
+this Appender. More than one Filter may be used by using a
+CompositeFilter.
+
+|layout |Layout |The Layout to use to format the LogEvent. Required,
+there is no default. _New since 2.9, in previous versions <PatternLayout
+pattern="%m"/> was default._
+
+|name |String |The name of the Appender. Required.
+
+|ignoreExceptions |boolean |The default is `true`, causing exceptions
+encountered while appending events to be internally logged and then
+ignored. When set to `false` exceptions will be propagated to the
+caller, instead. You must set this to `false` when wrapping this
+Appender in a link:#FailoverAppender[FailoverAppender].
+
+|syncSend |boolean |The default is `true`, causing sends to block until
+the record has been acknowledged by the Kafka server. When set to
+`false` sends return immediately, allowing for lower latency and
+significantly higher throughput. _New since 2.8. Be aware that this is a
+new addition, and it has not been extensively tested. Any failure
+sending to Kafka will be reported as error to StatusLogger and the log
+event will be dropped (the ignoreExceptions parameter will not be
+effective). Log events may arrive out of order to the Kafka server._
+
+|properties |Property[] |You can set properties in
+http://kafka.apache.org/documentation.html#producerconfigs[Kafka
+producer properties]. You need to set the `bootstrap.servers` property,
+there are sensible default values for the others. Do not set the
+`value.serializer` nor `key.serializer` properties.
+|=======================================================================
+
+Here is a sample KafkaAppender configuration snippet:
+
+[source,prettyprint,linenums]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+  ...
+  <Appenders>
+    <Kafka name="Kafka" topic="log-test">
+      <PatternLayout pattern="%date %message"/>
+        <Property name="bootstrap.servers">localhost:9092</Property>
+    </Kafka>
+  </Appenders>
+----
+
+This appender is synchronous by default and will block until the record
+has been acknowledged by the Kafka server, timeout for this can be set
+with the `timeout.ms` property (defaults to 30 seconds). Wrap with
+http://logging.apache.org/log4j/2.x/manual/appenders.html#AsyncAppender[Async
+appender] and/or set syncSend to `false` to log asynchronously.
+
+This appender requires the http://kafka.apache.org/[Kafka client
+library]. Note that you need to use a version of the Kafka client
+library matching the Kafka server used.
+
+__Note:__Make sure to not let `org.apache.kafka` log to a Kafka appender
+on DEBUG level, since that will cause recursive logging:
+
+[source,prettyprint,linenums]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+  ...
+  <Loggers>
+    <Root level="DEBUG">
+      <AppenderRef ref="Kafka"/>
+    </Root>
+    <Logger name="org.apache.kafka" level="INFO" /> <!-- avoid recursive 
logging -->
+  </Loggers>
+----
+
+[#MemoryMappedFileAppender]
+== MemoryMappedFileAppender
+
+_New since 2.1. Be aware that this is a new addition, and although it
+has been tested on several platforms, it does not have as much track
+record as the other file appenders._
+
+The MemoryMappedFileAppender maps a part of the specified file into
+memory and writes log events to this memory, relying on the operating
+system's virtual memory manager to synchronize the changes to the
+storage device. The main benefit of using memory mapped files is I/O
+performance. Instead of making system calls to write to disk, this
+appender can simply change the program's local memory, which is orders
+of magnitude faster. Also, in most operating systems the memory region
+mapped actually is the kernel's
+http://en.wikipedia.org/wiki/Page_cache[page cache] (file cache),
+meaning that no copies need to be created in user space. (TODO:
+performance tests that compare performance of this appender to
+RandomAccessFileAppender and FileAppender.)
+
+There is some overhead with mapping a file region into memory,
+especially very large regions (half a gigabyte or more). The default
+region size is 32 MB, which should strike a reasonable balance between
+the frequency and the duration of remap operations. (TODO: performance
+test remapping various sizes.)
+
+Similar to the FileAppender and the RandomAccessFileAppender,
+MemoryMappedFileAppender uses a MemoryMappedFileManager to actually
+perform the file I/O. While MemoryMappedFileAppender from different
+Configurations cannot be shared, the MemoryMappedFileManagers can be if
+the Manager is accessible. For example, two web applications 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.
+
+.MemoryMappedFileAppender Parameters
+[width="100%",cols="34%,33%,33%",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|append |boolean |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 records are written.
+
+|fileName |String |The name of the file to write to. If the file, or any
+of its parent directories, do not exist, they will be created.
+
+|filters |Filter |A Filter to determine if the event should be handled
+by this Appender. More than one Filter may be used by using a
+CompositeFilter.
+
+|immediateFlush |boolean a|
+When set to true, each write will be followed by a call to
+http://docs.oracle.com/javase/7/docs/api/java/nio/MappedByteBuffer.html#force()[MappedByteBuffer.force()].
+This will guarantee the data is written to the storage device.
+
+The default for this parameter is `false`. This means that the data is
+written to the storage device even if the Java process crashes, but
+there may be data loss if the operating system crashes.
+
+Note that manually forcing a sync on every log event loses most of the
+performance benefits of using a memory mapped file.
+
+Flushing after every write is only useful when using this appender with
+synchronous loggers. Asynchronous loggers and appenders will
+automatically flush at the end of a batch of events, even if
+immediateFlush is set to false. This also guarantees the data is written
+to disk but is more efficient.
+
+|regionLength |int |The length of the mapped region, defaults to 32 MB
+(32 * 1024 * 1024 bytes). This parameter must be a value between 256 and
+1,073,741,824 (1 GB or 2^30); values outside this range will be adjusted
+to the closest valid value. Log4j will round the specified value up to
+the nearest power of two.
+
+|layout |Layout |The Layout to use to format the LogEvent. If no layout
+is supplied the default pattern layout of "%m%n" will be used.
+
+|name |String |The name of the Appender.
+
+|ignoreExceptions |boolean |The default is `true`, causing exceptions
+encountered while appending events to be internally logged and then
+ignored. When set to `false` exceptions will be propagated to the
+caller, instead. You must set this to `false` when wrapping this
+Appender in a link:#FailoverAppender[FailoverAppender].
+|=======================================================================
+
+Here is a sample MemoryMappedFile configuration:
+
+[source,prettyprint,linenums]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="warn" name="MyApp" packages="">
+  <Appenders>
+    <MemoryMappedFile name="MyFile" fileName="logs/app.log">
+      <PatternLayout>
+        <Pattern>%d %p %c{1.} [%t] %m%n</Pattern>
+      </PatternLayout>
+    </MemoryMappedFile>
+  </Appenders>
+  <Loggers>
+    <Root level="error">
+      <AppenderRef ref="MyFile"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+[#NoSQLAppender]
+== NoSQLAppender
+
+The NoSQLAppender writes log events to a NoSQL database using an
+internal lightweight provider interface. Provider implementations
+currently exist for MongoDB and Apache CouchDB, and writing a custom
+provider is quite simple.
+
+.NoSQLAppender Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|name |String |_Required._ The name of the Appender.
+
+|ignoreExceptions |boolean |The default is `true`, causing exceptions
+encountered while appending events to be internally logged and then
+ignored. When set to `false` exceptions will be propagated to the
+caller, instead. You must set this to `false` when wrapping this
+Appender in a link:#FailoverAppender[FailoverAppender].
+
+|filter |Filter |A Filter to determine if the event should be handled by
+this Appender. More than one Filter may be used by using a
+CompositeFilter.
+
+|bufferSize |int |If an integer greater than 0, this causes the appender
+to buffer log events and flush whenever the buffer reaches this size.
+
+|NoSqlProvider |NoSQLProvider<C extends NoSQLConnection<W, T extends
+NoSQLObject<W>>> |_Required._ The NoSQL provider that provides
+connections to the chosen NoSQL database.
+|=======================================================================
+
+You specify which NoSQL provider to use by specifying the appropriate
+configuration element within the `<NoSql>` element. The types currently
+supported are `<MongoDb>` and `<CouchDb>`. To create your own custom
+provider, read the JavaDoc for the `NoSQLProvider`, `NoSQLConnection`,
+and `NoSQLObject` classes and the documentation about creating Log4j
+plugins. We recommend you review the source code for the MongoDB and
+CouchDB providers as a guide for creating your own provider.
+
+The following example demonstrates how log events are persisted in NoSQL
+databases if represented in a JSON format:
+
+[source,prettyprint,lang-javascript]
+----
+{
+    "level": "WARN",
+    "loggerName": "com.example.application.MyClass",
+    "message": "Something happened that you might want to know about.",
+    "source": {
+        "className": "com.example.application.MyClass",
+        "methodName": "exampleMethod",
+        "fileName": "MyClass.java",
+        "lineNumber": 81
+    },
+    "marker": {
+        "name": "SomeMarker",
+        "parent" {
+            "name": "SomeParentMarker"
+        }
+    },
+    "threadName": "Thread-1",
+    "millis": 1368844166761,
+    "date": "2013-05-18T02:29:26.761Z",
+    "thrown": {
+        "type": "java.sql.SQLException",
+        "message": "Could not insert record. Connection lost.",
+        "stackTrace": [
+                { "className": "org.example.sql.driver.PreparedStatement$1", 
"methodName": "responder", "fileName": "PreparedStatement.java", "lineNumber": 
1049 },
+                { "className": "org.example.sql.driver.PreparedStatement", 
"methodName": "executeUpdate", "fileName": "PreparedStatement.java", 
"lineNumber": 738 },
+                { "className": "com.example.application.MyClass", 
"methodName": "exampleMethod", "fileName": "MyClass.java", "lineNumber": 81 },
+                { "className": "com.example.application.MainClass", 
"methodName": "main", "fileName": "MainClass.java", "lineNumber": 52 }
+        ],
+        "cause": {
+            "type": "java.io.IOException",
+            "message": "Connection lost.",
+            "stackTrace": [
+                { "className": "java.nio.channels.SocketChannel", 
"methodName": "write", "fileName": null, "lineNumber": -1 },
+                { "className": "org.example.sql.driver.PreparedStatement$1", 
"methodName": "responder", "fileName": "PreparedStatement.java", "lineNumber": 
1032 },
+                { "className": "org.example.sql.driver.PreparedStatement", 
"methodName": "executeUpdate", "fileName": "PreparedStatement.java", 
"lineNumber": 738 },
+                { "className": "com.example.application.MyClass", 
"methodName": "exampleMethod", "fileName": "MyClass.java", "lineNumber": 81 },
+                { "className": "com.example.application.MainClass", 
"methodName": "main", "fileName": "MainClass.java", "lineNumber": 52 }
+            ]
+        }
+    },
+    "contextMap": {
+        "ID": "86c3a497-4e67-4eed-9d6a-2e5797324d7b",
+        "username": "JohnDoe"
+    },
+    "contextStack": [
+        "topItem",
+        "anotherItem",
+        "bottomItem"
+    ]
+}
+----
+
+[#NoSQLAppenderMongoDB]
+== NoSQLAppenderMongoDB
+
+Starting with Log4 2.11.0, we provide two MongoDB modules:
+
+* `log4j-mongodb2` defines the configuration element
+link:#NoSQLAppenderMongoDB2[`MongoDb2`] matching the MongoDB Driver
+version 2.
+* `log4j-mongodb3` defines the configuration element
+link:#NoSQLAppenderMongoDB3[`MongoDb3`] matching the MongoDB Driver
+version 3.
+
+We no longer provide the module `log4j-mongodb`.
+
+The module `log4j-mongodb2` aliases the old configuration element
+`MongoDb` to link:#NoSQLAppenderMongoDB2[`MongoDb2`].
+
+[#NoSQLAppenderMongoDB2]
+== NoSQLAppenderMongoDB2
+
+This section details specializations of the
+link:#NoSQLAppender[NoSQLAppender] provider for MongoDB using the
+MongoDB driver version 2. The NoSQLAppender Appender writes log events
+to a NoSQL database using an internal lightweight provider interface.
+
+.MongoDB2 Provider Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|collectionName |String |_Required._ The name of the MongoDB collection
+to insert the events into.
+
+|writeConcernConstant |Field |By default, the MongoDB provider inserts
+records with the instructions `com.mongodb.WriteConcern.ACKNOWLEDGED`.
+Use this optional attribute to specify the name of a constant other than
+`ACKNOWLEDGED`.
+
+|writeConcernConstantClass |Class |If you specify
+`writeConcernConstant`, you can use this attribute to specify a class
+other than `com.mongodb.WriteConcern` to find the constant on (to create
+your own custom instructions).
+
+|factoryClassName |Class |To provide a connection to the MongoDB
+database, you can use this attribute and `factoryMethodName` to specify
+a class and static method to get the connection from. The method must
+return a `com.mongodb.DB` or a `com.mongodb.MongoClient`. If the `DB` is
+not authenticated, you must also specify a `username` and `password`. If
+you use the factory method for providing a connection, you must not
+specify the `databaseName`, `server`, or `port` attributes.
+
+|factoryMethodName |Method |See the documentation for attribute
+`factoryClassName`.
+
+|databaseName |String |If you do not specify a `factoryClassName` and
+`factoryMethodName` for providing a MongoDB connection, you must specify
+a MongoDB database name using this attribute. You must also specify a
+`username` and `password`. You can optionally also specify a `server`
+(defaults to localhost), and a `port` (defaults to the default MongoDB
+port).
+
+|server |String |See the documentation for attribute `databaseName`.
+
+|port |int |See the documentation for attribute `databaseName`.
+
+|username |String |See the documentation for attributes `databaseName`
+and `factoryClassName`.
+
+|password |String |See the documentation for attributes `databaseName`
+and `factoryClassName`.
+
+|capped |boolean |Enable support for
+https://docs.mongodb.com/manual/core/capped-collections/[capped
+collections]
+
+|collectionSize |int |Specify the size in bytes of the capped collection
+to use if enabled. The minimum size is 4096 bytes, and larger sizes will
+be increased to the nearest integer multiple of 256. See the capped
+collection documentation linked above for more information.
+|=======================================================================
+
+This appender is link:messages.html#MapMessage[MapMessage]-aware.
+
+Here are a few sample configurations for the NoSQLAppender and MongoDB2
+provider:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="error">
+  <Appenders>
+    <NoSql name="databaseAppender">
+      <MongoDb2 databaseName="applicationDb" collectionName="applicationLog" 
server="mongo.example.org"
+               username="loggingUser" password="abc123" />
+    </NoSql>
+  </Appenders>
+  <Loggers>
+    <Root level="warn">
+      <AppenderRef ref="databaseAppender"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="error">
+  <Appenders>
+    <NoSql name="databaseAppender">
+      <MongoDb2 collectionName="applicationLog" 
factoryClassName="org.example.db.ConnectionFactory"
+               factoryMethodName="getNewMongoClient" />
+    </NoSql>
+  </Appenders>
+  <Loggers>
+    <Root level="warn">
+      <AppenderRef ref="databaseAppender"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+Starting in Log4j version 2.11.0, the provider element name is
+`MongoDb2`. The name `MongoDb` is now a deprecated alias for `MongoDb2`.
+
+[#NoSQLAppenderMongoDB3]
+== NoSQLAppenderMongoDB3
+
+This section details specializations of the
+link:#NoSQLAppender[NoSQLAppender] provider for MongoDB using the
+MongoDB driver version 3. The NoSQLAppender Appender writes log events
+to a NoSQL database using an internal lightweight provider interface.
+
+.MongoDB3 Provider Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|collectionName |String |_Required._ The name of the MongoDB collection
+to insert the events into.
+
+|writeConcernConstant |Field |By default, the MongoDB provider inserts
+records with the instructions `com.mongodb.WriteConcern.ACKNOWLEDGED`.
+Use this optional attribute to specify the name of a constant other than
+`ACKNOWLEDGED`.
+
+|writeConcernConstantClass |Class |If you specify
+`writeConcernConstant`, you can use this attribute to specify a class
+other than `com.mongodb.WriteConcern` to find the constant on (to create
+your own custom instructions).
+
+|factoryClassName |Class |To provide a connection to the MongoDB
+database, you can use this attribute and `factoryMethodName` to specify
+a class and static method to get the connection from. The method must
+return a `com.mongodb.client.MongoDatabase` or a
+`com.mongodb.MongoClient`. If the `com.mongodb.client.MongoDatabase` is
+not authenticated, you must also specify a `username` and `password`. If
+you use the factory method for providing a connection, you must not
+specify the `databaseName`, `server`, or `port` attributes.
+
+|factoryMethodName |Method |See the documentation for attribute
+`factoryClassName`.
+
+|databaseName |String |If you do not specify a `factoryClassName` and
+`factoryMethodName` for providing a MongoDB connection, you must specify
+a MongoDB database name using this attribute. You must also specify a
+`username` and `password`. You can optionally also specify a `server`
+(defaults to localhost), and a `port` (defaults to the default MongoDB
+port).
+
+|server |String |See the documentation for attribute `databaseName`.
+
+|port |int |See the documentation for attribute `databaseName`.
+
+|username |String |See the documentation for attributes `databaseName`
+and `factoryClassName`.
+
+|password |String |See the documentation for attributes `databaseName`
+and `factoryClassName`.
+
+|capped |boolean |Enable support for
+https://docs.mongodb.com/manual/core/capped-collections/[capped
+collections]
+
+|collectionSize |int |Specify the size in bytes of the capped collection
+to use if enabled. The minimum size is 4096 bytes, and larger sizes will
+be increased to the nearest integer multiple of 256. See the capped
+collection documentation linked above for more information.
+|=======================================================================
+
+This appender is link:messages.html#MapMessage[MapMessage]-aware.
+
+Here are a few sample configurations for the NoSQLAppender and MongoDB3
+provider:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="error">
+  <Appenders>
+    <NoSql name="databaseAppender">
+      <MongoDb3 databaseName="applicationDb" collectionName="applicationLog" 
server="mongo.example.org"
+               username="loggingUser" password="abc123" />
+    </NoSql>
+  </Appenders>
+  <Loggers>
+    <Root level="warn">
+      <AppenderRef ref="databaseAppender"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="error">
+  <Appenders>
+    <NoSql name="databaseAppender">
+      <MongoDb3 collectionName="applicationLog" 
factoryClassName="org.example.db.ConnectionFactory"
+               factoryMethodName="getNewMongoClient" />
+    </NoSql>
+  </Appenders>
+  <Loggers>
+    <Root level="warn">
+      <AppenderRef ref="databaseAppender"/>
+    </Root>
+  </Loggers>
+</Configuration>
+----
+
+[#NoSQLAppenderCouchDB]
+== NoSQLAppenderCouchDB
+
+This section details specializations of the
+link:#NoSQLAppender[NoSQLAppender] provider for CouchDB. The
+NoSQLAppender writes log events to a NoSQL database using an internal
+lightweight provider interface.
+
+.CouchDB Provider Parameters
+[cols=",,",options="header",]
+|=======================================================================
+|Parameter Name |Type |Description
+|factoryClassName |Class |To provide a connection to the CouchDB
+database, you can use this attribute and `factoryMethodName` to specify
+a class and static method to get the connection from. The method must
+return a `org.lightcouch.CouchDbClient` or a
+`org.lightcouch.CouchDbProperties`. If you use the factory method for
+providing a connection, you must not specify the `databaseName`,
+`protocol`, `server`, `port`, `username`, or `password` attributes.
+
+|factoryMethodName |Method |See the documentation for attribute
+`factoryClassName`.
+
+|databaseName |String |If you do not specify a `factoryClassName` and
+`factoryMethodName` for providing a CouchDB connection, you must specify
+a CouchDB database name using this attribute. You must also specify a
+`username` and `password`. You can optionally also specify a `protocol`
+(defaults to http), `server` (defaults to localhost), and a `port`
+(defaults to 80 for http and 443 for https).
+
+|protocol |String |Must either be "http" or "https." See the
+documentation for attribute `databaseName`.
+
+|server |String |See the documentation for attribute `databaseName`.
+
+|port |int |See the documentation for attribute `databaseName`.
+
+|username |String |See the documentation for attributes `databaseName`.
+
+|password |String |See the documentation for attributes `databaseName`.
+|=======================================================================
+
+Here are a few sample configurations for the NoSQLAppender and CouchDB
+provider:
+
+[source,prettyprint,linenums,lang-xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="error">
+  <Appenders>
+    <NoSql name="databaseAppender">
+      <CouchDb databaseName="applicationDb" protocol="https" 
server="couch.example.org"
+               username="loggingUser" password="abc123" />
+    </NoSql>
+  </Appenders>
+  <Loggers>
+    <Root level="warn">
+      <AppenderRef ref="databaseAppender"/>
+    </Root>
+  </Loggers>
+</Configurat

<TRUNCATED>

Reply via email to