Log4j Core provides multiple appenders to send log events directly to your database.
Since relational databases and some NoSQL databases split data into columns, Log4j Core provides a reusable
ColumnMapping
configuration element to allow specifying the content of each column.
The Column Mapping element supports the following configuration properties:
ColumnMapping configuration attributes
| Attribute | Type | Default value | Description | ||
|---|---|---|---|---|---|
Required |
|||||
|
The name of the column. |
||||
Optional |
|||||
|
|
It specifies the Java type that will be stored in the column. If set to:
For any other value:
|
|||
|
|
Deprecated: since |
|||
|
If set, the value will be added directly in the insert statement of the database-specific query language.
|
||||
|
It specifies the database-specific parameter marker to use. Otherwise, the default parameter marker for the database language will be used.
|
||||
|
This is a shortcut configuration attribute to set the
nested |
||||
|
It specifies which key of a
|
||||
ColumnMapping nested elements
| Type | Multiplicity | Description |
|---|---|---|
zero or one |
Formats the value to store in the column. See manual/layouts.adoc for more information. |
An example column mapping might look like this:
- XML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/column-mapping.xml[
log4j2.xml]link:example$manual/appenders/database/column-mapping.xml[role=include]
- JSON
-
Snippet from an example {antora-examples-url}/manual/appenders/database/column-mapping.json[
log4j2.json]link:example$manual/appenders/database/column-mapping.json[role=include] - YAML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/column-mapping.yaml[
log4j2.yaml]link:example$manual/appenders/database/column-mapping.yaml[role=include] - Properties
-
Snippet from an example {antora-examples-url}/manual/appenders/database/column-mapping.properties[
log4j2.properties]link:example$manual/appenders/database/column-mapping.properties[role=include]
-
A database-specific expression is added literally to the
INSERTstatement. -
A manual/pattern-layout.adoc with the specified pattern is used for these columns. The
uuidcolumn is additionally converted into ajava.util.UUIDbefore being sent to the JDBC driver. -
Three special column types are replaced with the log event timestamp, context map, and context stack.
-
A manual/json-template-layout.adoc is used to format this column.
-
If the global layout of the appender returns a
MapMessage, the value for keyresourceIdwill be put into theresourcecolumn.
The Cassandra Appender writes its output to an Apache Cassandra database. The appender supports the following configuration properties:
| Attribute | Type | Default value | Description |
|---|---|---|---|
Required |
|||
|
The name of the Appender. |
||
Optional |
|||
|
|
Whether to use batch statements to write log messages to Cassandra. |
|
The batch type to use when using batched writes. |
|||
|
|
The number of log messages to buffer or batch before writing.
If |
|
|
The name of the Cassandra cluster to connect to. |
||
|
|
If |
|
String |
The name of the keyspace containing the table that log messages will be written to. |
||
|
|
The password to use (along with the username) to connect to Cassandra. |
|
|
|
The name of the table to write log messages to. |
|
|
|
|
Whether to use the configured |
|
|
The username to use to connect to Cassandra. By default, no username or password is used. |
|
|
|
|
Whether to use TLS/SSL to connect to Cassandra. This is |
| Type | Multiplicity | Description |
|---|---|---|
zero or one |
Allows filtering log events just before they are formatted and sent. See also appender filtering stage. |
|
one or more |
A list of column mapping configurations. The following database-specific restrictions apply:
|
|
one or more |
A list of Cassandra node addresses to connect to.
If absent, See Socket Addresses for the configuration syntax. |
Additional runtime dependencies are required for using the Cassandra Appender:
The address of the Cassandra server is specified using the SocketAddress element, which supports the following configuration options:
SocketAddress configuration attributes
| Attribute | Type | Default value | Description |
|---|---|---|---|
|
The host to connect to. |
||
|
|
The port to connect to. |
Here is an example Cassandra Appender configuration:
- XML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/cassandra.xml[
log4j2.xml]link:example$manual/appenders/database/cassandra.xml[role=include]
- JSON
-
Snippet from an example {antora-examples-url}/manual/appenders/database/cassandra.json[
log4j2.json]link:example$manual/appenders/database/cassandra.json[role=include] - YAML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/cassandra.yaml[
log4j2.yaml]link:example$manual/appenders/database/cassandra.yaml[role=include] - Properties
-
Snippet from an example {antora-examples-url}/manual/appenders/database/cassandra.properties[
log4j2.properties]link:example$manual/appenders/database/cassandra.properties[role=include]
-
Enables buffering. Messages are sent in batches of 10.
-
Multiple server addresses can be used.
-
An example of column mapping. See Column mapping for more details.
The example above uses the following table schema:
link:example$manual/appenders/database/cassandra.sql[role=include]The JDBCAppender writes log events to a relational database table using standard JDBC. It can be configured to get JDBC connections from different connection sources.
If batch statements are supported by the configured JDBC driver and
bufferSize
is configured to be a positive number, then log events will be batched.
|
Note
|
The appender gets a new connection for each batch of log events. The connection source must be backed by a connection pool, otherwise the performance will suffer greatly. |
| Attribute | Type | Default value | Description |
|---|---|---|---|
Required |
|||
|
The name of the Appender. |
||
|
The name of the table to use. |
||
Optional |
|||
|
|
The number of log messages to batch before writing.
If |
|
|
|
If |
|
|
|
When set to |
|
|
|
If set to a value greater than 0, after an error, the If the reconnecting fails then an exception will be thrown and can be caught by the application if
|
|
| Type | Multiplicity | Description |
|---|---|---|
zero or one |
Allows filtering log events just before they are formatted and sent. See also appender filtering stage. |
|
zero or more |
A list of column mapping configurations. The following database-specific restrictions apply:
Required, unless |
|
zero or more |
Deprecated: an older mechanism to define column mappings. |
|
one |
It specifies how to retrieve JDBC
See Connection Sources for more details. |
|
zero or one |
An optional
If supplied See Map Message handling for more details. |
When configuring the JDBC Appender, you must specify an implementation of
ConnectionSource
that the appender will use to get
Connection objects.
The following connection sources are available out-of-the-box:
This connection source uses JNDI to locate a JDBC
DataSource.
|
Important
|
As of Log4j |
DataSource configuration attributes
| Attribute | Type | Default value | Description |
|---|---|---|---|
It specifies the JNDI name of a JDBC
Only the Required |
This connection source can use any factory method. The method must:
-
Be
publicandstatic. -
Have an empty parameter list.
-
Return either
ConnectionorDataSource.
ConnectionFactory configuration attributes
| Attribute | Type | Default value | Description |
|---|---|---|---|
|
The fully qualified class name of the class containing the factory method. Required |
||
|
The name of the factory method. Required |
This connection source uses
DriverManager
to directly create connections using a JDBC
Driver.
|
Tip
|
This configuration source is useful during development, but we don’t recommend it in production. Unless the JDBC driver provides connection pooling, the performance of the appender will suffer. See |
DriverManager configuration attributes
| Attribute | Type | Default value | Description |
|---|---|---|---|
|
The driver-specific JDBC connection string. Required |
||
|
autodetected |
The fully qualified class name of the JDBC driver to use. JDBC 4.0 drivers can be automatically detected by |
|
|
The username to use to connect to the database. |
||
|
The password to use to connect to the database. |
DriverManager nested elements
| Type | Multiplicity | Description |
|---|---|---|
zero or more |
A list of key/value pairs to pass to If supplied, the |
The PoolingDriver uses
Apache Commons DBCP 2
to configure a JDBC connection pool.
PoolingDriver configuration attributes
| Attribute | Type | Default value | Description |
|---|---|---|---|
|
The driver-specific JDBC connection string. Required |
||
|
autodetected |
The fully qualified class name of the JDBC driver to use. JDBC 4.0 drivers can be automatically detected by |
|
|
The username to use to connect to the database. |
||
|
The password to use to connect to the database. |
||
|
|
PoolingDriver nested elements
| Type | Multiplicity | Description |
|---|---|---|
zero or more |
A list of key/value pairs to pass to If supplied, the |
|
zero or one |
Allows finely tuning the configuration of the DBCP 2 connection pool. The available parameters are the same as those provided by DBCP 2. See DBCP 2 configuration for more details. {plugin-reference-marker} Plugin reference for |
Additional runtime dependencies are required for using PoolingDriver:
If the optional nested element of type Layout<? Extends Message> is provided, log events containing messages of type
MapMessage
will be treated specially.
For each column mapping (except those containing literals) the source attribute will be used as key to the value in MapMessage that will be stored in column name.
Here is an example JDBC Appender configuration:
- XML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/jdbc.xml[
log4j2.xml]link:example$manual/appenders/database/jdbc.xml[role=include]
- JSON
-
Snippet from an example {antora-examples-url}/manual/appenders/database/jdbc.json[
log4j2.json]link:example$manual/appenders/database/jdbc.json[role=include] - YAML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/jdbc.yaml[
log4j2.yaml]link:example$manual/appenders/database/jdbc.yaml[role=include] - Properties
-
Snippet from an example {antora-examples-url}/manual/appenders/database/jdbc.properties[
log4j2.properties]link:example$manual/appenders/database/jdbc.properties[role=include]
-
Enables buffering. Messages are sent in batches of 10.
-
A
JNDIdata source is used. -
An example of column mapping. See Column mapping for more details.
The example above uses the following table schema:
link:example$manual/appenders/database/jdbc.sql[role=include]The JPA Appender writes log events to a relational database table using the Jakarta Persistence API 2.2. To use the appender, you need to:
-
configure your JPA persistence unit. See Persistence configuration below.
-
configure the JPA Appender. See Appender configuration below.
|
Important
|
Due to breaking changes in the underlying API, the JPA Appender cannot be used with Jakarta Persistence API 3.0 or later. |
To store log events using JPA, you need to implement a JPA Entity that extends the
AbstractLogEventWrapperEntity
class.
To help you with the implementation, Log4j provides a
BasicLogEventEntity
class that only lacks an identity field.
A simple AbstractLogEventWrapperEntity implementation might look like:
LogEventEntity.java]link:example$manual/appenders/database/LogEventEntity.java[role=include]For performance reasons, we recommend creating a separate persistence unit for logging. This allows you to optimize the unit for logging purposes. The definition of the persistence unit should look like the example below:
link:example$manual/appenders/database/persistence.xml[role=include]-
Specify you JPA provider.
-
A non-JTA source should be used for performance.
-
If your log event entity extends
BasicLogEventEntity, you need to declare these converters. -
Declare your log event entity.
-
Cache sharing should be set to
NONE.
The JPA appender supports these configuration options:
| Attribute | Type | Default value | Description |
|---|---|---|---|
Required |
|||
|
The name of the Appender. |
||
|
The name of the table to use. |
||
|
The name of the persistence unit to use. |
||
|
The fully qualified name of the entity class to use. The type must extend
|
||
Optional |
|||
|
|
The number of log messages to batch before writing.
If |
|
|
|
If |
|
| Type | Multiplicity | Description |
|---|---|---|
zero or one |
Allows filtering log events just before they are formatted and sent. See also appender filtering stage. |
Additional runtime dependencies are required for using the JPA Appender:
Using the persistence unit from section Persistence configuration, the JPA appender can be easily configured as:
- XML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/jpa.xml[
log4j2.xml]link:example$manual/appenders/database/jpa.xml[role=include]
- JSON
-
Snippet from an example {antora-examples-url}/manual/appenders/database/jpa.json[
log4j2.json]link:example$manual/appenders/database/jpa.json[role=include] - YAML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/jpa.yaml[
log4j2.yaml]link:example$manual/appenders/database/jpa.yaml[role=include] - Properties
-
Snippet from an example {antora-examples-url}/manual/appenders/database/jpa.properties[
log4j2.properties]link:example$manual/appenders/database/jpa.properties[role=include]
The NoSQL Appender writes log events to a document-oriented NoSQL database using an internal lightweight provider interface. It supports the following configuration options:
| Attribute | Type | Default value | Description |
|---|---|---|---|
Required |
|||
|
The name of the Appender. |
||
Optional |
|||
|
|
The number of log messages to batch before writing to the database.
If |
|
|
|
If |
|
| Type | Multiplicity | Description |
|---|---|---|
zero or one |
Allows filtering log events just before they are formatted and sent. See also appender filtering stage. |
|
Zero or more |
Adds a simple key/value field to the NoSQL object. The |
|
zero or one |
An optional
See Formatting for more details. |
This appender transforms log events into NoSQL documents in two ways:
-
If the optional
Layoutconfiguration element is provided, theMapMessagereturned by the layout will be converted into its NoSQL document. -
Otherwise, a default conversion will be applied. You enhance the format with additional top level key/value pairs using nested
KeyValuePairconfiguration elements.Click to see an example of default log event formatting
link:example$manual/appenders/database/nosql-log-event.json[role=include]
The NoSQL Appender only handles the conversion of log events into NoSQL documents, and it delegates database-specific tasks to a NoSQL provider.
NoSQL providers are Log4j plugins that implement the
NoSqlProvider
interface.
Log4j Core currently provides the following providers:
-
Multiple providers for different versions of the MongoDB database. See MongoDB Providers below for more details.
-
A provider for the Apache CouchDB database. See Apache CouchDB provider below for more details.
Starting with version 2.11.0, Log4j supplies providers for the MongoDB NoSQL database engine, based on the MongoDB synchronous Java driver. The choice of the provider to use depends on:
-
the major version of the MongoDB Java driver your application uses: Log4j supports all major versions starting from version 2.
-
the type of driver API used: either the Legacy API or the Modern API. See MongoDB documentation for the difference between APIs.
|
Note
|
The list of dependencies of your application provides a hint as to which driver API your application is using. If your application contains any one of these dependencies, it might use the Legacy API:
If you application only uses |
|
Warning
|
The version of the MongoDB Java driver is not the same as the version of the MongoDB server. See MongoDB compatibility matrix for more information. |
In order to use a Log4j MongoDB appender you need to add the following dependencies to your application:
| Driver version | Driver API | Log4j artifact | Notes |
|---|---|---|---|
|
Legacy |
Reached end-of-support. Last released version: |
|
Legacy |
Reached end-of-support. Last released version: |
||
|
Modern |
||
|
Modern |
|
Tip
|
If you are note sure, which implementation to choose, |
The MongoDb provider is based on the
current version of the MongoDB Java driver.
It supports the following configuration options:
| Attribute | Type | Default value | Description |
|---|---|---|---|
It specifies the connection URI used to reach the server. Required |
|||
|
It specifies the name of the database for the appender to use. The database name can also be specified in the connection URI.
If both are provided, this Required |
||
|
It specifies the name of the collection for the appender to use. For backward compatibility, the collection name can also be specified in the connection URI per Required |
||
|
|
If |
|
|
|
It specifies the capped collection size of bytes. |
Additional runtime dependencies are required to use the MongoDb provider:
The log4j-mongodb4 module is deprecated in favor of the current MongoDB provider.
It supports the following configuration attributes:
| Attribute | Type | Default value | Description |
|---|---|---|---|
It specifies the connection URI used to reach the server. Required |
|||
|
|
If |
|
|
|
It specifies the capped collection size of bytes. |
Additional runtime dependencies are required to use the MongoDb4 provider:
|
Warning
|
This provider is planned to be removed in the next major release! If you are using this library, please get in touch with the Log4j maintainers using the official support channels. |
The CouchDb Provider allows using the NoSQL Appender with an
Apache CouchDB database.
The provider can be configured by:
-
either providing some standard configuration attributes,
-
or providing a factory method.
| Attribute | Type | Default value | Description |
|---|---|---|---|
enumeration |
|
It specifies the protocol to use to connect to the server. Can be one of:
|
|
|
|
The host name of the CouchDB server. |
|
|
|
It specifies the TCP port to use. |
|
|
The name of the database to connect to. |
||
|
The username for authentication. |
||
|
The password for authentication. |
||
|
The fully qualified class name that contains a factory method that returns either a
The class must be public. |
||
|
The name of the factory method. The method:
|
||
Additional runtime dependencies are required to use the CouchDb provider:
To connect the NoSQL Appender to a MongoDB database, you only need to provide a connection string:
- XML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo.xml[
log4j2.xml]link:example$manual/appenders/database/nosql-mongo.xml[role=include]
- JSON
-
Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo.json[
log4j2.json]link:example$manual/appenders/database/nosql-mongo.json[role=include] - YAML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo.yaml[
log4j2.yaml]link:example$manual/appenders/database/nosql-mongo.yaml[role=include] - Properties
-
Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo.properties[
log4j2.properties]link:example$manual/appenders/database/nosql-mongo.properties[role=include]
|
Note
|
Make sure to not let
|
A similar configuration for an Apache CouchDB database looks like:
- XML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-couch.xml[
log4j2.xml]link:example$manual/appenders/database/nosql-couch.xml[role=include]
- JSON
-
Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-couch.json[
log4j2.json]link:example$manual/appenders/database/nosql-couch.json[role=include] - YAML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-couch.yaml[
log4j2.yaml]link:example$manual/appenders/database/nosql-couch.yaml[role=include] - Properties
-
Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-couch.properties[
log4j2.properties]link:example$manual/appenders/database/nosql-couch.properties[role=include]
You can define additional fields to the NoSQL document using KeyValuePair elements, for example:
- XML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo-keys.xml[
log4j2.xml]link:example$manual/appenders/database/nosql-mongo-keys.xml[role=include]
- JSON
-
Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo-keys.json[
log4j2.json]link:example$manual/appenders/database/nosql-mongo-keys.json[role=include] - YAML
-
Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo-keys.yaml[
log4j2.yaml]link:example$manual/appenders/database/nosql-mongo-keys.yaml[role=include] - Properties
-
Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo-keys.properties[
log4j2.properties]link:example$manual/appenders/database/nosql-mongo-keys.properties[role=include]
-
This lookup is evaluated at configuration time and gives the time when Log4j was most recently reconfigured.
-
This lookup is evaluated at runtime and gives the current date. See runtime lookup evaluation for more details.