ppkarwasz commented on code in PR #2790: URL: https://github.com/apache/logging-log4j2/pull/2790#discussion_r1701968960
########## src/site/antora/modules/ROOT/pages/manual/appenders/database.adoc: ########## @@ -0,0 +1,1505 @@ +//// + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// + += Database Appenders +:open-book: 📖 + +Log4j Core provides multiple appenders to send log events directly to your database. + +[#common-concerns] +== Common concerns + +[#ColumnMapping] +=== Column mapping + +Since relational databases and some NoSQL databases split data into columns, Log4j Core provides a reusable +link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/db/ColumnMapping.html[`ColumnMapping`] +configuration element to allow specifying the content of each column. + +The Column Mapping element supports the following configuration properties: + +[#attributes] +.Common configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[attr-name]]name +| `String` +| +| The name of the column. + +4+h| Optional + +| [[attr-columnType]]columnType +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| https://docs.oracle.com/javase/8/docs/api/java/lang/String.html[`String`] +a| +It specifies the Java type that will be stored in the column. + +If set to: + +`org.apache.logging.log4j.util.ReadOnlyStringMap`:: +`org.apache.logging.log4j.spi.ThreadContextMap`:: +The column will be filled with the contents of the log event's xref:manual/thread-context.adoc#mdc[context map]. + +`org.apache.logging.log4j.spi.ThreadContextStack`:: +The column will be filled with the contents of the log event's xref:manual/thread-context.adoc#ndc[context stack]. + +`java.util.Date`:: +The column will be filled with the log event's timestamp. + +For any other value: + +. The log event will be formatted using the <<element-Layout,nested `Layout`>>. +. The resulting `String` will be converted to the specified type using a +link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/convert/TypeConverter.html[`TypeConverter`]. +See the +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverter[plugin reference] +for a list of available type converters. + +| [[attr-type]]type +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| https://docs.oracle.com/javase/8/docs/api/java/lang/String.html[`String`] +| +**Deprecated**: since `2.21.0` use <<attr-columnType,`columnType`>> instead. + +| [[attr-literal]]literal +| `String` +| +a| +If set, the value will be added **directly** in the insert statement of the database-specific query language. + +[CAUTION] +==== +This value is added as-is, without any validation. +Never use user-provided data to determine its value. +==== + +| [[attr-parameter]]parameter +| `String` +| +a| +It specifies the database-specific parameter marker to use. +Otherwise, the default parameter marker for the database language will be used. + +[CAUTION] +==== +This value is added as-is, without any validation. +Never use user-provided data to determine its value. +==== + +| [[attr-pattern]]pattern +| `String` +| +| +This is a shortcut configuration attribute to set the +<<element-Layout,nested `Layout` element>> +to a xref:manual/pattern-layout.adoc[`PatternLayout`] +instance with the specified `pattern` property. + +| [[attr-source]]source +| `String` +| <<attr-name,`name`>> +a| +It specifies which key of a xref:manual/messages.adoc#MapMessage[`MapMessage`] will be stored in the column. +This attribute is used only if: + +* The <<element-Layout,nested `Layout` element>> +is a +link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MessageLayout.html[`MessageLayout`]. +* The message being logged is a `MapMessage` +|=== + +[#elements] +.Common nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[element-Layout]]xref:manual/layouts.adoc[`Layout`] +| zero or one +| +Formats the value to store in the column. + +See xref:manual/layouts.adoc[] for more information. + +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-ColumnMapping[Plugin reference for `ColumnMapping`] + +[#CassandraAppender] +== Cassandra Appender + +The Cassandra Appender writes its output to an +https://cassandra.apache.org/_/index.html[Apache Cassandra] +database. +The appender supports the following configuration properties: + +[#CassandraAppender-attributes] +.Cassandra Appender configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[CassandraAppender-attr-name]]name +| `String` +| +| The name of the Appender. + +4+h| Optional + +| [[CassandraAppender-attr-batched]]batched +| `boolean` +| `false` +| Whether to use batch statements to write log messages to Cassandra. + +| [[CassandraAppender-attr-batchType]]batchType +| https://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/BatchStatement.Type.html[BatchStatement.Type] +| https://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/BatchStatement.Type.html#LOGGED[`LOGGED`] +| The batch type to use when using batched writes. + +| [[CassandraAppender-attr-bufferSize]]bufferSize +| `int` +| `0` +| +The number of log messages to buffer or batch before writing. +If `0`, buffering is disabled. + +| [[CassandraAppender-attr-clusterName]]clusterName +| `String` +| +| The name of the Cassandra cluster to connect to. + +| [[CassandraAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +| [[CassandraAppender-attr-keyspace]]keyspace +| String +| +| The name of the keyspace containing the table that log messages will be written to. + +| 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` +| `false` +| Whether to use the configured `org.apache.logging.log4j.core.util.Clock` as a timestamp generator. + +| `username` +| `String` +| +| The username to use to connect to Cassandra. By default, no username or password is used. + +| useTls +| `boolean` +| `true` +| Whether to use TLS/SSL to connect to Cassandra. This is `false` by default. +|=== + +[#CassandraAppender-elements] +.Cassandra Appender nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[CassandraAppender-element-Filter]]xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. + +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. + +| [[CassandraAppender-element-ColumnMapping]]<<ColumnMapping,`ColumnMapping`>> +| one or more +a| +A list of <<ColumnMapping,column mapping>> configurations. +The following database-specific restrictions apply: + +* the <<attr-name,`name` attribute>> must be a valid +https://cassandra.apache.org/doc/stable/cassandra/cql/definitions.html#identifiers[CQL identifier]. +* the <<attr-literal,`literal` attribute>> must be a valid +https://cassandra.apache.org/doc/stable/cassandra/cql/definitions.html#terms[CQL term]. +* the <<attr-parameter,`parameter` attribute>> has a fixed value of `?`. + +| [[CassandraAppender-element-SocketAddress]]<<SocketAddress,`SocketAddress`>> +| one or more +| A list of Cassandra node addresses to connect to. +If absent, `localhost:9042` will be used. + +See <<SocketAddress>> for the configuration syntax. +|=== + +Additional runtime dependencies are required for using the Cassandra Appender: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-cassandra</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-cassandra' +---- + +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-cassandra_org-apache-logging-log4j-cassandra-CassandraAppender[{open-book} Plugin reference for `Cassandra`] + +[#SocketAddress] +=== Socket Addresses + +The address of the Cassandra server is specified using the `SocketAddress` element, which supports the following configuration options: + +[#SocketAddress-attributes] +.`SocketAddress` configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[SocketAddress-attr-host]]host +| https://docs.oracle.com/javase/8/docs/api/java/net/InetAddress.html[`InetAddress`] +| `localhost` +| The host to connect to. + +| [[SocketAddress-attr-port]]port +| `int` +| `0` +| The port to connect to. + +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-SocketAddress[{open-book} Plugin reference for `SocketAddress`] + +[#CassandraAppender-examples] +=== Configuration examples + +Here is an example Cassandra Appender 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> +); +---- + +[#JdbcAppender] +== JDBC Appender + +The JDBCAppender writes log events to a relational database table using standard JDBC. +It can be configured to get JDBC connections from different <<ConnectionSource,connection sources>>. + +If batch statements are supported by the configured JDBC driver and +<<JdbcAppender-attr-bufferSize,`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. +==== + +[#JdbcAppender-attributes] +.JDBC Appender configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[JdbcAppender-attr-name]]name +| `String` +| +| The name of the Appender. + +| [[JdbcAppender-attr-tableName]]tableName +| `String` +| +| The name of the table to use. + +4+h| Optional + +| [[JdbcAppender-attr-bufferSize]]bufferSize +| `int` +| `0` +| +The number of log messages to batch before writing. +If `0`, batching is disabled. + +| [[JdbcAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +| [[JdbcAppender-attr-immediateFail]]immediateFail +| `boolean` +| `false` +| +When set to `true`, log events will not wait to try to reconnect and will fail immediately if the JDBC resources are not available. + +| [[JdbcAppender-attr-reconnectIntervalMillis]]reconnectIntervalMillis +| `long` +| `5000` +| +If set to a value greater than 0, after an error, the `JdbcDatabaseManager` will attempt to reconnect to the database after waiting the specified number of milliseconds. + +If the reconnecting fails then an exception will be thrown and can be caught by the application if +<<JdbcAppender-attr-ignoreExceptions,`ignoreExceptions`>> +is set to `false`. +|=== + +[#JdbcAppender-elements] +.JDBC Appender nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[JdbcAppender-element-Filter]]xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. + +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. + +| [[JdbcAppender-element-ColumnMapping]]<<ColumnMapping,`ColumnMapping`>> +| zero or more +a| +A list of <<ColumnMapping,column mapping>> configurations. +The following database-specific restrictions apply: + +* the <<attr-name,`name` attribute>> must be a valid SQL identifier. +* the <<attr-literal,`literal` attribute>> must be a valid SQL term. +* the <<attr-parameter,`parameter` attribute>> must be a valid SQL term containing a `?` placeholder. + +**Required**, unless <<JdbcAppender-element-ColumnConfig,`ColumnConfig`>> is used. + +| [[JdbcAppender-element-ColumnConfig]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-ColumnConfig[`ColumnConfig`] +| zero or more +| **Deprecated**: an older mechanism to define <<JdbcAppender-element-ColumnMapping,column mappings>>. + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-ColumnConfig[{open-book} Plugin reference for `ColumnConfig`] + +| [[JdbcAppender-element-ConnectionSource]]<<ConnectionSource,`ConnectionSource`>> +| **one** +| +It specifies how to retrieve JDBC +https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html[`Connection`] +objects. + +See <<ConnectionSource>> for more details. + +| [[JdbcAppender-element-Layout]]<<JdbcAppender-MapMessage,`Layout`>> +| zero or one +| +An optional +link:../javadoc/log4j-core/org/apache/logging/log4j/core/Layout.html[`Layout<? extends Message>`] +implementation that formats a log event as +xref:manual/messages.adoc[log `Message`]. + +If supplied ``MapMessage``s will be treated in a special way. + +See <<JdbcAppender-MapMessage>> for more details. + +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-JdbcAppender[{open-book} Plugin reference for `JDBC`] + +[#ConnectionSource] +=== Connection Sources + +When configuring the JDBC Appender, you must specify an implementation of +link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/db/jdbc/ConnectionSource.html[`ConnectionSource`] +that the appender will use to get +https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html[`Connection`] objects. + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-ConnectionSource[{open-book} Plugin reference for `ConnectionSource`] + +The following connection sources are available out-of-the-box: + +[#DataSourceConnectionSource] +==== `DataSource` + +This connection source uses JNDI to locate a JDBC +https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[`DataSource`]. + +[IMPORTANT] +==== +As of Log4j `2.17.0` you need to enable the `DataSource` connection source **explicitly** by setting the +xref:manual/systemproperties.adoc#log4j2.enableJndiJdbc[`log4j2.enableJndiJdbc`] +configuration property to `true`. +==== + +[#DataSourceConnectionSource-attributes] +.`DataSource` configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[DataSourceConnectionSource-attr-jndiName]]jndiName +| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/naming/Name.html[`Name`] +| +| +It specifies the JNDI name of a JDBC +https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[`DataSource`]. + +Only the `java:` JNDI protocol is supported. + +**Required** +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-DataSourceConnectionSource[{open-book} Plugin reference for `DataSource`] + +[#FactoryMethodConnectionSource] +==== `ConnectionFactory` + +This connection source can use any factory method. +The method must: + +* Be `public` and `static`. +* Have an empty parameter list. +* Return either +https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html[`Connection`] +or +https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[`DataSource`]. + +[#FactoryMethodConnectionSource-attributes] +.`ConnectionFactory` configuration attributes +[cols="1m,2,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[FactoryMethodConnectionSource-attr-class]]class +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| +| +The fully qualified class name of the class containing the factory method. + +**Required** + +| [[FactoryMethodConnectionSource-attr-method]]method +| `String` +| +| +The name of the factory method. + +**Required** +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-FactoryMethodConnectionSource[{open-book} Plugin reference for `ConnectionFactory`] + +[#DriverManagerConnectionSource] +==== `DriverManager` + +This connection source uses +https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html[`DriverManager`] +to directly create connections using a JDBC +https://docs.oracle.com/javase/8/docs/api/java/sql/Driver.html[`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 <<PoolingDriverConnectionSource,`PoolingDriver`>> for a variant of this connection source that uses a connection pool. +==== + +[#DriverManagerConnectionSource-attributes] +.`DriverManager` configuration attributes +[cols="1m,2,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[DriverManagerConnectionSource-attr-connectionString]]connectionString +| `String` +| +| +The driver-specific JDBC connection string. + +**Required** + +| [[DriverManagerConnectionSource-attr-driverClassName]]driverClassName +| `String` +| _autodetected_ +| +The fully qualified class name of the JDBC driver to use. + +JDBC 4.0 drivers can be automatically detected by `DriverManager`. +See +https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html[`DriverManager`] +for more details. + +| [[DriverManagerConnectionSource-attr-userName]]userName +| `String` +| +| +The username to use to connect to the database. + +| [[DriverManagerConnectionSource-attr-password]]password +| `String` +| +| +The password to use to connect to the database. +|=== + +[#DriverManagerConnectionSource-elements] +.`DriverManager` nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[DriverManagerConnectionSource-element-Property]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Property[`Property`] +| zero or more +| +A list of key/value pairs to pass to `DriverManager`. + +If supplied, the <<DriverManagerConnectionSource-attr-userName,`userName`>> and <<DriverManagerConnectionSource-attr-password,`password`>> attributes will be ignored. +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-DriverManagerConnectionSource[{open-book} Plugin reference for `DriverManager`] + +[#PoolingDriverConnectionSource] +==== `PoolingDriver` + +The `PoolingDriver` uses +https://commons.apache.org/proper/commons-dbcp/[Apache Commons DBCP 2] +to configure a JDBC connection pool. + +[#PoolingDriverConnectionSource-attributes] +.`PoolingDriver` configuration attributes +[cols="1m,2,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[PoolingDriverConnectionSource-attr-connectionString]]connectionString +| `String` +| +| +The driver-specific JDBC connection string. + +**Required** + +| [[PoolingDriverConnectionSource-attr-driverClassName]]driverClassName +| `String` +| _autodetected_ +| +The fully qualified class name of the JDBC driver to use. + +JDBC 4.0 drivers can be automatically detected by `DriverManager`. +See +https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html[`DriverManager`] +for more details. + +| [[PoolingDriverConnectionSource-attr-userName]]userName +| `String` +| +| +The username to use to connect to the database. + +| [[PoolingDriverConnectionSource-attr-password]]password +| `String` +| +| +The password to use to connect to the database. + +| [[PoolingDriverConnectionSource-attr-poolName]]poolName +| `String` +| `example` +| + +|=== + +[#PoolingDriverConnectionSource-elements] +.`PoolingDriver` nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[PoolingDriverConnectionSource-element-Property]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Property[`Property`] +| zero or more +| +A list of key/value pairs to pass to `DriverManager`. + +If supplied, the <<DriverManagerConnectionSource-attr-userName,`userName`>> and <<DriverManagerConnectionSource-attr-password,`password`>> attributes will be ignored. + +| [[PoolingDriverConnectionSource-element-PoolingConnectionFactoryConfig]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-jdbc-dbcp2_org-apache-logging-log4j-core-appender-db-jdbc-PoolableConnectionFactoryConfig[`PoolableConnectionFactory`] +| 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 +https://commons.apache.org/proper/commons-dbcp/configuration.html[DBCP 2 configuration] for more details. + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-jdbc-dbcp2_org-apache-logging-log4j-core-appender-db-jdbc-PoolableConnectionFactoryConfig[{open-book} Plugin reference for `PoolableConnectionFactory`] +|=== + +Additional runtime dependencies are required for using `PoolingDriver`: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-jdbc-dbcp2</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-jdbc-dbcp2' +---- + +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-jdbc-dbcp2_org-apache-logging-log4j-core-appender-db-jdbc-PoolingDriverConnectionSource[{open-book} Plugin reference for `PoolingDriver`] + +[#JdbcAppender-MapMessage] +=== Map Message handling + +If the optional <<JdbcAppender-element-Layout,nested element of type `Layout<? Extends Message>`>> is provided, log events containing messages of type +xref:manual/messages.adoc#MapMessage[`MapMessage`] +will be treated specially. +For each <<ColumnMapping,column mapping>> (except those containing literals) the <<attr-source,`source`>> attribute will be used as key to the value in `MapMessage` that will be stored in column <<attr-name,`name`>>. + +[#JdbcAppender-examples] +=== Configuration examples + +Here are a couple of 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> +---- + +The following configuration uses no layout 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 lets you insert rows for custom values in a database table based on a Log4j `MapMessage` instead of values from `LogEvent`. + +[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" /> + </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> +---- + +[#JpaAppender] +== JPA Appender + +The JPA Appender writes log events to a relational database table using the +https://jakarta.ee/specifications/persistence/2.2/[Jakarta Persistence API 2.2]. +To use the appender, you need to: + +* configure your JPA persistence unit. +See <<JpaAppender-persistence>> below. +* configure the JPA Appender. +See <<JpaAppender-configuration>> below. + +[#JpaAppender-persistence] +=== Persistence configuration + +To store log events using JPA, you need to implement a JPA Entity that extends the +link:../javadoc/log4j-jpa/org/apache/logging/log4j/core/appender/db/jpa/AbstractLogEventWrapperEntity.html[`AbstractLogEventWrapperEntity`] +class. +To help you with the implementation, Log4j provides a +link:../javadoc/log4j-jpa/org/apache/logging/log4j/core/appender/db/jpa/BasicLogEventEntity.html[`BasicLogEventEntity`] +class that only lacks an identity field. + +A simple `AbstractLogEventWrapperEntity` implementation might look like: + +.Snippet from a {antora-examples-url}/manual/appenders/database/LogEventEntity.java[`LogEventEntity.java`] +[source,java] +---- +include::example$manual/appenders/database/LogEventEntity.java[tags=!setter;entity] +---- + +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: + +[source,xml] +---- +include::example$manual/appenders/database/persistence.xml[lines=1;18..-1] +---- + +<1> Specify you JPA provider. +<2> A non-JTA source should be used for performance. +<3> If your log event entity extends `BasicLogEventEntity`, you need to declare these converters. +<4> Declare your log event entity. +<5> Cache sharing should be set to `NONE`. + +[#JpaAppender-configuration] +=== Appender configuration + +The JPA appender supports these configuration options: + +[#JpaAppender-attributes] +.JPA Appender configuration attributes +[cols="1m,2,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[JpaAppender-attr-name]]name +| `String` +| +| The name of the Appender. + +| [[JpaAppender-attr-tableName]]tableName +| `String` +| +| The name of the table to use. + +| [[JpaAppender-attr-persistenceUnit]]persistenceUnitName +| `String` +| +| The name of the persistence unit to use. + +| [[JpaAppender-attr-entityClassName]]entityClassName +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| +| The fully qualified name of the entity class to use. + +The type must extend +link:../javadoc/log4j-jpa/org/apache/logging/log4j/core/appender/db/jpa/AbstractLogEventWrapperEntity.html[`AbstractLogEventWrapperEntity`]. + +4+h| Optional + +| [[JpaAppender-attr-bufferSize]]bufferSize +| `int` +| `0` +| +The number of log messages to batch before writing. +If `0`, batching is disabled. + +| [[JpaAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +|=== + +[#JpaAppender-elements] +.JPA Appender nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[JpaAppender-element-Filter]]xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. + +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. + +|=== + +Additional runtime dependencies are required for using the Cassandra Appender: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-jpa</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-jpa' +---- +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-jpa_org-apache-logging-log4j-core-appender-db-jpa-JpaAppender[{open-book} Plugin reference for `JPA`] + +[#JpaAppender-examples] +=== Configuration examples + +[source,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> +---- + +[#NoSqlAppender] +== NoSQL Appender + +The NoSQL Appender writes log events to a NoSQL database using an internal lightweight provider interface. +It supports the following configuration options + +[#NoSqlAppender-attributes] +.NoSQL Appender configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[NoSqlAppender-attr-name]]name +| `String` +| +| The name of the Appender. + +4+h| Optional + +| [[NoSqlAppender-attr-bufferSize]]bufferSize +| `int` +| `0` +| +The number of log messages to batch before writing to the database. +If `0`, batching is disabled. + +| [[NoSqlAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +|=== + +[#NoSqlAppender-elements] +.NoSQL Appender nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[NoSqlAppender-element-Filter]]xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. + +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. + +| [[NoSqlAppender-element-KeyValuePair]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-util-KeyValuePair[`KeyValuePair`] +| Zero or more +a| Adds a simple key/value field to the NoSQL object. + +The `value` attribute of the pair supports +xref:manual/configuration.adoc#lazy-property-substitution[runtime property substitution] +using the +xref:manual/lookups.adoc#event-context[current event as context]. + +| [[NoSqlAppender-element-Layout]]<<NoSqlAppender-formatting,`Layout`>> +| zero or one +| +An optional +link:../javadoc/log4j-core/org/apache/logging/log4j/core/Layout.html[`Layout<? extends MapMessage>`] +implementation that formats a log event as +xref:manual/messages.adoc#MapMessage[`MapMessage`]. + +See <<NoSqlAppender-formatting>> for more details. +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-nosql-NoSqlAppender[{open-book} Plugin reference for `NoSQL`] + +[#NoSqlAppender-formatting] +=== Formatting + +This appender transforms log events into JSON-like structures in two ways: + +* If the optional <<NoSqlAppender-element-Layout,`Layout`>> configuration element is provided, the +xref:manual/messages.adoc#MapMessage[`MapMessage`] returned by the layout will be converted into its JSON representation. +* Otherwise, a default conversion will be applied. +You enhance the format with additional top level key/value pairs using nested +<<NoSqlAppender-element-KeyValuePair,`KeyValuePair`>> configuration elements. ++ +.Click to see an example of default log event formatting +[%collapsible] +==== +[source,json] +---- +include::example$manual/appenders/database/nosql-log-event.json[] +---- +==== + +[#NoSqlProvider] +=== Providers + +The NoSQL Appender only handles the conversion of log events into NoSQL objects and delegates database-specific tasks to a NoSQL provider. +NoSQL providers are Log4j plugins that implement the +link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/nosql/NoSqlProvider.html[`NoSqlProvider`] +interface. +Log4j Core currently provides the following providers: + +* Multiple providers for different versions of the +https://www.mongodb.com/[MongoDB database]. +See <<NoSQLProvider-MongoDB>> below for more details. +* A provider for the +https://couchdb.apache.org/[Apache CouchDB database]. +See <<CouchDbProvider>> below for more details. + +[#NoSQLProvider-MongoDB] +=== MongoDB Providers + +Starting with version 2.11.0, Log4j supplies providers for the +https://www.mongodb.com/[MongoDB] +NoSQL database engine, based on the +https://www.mongodb.com/docs/drivers/java/sync/current/[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 https://www.mongodb.com/docs/drivers/java/sync/current/legacy/[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**: + +* `org.mongodb:mongo-java-driver` +* `org.mongodb:mongodb-driver-legacy` + +If you application only uses `org.mongodb:mongodb-driver-sync`, it uses the **Modern API**. +==== + +[WARNING] +==== +The version of the MongoDB Java driver is not the same as the version of the MongoDB server. +See +https://www.mongodb.com/docs/drivers/java/sync/current/compatibility/[MongoDB compatibility matrix] +for more information. +==== + +In order to use a Log4j MongoDB appender you need to add the following dependencies to your application: + +.MongoDB providers compatibility table +[cols="2,2,2,5"] +|=== +| Driver version | Driver API | Log4j artifact | Notes + +| `2.x` +| Legacy +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb2[`log4j-mongodb2`] +| Reached end-of-support. + +Last released version: `2.12.4` + +| [[NoSQLAppenderMongoDB3]]`3.x` +| Legacy +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb3[`log4j-mongodb3`] +| Reached end-of-support. + +Last released version: `2.23.1` + +| `4.x` +| Modern +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb4[`log4j-mongodb4`] +| + +| `5.x` or later +| Modern +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb[`log4j-mongodb`] +| +|=== + +[TIP] +==== +If you are note sure, which implementation to choose, `log4j-mongodb` is the recommended choice. +==== + +[#MongoDbProvider] +==== MongoDb Provider (current) + +The `MongoDb` provider is based on the +https://www.mongodb.com/docs/drivers/java/sync/current/[current version of the MongoDB Java driver]. +It supports the following configuration options: + +[#MongoDbProvider-attributes] +.MongoDb Provider configuration attributes +[cols="1m,1,2,5"] +|=== +| Attribute | Type | Default value | Description + +| [[MongoDbProvider-attr-connection]]connection +| https://mongodb.github.io/mongo-java-driver/5.1/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html[`ConnectionString`] +| +| +It specifies the connection URI used to reach the server. + +See +https://www.mongodb.com/docs/drivers/java/sync/current/fundamentals/connection/connect/#connection-uri[Connection URI documentation] +for its format. + +**Required** + +| [[MongoDbProvider-attr-capped]]capped +| `boolean` +| `false` +| +If `true`, a +https://www.mongodb.com/docs/manual/core/capped-collections/[capped collection] +will be used. + +| [[MongoDbProvider-attr-collectionSize]]collectionSize +| `long` +| `512 MiB` +| +It specifies the capped collection size of bytes. + +|=== + +Additional runtime dependencies are required to use the `MongoDb` provider: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-mongodb</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-mongodb' +---- +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-mongodb_org-apache-logging-log4j-mongodb-MongoDbProvider[{open-book} Plugin reference for `MongoDb`] + +[#MongoDb4Provider] +==== MongoDb4 Provider (deprecated) + +The `log4j-mongodb4` module is deprecated in favor of the <<MongoDbProvider,current `MongoDB` provider>>. +It supports the following configuration attributes: + +[#MongoDb4Provider-attributes] +.MongoDb4 provider configuration attributes +[cols="1m,1,2,5"] +|=== +| Attribute | Type | Default value | Description + +| [[MongoDb4Provider-attr-connection]]connection +| https://mongodb.github.io/mongo-java-driver/5.1/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html[`ConnectionString`] +| +| +It specifies the connection URI used to reach the server. + +See +https://www.mongodb.com/docs/drivers/java/sync/current/fundamentals/connection/connect/#connection-uri[Connection URI documentation] +for its format. + +**Required** + +| [[MongoDb4Provider-attr-capped]]capped +| `boolean` +| `false` +| +If `true`, a +https://www.mongodb.com/docs/manual/core/capped-collections/[capped collection] +will be used. + +| [[MongoDb4Provider-attr-collectionSize]]collectionSize +| `long` +| `512 MiB` +| +It specifies the capped collection size of bytes. + +|=== + +Additional runtime dependencies are required to use the `MongoDb4` provider: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-mongodb4</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-mongodb4' +---- +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-mongodb4_org-apache-logging-log4j-mongodb4-MongoDb4Provider[{open-book} Plugin reference for `MongoDb4`] + +[#CouchDbProvider] +=== Apache CouchDB provider + +The `CouchDb` Provider allows using the <<NoSqlAppender>> with an +https://couchdb.apache.org/[Apache CouchDB database]. +The provider can be configured by: + +* either providing some <<CouchDbProvider-attr-standard,standard configuration attributes>>, +* or providing a <<CouchDbProvider-attr-factory,factory method>>. + +[#CouchDbProvider-attributes] +.CouchDb provider configuration attributes +[cols="1m,1,2,5"] +|=== +| Attribute | Type | Default value | Description + + +4+h| [[CouchDbProvider-attr-standard]]Standard configuration attributes + +| [[CouchDbProvider-attr-protocol]]protocol +| _enumeration_ +| `http` +a| +It specifies the protocol to use to connect to the server. +Can be one of: + +* `http` +* `https` + +| [[CouchDbProvider-attr-server]]server +| `String` +| `localhost` +| +The host name of the CouchDB server. + +| [[CouchDbProvider-attr-port]]port +| `int` +a| +`80`:: for `http` +`443`:: for `https` +| +It specifies the TCP port to use. + +| [[CouchDbProvider-attr-databaseName]]databaseName +| `String` +| +| +The name of the database to connect to. + +| [[CouchDbProvider-attr-username]]username +| `String` +| +| +The username for authentication. + +| [[CouchDbProvider-attr-password]]password +| `String` +| +| +The password for authentication. + +4+h| [[CouchDbProvider-attr-factory]]Factory method configuration attributes + +| [[CouchDbProvider-attr-factoryClassName]]factoryClassName +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| +a| +The fully qualified class name that contains a factory method that returns either a +https://javadoc.io/static/org.lightcouch/lightcouch/0.2.0/org/lightcouch/CouchDbClient.html[`CouchDbClient`] +or +https://javadoc.io/static/org.lightcouch/lightcouch/0.2.0/org/lightcouch/CouchDbProperties.html[`CouchDbProperties`] +object. + +The class must be public. + +| [[CouchDbProvider-attr-factoryMethodName]]factoryMethodName +| `String` +| +a| +The name of the factory method. +The method: + +* Must be `public` and `static`. +* Have an empty parameter list. +* Returns either a +https://javadoc.io/static/org.lightcouch/lightcouch/0.2.0/org/lightcouch/CouchDbClient.html[`CouchDbClient`] +or +https://javadoc.io/static/org.lightcouch/lightcouch/0.2.0/org/lightcouch/CouchDbProperties.html[`CouchDbProperties`] +object. + +|=== + +Additional runtime dependencies are required to use the `CouchDb` provider: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-couchdb</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-couchdb' +---- +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-couchdb_org-apache-logging-log4j-couchdb-CouchDbProvider[{open-book} Plugin reference for `CouchDb`] + +[#NoSqlAppender-examples] +=== Configuration examples + +Here are a few sample configurations for the NoSQLAppender and MongoDB4 provider: + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> Review Comment: Fixed in https://github.com/apache/logging-log4j2/pull/2790/commits/fad8d7f8603086a8abaa44c0c9e2d1dd6d7524fe ########## src/site/antora/modules/ROOT/pages/manual/appenders/database.adoc: ########## @@ -0,0 +1,1505 @@ +//// + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// + += Database Appenders +:open-book: 📖 + +Log4j Core provides multiple appenders to send log events directly to your database. + +[#common-concerns] +== Common concerns + +[#ColumnMapping] +=== Column mapping + +Since relational databases and some NoSQL databases split data into columns, Log4j Core provides a reusable +link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/db/ColumnMapping.html[`ColumnMapping`] +configuration element to allow specifying the content of each column. + +The Column Mapping element supports the following configuration properties: + +[#attributes] +.Common configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[attr-name]]name +| `String` +| +| The name of the column. + +4+h| Optional + +| [[attr-columnType]]columnType +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| https://docs.oracle.com/javase/8/docs/api/java/lang/String.html[`String`] +a| +It specifies the Java type that will be stored in the column. + +If set to: + +`org.apache.logging.log4j.util.ReadOnlyStringMap`:: +`org.apache.logging.log4j.spi.ThreadContextMap`:: +The column will be filled with the contents of the log event's xref:manual/thread-context.adoc#mdc[context map]. + +`org.apache.logging.log4j.spi.ThreadContextStack`:: +The column will be filled with the contents of the log event's xref:manual/thread-context.adoc#ndc[context stack]. + +`java.util.Date`:: +The column will be filled with the log event's timestamp. + +For any other value: + +. The log event will be formatted using the <<element-Layout,nested `Layout`>>. +. The resulting `String` will be converted to the specified type using a +link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/convert/TypeConverter.html[`TypeConverter`]. +See the +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverter[plugin reference] +for a list of available type converters. + +| [[attr-type]]type +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| https://docs.oracle.com/javase/8/docs/api/java/lang/String.html[`String`] +| +**Deprecated**: since `2.21.0` use <<attr-columnType,`columnType`>> instead. + +| [[attr-literal]]literal +| `String` +| +a| +If set, the value will be added **directly** in the insert statement of the database-specific query language. + +[CAUTION] +==== +This value is added as-is, without any validation. +Never use user-provided data to determine its value. +==== + +| [[attr-parameter]]parameter +| `String` +| +a| +It specifies the database-specific parameter marker to use. +Otherwise, the default parameter marker for the database language will be used. + +[CAUTION] +==== +This value is added as-is, without any validation. +Never use user-provided data to determine its value. +==== + +| [[attr-pattern]]pattern +| `String` +| +| +This is a shortcut configuration attribute to set the +<<element-Layout,nested `Layout` element>> +to a xref:manual/pattern-layout.adoc[`PatternLayout`] +instance with the specified `pattern` property. + +| [[attr-source]]source +| `String` +| <<attr-name,`name`>> +a| +It specifies which key of a xref:manual/messages.adoc#MapMessage[`MapMessage`] will be stored in the column. +This attribute is used only if: + +* The <<element-Layout,nested `Layout` element>> +is a +link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MessageLayout.html[`MessageLayout`]. +* The message being logged is a `MapMessage` +|=== + +[#elements] +.Common nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[element-Layout]]xref:manual/layouts.adoc[`Layout`] +| zero or one +| +Formats the value to store in the column. + +See xref:manual/layouts.adoc[] for more information. + +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-ColumnMapping[Plugin reference for `ColumnMapping`] + +[#CassandraAppender] +== Cassandra Appender + +The Cassandra Appender writes its output to an +https://cassandra.apache.org/_/index.html[Apache Cassandra] +database. +The appender supports the following configuration properties: + +[#CassandraAppender-attributes] +.Cassandra Appender configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[CassandraAppender-attr-name]]name +| `String` +| +| The name of the Appender. + +4+h| Optional + +| [[CassandraAppender-attr-batched]]batched +| `boolean` +| `false` +| Whether to use batch statements to write log messages to Cassandra. + +| [[CassandraAppender-attr-batchType]]batchType +| https://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/BatchStatement.Type.html[BatchStatement.Type] +| https://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/BatchStatement.Type.html#LOGGED[`LOGGED`] +| The batch type to use when using batched writes. + +| [[CassandraAppender-attr-bufferSize]]bufferSize +| `int` +| `0` +| +The number of log messages to buffer or batch before writing. +If `0`, buffering is disabled. + +| [[CassandraAppender-attr-clusterName]]clusterName +| `String` +| +| The name of the Cassandra cluster to connect to. + +| [[CassandraAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +| [[CassandraAppender-attr-keyspace]]keyspace +| String +| +| The name of the keyspace containing the table that log messages will be written to. + +| 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` +| `false` +| Whether to use the configured `org.apache.logging.log4j.core.util.Clock` as a timestamp generator. + +| `username` +| `String` +| +| The username to use to connect to Cassandra. By default, no username or password is used. + +| useTls +| `boolean` +| `true` +| Whether to use TLS/SSL to connect to Cassandra. This is `false` by default. +|=== + +[#CassandraAppender-elements] +.Cassandra Appender nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[CassandraAppender-element-Filter]]xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. + +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. + +| [[CassandraAppender-element-ColumnMapping]]<<ColumnMapping,`ColumnMapping`>> +| one or more +a| +A list of <<ColumnMapping,column mapping>> configurations. +The following database-specific restrictions apply: + +* the <<attr-name,`name` attribute>> must be a valid +https://cassandra.apache.org/doc/stable/cassandra/cql/definitions.html#identifiers[CQL identifier]. +* the <<attr-literal,`literal` attribute>> must be a valid +https://cassandra.apache.org/doc/stable/cassandra/cql/definitions.html#terms[CQL term]. +* the <<attr-parameter,`parameter` attribute>> has a fixed value of `?`. + +| [[CassandraAppender-element-SocketAddress]]<<SocketAddress,`SocketAddress`>> +| one or more +| A list of Cassandra node addresses to connect to. +If absent, `localhost:9042` will be used. + +See <<SocketAddress>> for the configuration syntax. +|=== + +Additional runtime dependencies are required for using the Cassandra Appender: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-cassandra</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-cassandra' +---- + +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-cassandra_org-apache-logging-log4j-cassandra-CassandraAppender[{open-book} Plugin reference for `Cassandra`] + +[#SocketAddress] +=== Socket Addresses + +The address of the Cassandra server is specified using the `SocketAddress` element, which supports the following configuration options: + +[#SocketAddress-attributes] +.`SocketAddress` configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[SocketAddress-attr-host]]host +| https://docs.oracle.com/javase/8/docs/api/java/net/InetAddress.html[`InetAddress`] +| `localhost` +| The host to connect to. + +| [[SocketAddress-attr-port]]port +| `int` +| `0` +| The port to connect to. + +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-SocketAddress[{open-book} Plugin reference for `SocketAddress`] + +[#CassandraAppender-examples] +=== Configuration examples + +Here is an example Cassandra Appender 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> +); +---- + +[#JdbcAppender] +== JDBC Appender + +The JDBCAppender writes log events to a relational database table using standard JDBC. +It can be configured to get JDBC connections from different <<ConnectionSource,connection sources>>. + +If batch statements are supported by the configured JDBC driver and +<<JdbcAppender-attr-bufferSize,`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. +==== + +[#JdbcAppender-attributes] +.JDBC Appender configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[JdbcAppender-attr-name]]name +| `String` +| +| The name of the Appender. + +| [[JdbcAppender-attr-tableName]]tableName +| `String` +| +| The name of the table to use. + +4+h| Optional + +| [[JdbcAppender-attr-bufferSize]]bufferSize +| `int` +| `0` +| +The number of log messages to batch before writing. +If `0`, batching is disabled. + +| [[JdbcAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +| [[JdbcAppender-attr-immediateFail]]immediateFail +| `boolean` +| `false` +| +When set to `true`, log events will not wait to try to reconnect and will fail immediately if the JDBC resources are not available. + +| [[JdbcAppender-attr-reconnectIntervalMillis]]reconnectIntervalMillis +| `long` +| `5000` +| +If set to a value greater than 0, after an error, the `JdbcDatabaseManager` will attempt to reconnect to the database after waiting the specified number of milliseconds. + +If the reconnecting fails then an exception will be thrown and can be caught by the application if +<<JdbcAppender-attr-ignoreExceptions,`ignoreExceptions`>> +is set to `false`. +|=== + +[#JdbcAppender-elements] +.JDBC Appender nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[JdbcAppender-element-Filter]]xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. + +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. + +| [[JdbcAppender-element-ColumnMapping]]<<ColumnMapping,`ColumnMapping`>> +| zero or more +a| +A list of <<ColumnMapping,column mapping>> configurations. +The following database-specific restrictions apply: + +* the <<attr-name,`name` attribute>> must be a valid SQL identifier. +* the <<attr-literal,`literal` attribute>> must be a valid SQL term. +* the <<attr-parameter,`parameter` attribute>> must be a valid SQL term containing a `?` placeholder. + +**Required**, unless <<JdbcAppender-element-ColumnConfig,`ColumnConfig`>> is used. + +| [[JdbcAppender-element-ColumnConfig]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-ColumnConfig[`ColumnConfig`] +| zero or more +| **Deprecated**: an older mechanism to define <<JdbcAppender-element-ColumnMapping,column mappings>>. + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-ColumnConfig[{open-book} Plugin reference for `ColumnConfig`] + +| [[JdbcAppender-element-ConnectionSource]]<<ConnectionSource,`ConnectionSource`>> +| **one** +| +It specifies how to retrieve JDBC +https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html[`Connection`] +objects. + +See <<ConnectionSource>> for more details. + +| [[JdbcAppender-element-Layout]]<<JdbcAppender-MapMessage,`Layout`>> +| zero or one +| +An optional +link:../javadoc/log4j-core/org/apache/logging/log4j/core/Layout.html[`Layout<? extends Message>`] +implementation that formats a log event as +xref:manual/messages.adoc[log `Message`]. + +If supplied ``MapMessage``s will be treated in a special way. + +See <<JdbcAppender-MapMessage>> for more details. + +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-JdbcAppender[{open-book} Plugin reference for `JDBC`] + +[#ConnectionSource] +=== Connection Sources + +When configuring the JDBC Appender, you must specify an implementation of +link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/db/jdbc/ConnectionSource.html[`ConnectionSource`] +that the appender will use to get +https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html[`Connection`] objects. + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-ConnectionSource[{open-book} Plugin reference for `ConnectionSource`] + +The following connection sources are available out-of-the-box: + +[#DataSourceConnectionSource] +==== `DataSource` + +This connection source uses JNDI to locate a JDBC +https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[`DataSource`]. + +[IMPORTANT] +==== +As of Log4j `2.17.0` you need to enable the `DataSource` connection source **explicitly** by setting the +xref:manual/systemproperties.adoc#log4j2.enableJndiJdbc[`log4j2.enableJndiJdbc`] +configuration property to `true`. +==== + +[#DataSourceConnectionSource-attributes] +.`DataSource` configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[DataSourceConnectionSource-attr-jndiName]]jndiName +| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/naming/Name.html[`Name`] +| +| +It specifies the JNDI name of a JDBC +https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[`DataSource`]. + +Only the `java:` JNDI protocol is supported. + +**Required** +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-DataSourceConnectionSource[{open-book} Plugin reference for `DataSource`] + +[#FactoryMethodConnectionSource] +==== `ConnectionFactory` + +This connection source can use any factory method. +The method must: + +* Be `public` and `static`. +* Have an empty parameter list. +* Return either +https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html[`Connection`] +or +https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[`DataSource`]. + +[#FactoryMethodConnectionSource-attributes] +.`ConnectionFactory` configuration attributes +[cols="1m,2,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[FactoryMethodConnectionSource-attr-class]]class +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| +| +The fully qualified class name of the class containing the factory method. + +**Required** + +| [[FactoryMethodConnectionSource-attr-method]]method +| `String` +| +| +The name of the factory method. + +**Required** +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-FactoryMethodConnectionSource[{open-book} Plugin reference for `ConnectionFactory`] + +[#DriverManagerConnectionSource] +==== `DriverManager` + +This connection source uses +https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html[`DriverManager`] +to directly create connections using a JDBC +https://docs.oracle.com/javase/8/docs/api/java/sql/Driver.html[`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 <<PoolingDriverConnectionSource,`PoolingDriver`>> for a variant of this connection source that uses a connection pool. +==== + +[#DriverManagerConnectionSource-attributes] +.`DriverManager` configuration attributes +[cols="1m,2,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[DriverManagerConnectionSource-attr-connectionString]]connectionString +| `String` +| +| +The driver-specific JDBC connection string. + +**Required** + +| [[DriverManagerConnectionSource-attr-driverClassName]]driverClassName +| `String` +| _autodetected_ +| +The fully qualified class name of the JDBC driver to use. + +JDBC 4.0 drivers can be automatically detected by `DriverManager`. +See +https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html[`DriverManager`] +for more details. + +| [[DriverManagerConnectionSource-attr-userName]]userName +| `String` +| +| +The username to use to connect to the database. + +| [[DriverManagerConnectionSource-attr-password]]password +| `String` +| +| +The password to use to connect to the database. +|=== + +[#DriverManagerConnectionSource-elements] +.`DriverManager` nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[DriverManagerConnectionSource-element-Property]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Property[`Property`] +| zero or more +| +A list of key/value pairs to pass to `DriverManager`. + +If supplied, the <<DriverManagerConnectionSource-attr-userName,`userName`>> and <<DriverManagerConnectionSource-attr-password,`password`>> attributes will be ignored. +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-DriverManagerConnectionSource[{open-book} Plugin reference for `DriverManager`] + +[#PoolingDriverConnectionSource] +==== `PoolingDriver` + +The `PoolingDriver` uses +https://commons.apache.org/proper/commons-dbcp/[Apache Commons DBCP 2] +to configure a JDBC connection pool. + +[#PoolingDriverConnectionSource-attributes] +.`PoolingDriver` configuration attributes +[cols="1m,2,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[PoolingDriverConnectionSource-attr-connectionString]]connectionString +| `String` +| +| +The driver-specific JDBC connection string. + +**Required** + +| [[PoolingDriverConnectionSource-attr-driverClassName]]driverClassName +| `String` +| _autodetected_ +| +The fully qualified class name of the JDBC driver to use. + +JDBC 4.0 drivers can be automatically detected by `DriverManager`. +See +https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html[`DriverManager`] +for more details. + +| [[PoolingDriverConnectionSource-attr-userName]]userName +| `String` +| +| +The username to use to connect to the database. + +| [[PoolingDriverConnectionSource-attr-password]]password +| `String` +| +| +The password to use to connect to the database. + +| [[PoolingDriverConnectionSource-attr-poolName]]poolName +| `String` +| `example` +| + +|=== + +[#PoolingDriverConnectionSource-elements] +.`PoolingDriver` nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[PoolingDriverConnectionSource-element-Property]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Property[`Property`] +| zero or more +| +A list of key/value pairs to pass to `DriverManager`. + +If supplied, the <<DriverManagerConnectionSource-attr-userName,`userName`>> and <<DriverManagerConnectionSource-attr-password,`password`>> attributes will be ignored. + +| [[PoolingDriverConnectionSource-element-PoolingConnectionFactoryConfig]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-jdbc-dbcp2_org-apache-logging-log4j-core-appender-db-jdbc-PoolableConnectionFactoryConfig[`PoolableConnectionFactory`] +| 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 +https://commons.apache.org/proper/commons-dbcp/configuration.html[DBCP 2 configuration] for more details. + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-jdbc-dbcp2_org-apache-logging-log4j-core-appender-db-jdbc-PoolableConnectionFactoryConfig[{open-book} Plugin reference for `PoolableConnectionFactory`] +|=== + +Additional runtime dependencies are required for using `PoolingDriver`: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-jdbc-dbcp2</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-jdbc-dbcp2' +---- + +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-jdbc-dbcp2_org-apache-logging-log4j-core-appender-db-jdbc-PoolingDriverConnectionSource[{open-book} Plugin reference for `PoolingDriver`] + +[#JdbcAppender-MapMessage] +=== Map Message handling + +If the optional <<JdbcAppender-element-Layout,nested element of type `Layout<? Extends Message>`>> is provided, log events containing messages of type +xref:manual/messages.adoc#MapMessage[`MapMessage`] +will be treated specially. +For each <<ColumnMapping,column mapping>> (except those containing literals) the <<attr-source,`source`>> attribute will be used as key to the value in `MapMessage` that will be stored in column <<attr-name,`name`>>. + +[#JdbcAppender-examples] +=== Configuration examples + +Here are a couple of 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> +---- + +The following configuration uses no layout 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 lets you insert rows for custom values in a database table based on a Log4j `MapMessage` instead of values from `LogEvent`. + +[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" /> + </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> +---- + +[#JpaAppender] +== JPA Appender + +The JPA Appender writes log events to a relational database table using the +https://jakarta.ee/specifications/persistence/2.2/[Jakarta Persistence API 2.2]. +To use the appender, you need to: + +* configure your JPA persistence unit. +See <<JpaAppender-persistence>> below. +* configure the JPA Appender. +See <<JpaAppender-configuration>> below. + +[#JpaAppender-persistence] +=== Persistence configuration + +To store log events using JPA, you need to implement a JPA Entity that extends the +link:../javadoc/log4j-jpa/org/apache/logging/log4j/core/appender/db/jpa/AbstractLogEventWrapperEntity.html[`AbstractLogEventWrapperEntity`] +class. +To help you with the implementation, Log4j provides a +link:../javadoc/log4j-jpa/org/apache/logging/log4j/core/appender/db/jpa/BasicLogEventEntity.html[`BasicLogEventEntity`] +class that only lacks an identity field. + +A simple `AbstractLogEventWrapperEntity` implementation might look like: + +.Snippet from a {antora-examples-url}/manual/appenders/database/LogEventEntity.java[`LogEventEntity.java`] +[source,java] +---- +include::example$manual/appenders/database/LogEventEntity.java[tags=!setter;entity] +---- + +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: + +[source,xml] +---- +include::example$manual/appenders/database/persistence.xml[lines=1;18..-1] +---- + +<1> Specify you JPA provider. +<2> A non-JTA source should be used for performance. +<3> If your log event entity extends `BasicLogEventEntity`, you need to declare these converters. +<4> Declare your log event entity. +<5> Cache sharing should be set to `NONE`. + +[#JpaAppender-configuration] +=== Appender configuration + +The JPA appender supports these configuration options: + +[#JpaAppender-attributes] +.JPA Appender configuration attributes +[cols="1m,2,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[JpaAppender-attr-name]]name +| `String` +| +| The name of the Appender. + +| [[JpaAppender-attr-tableName]]tableName +| `String` +| +| The name of the table to use. + +| [[JpaAppender-attr-persistenceUnit]]persistenceUnitName +| `String` +| +| The name of the persistence unit to use. + +| [[JpaAppender-attr-entityClassName]]entityClassName +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| +| The fully qualified name of the entity class to use. + +The type must extend +link:../javadoc/log4j-jpa/org/apache/logging/log4j/core/appender/db/jpa/AbstractLogEventWrapperEntity.html[`AbstractLogEventWrapperEntity`]. + +4+h| Optional + +| [[JpaAppender-attr-bufferSize]]bufferSize +| `int` +| `0` +| +The number of log messages to batch before writing. +If `0`, batching is disabled. + +| [[JpaAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +|=== + +[#JpaAppender-elements] +.JPA Appender nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[JpaAppender-element-Filter]]xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. + +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. + +|=== + +Additional runtime dependencies are required for using the Cassandra Appender: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-jpa</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-jpa' +---- +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-jpa_org-apache-logging-log4j-core-appender-db-jpa-JpaAppender[{open-book} Plugin reference for `JPA`] + +[#JpaAppender-examples] +=== Configuration examples + +[source,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> +---- + +[#NoSqlAppender] +== NoSQL Appender + +The NoSQL Appender writes log events to a NoSQL database using an internal lightweight provider interface. +It supports the following configuration options + +[#NoSqlAppender-attributes] +.NoSQL Appender configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[NoSqlAppender-attr-name]]name +| `String` +| +| The name of the Appender. + +4+h| Optional + +| [[NoSqlAppender-attr-bufferSize]]bufferSize +| `int` +| `0` +| +The number of log messages to batch before writing to the database. +If `0`, batching is disabled. + +| [[NoSqlAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +|=== + +[#NoSqlAppender-elements] +.NoSQL Appender nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[NoSqlAppender-element-Filter]]xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. + +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. + +| [[NoSqlAppender-element-KeyValuePair]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-util-KeyValuePair[`KeyValuePair`] +| Zero or more +a| Adds a simple key/value field to the NoSQL object. + +The `value` attribute of the pair supports +xref:manual/configuration.adoc#lazy-property-substitution[runtime property substitution] +using the +xref:manual/lookups.adoc#event-context[current event as context]. + +| [[NoSqlAppender-element-Layout]]<<NoSqlAppender-formatting,`Layout`>> +| zero or one +| +An optional +link:../javadoc/log4j-core/org/apache/logging/log4j/core/Layout.html[`Layout<? extends MapMessage>`] +implementation that formats a log event as +xref:manual/messages.adoc#MapMessage[`MapMessage`]. + +See <<NoSqlAppender-formatting>> for more details. +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-nosql-NoSqlAppender[{open-book} Plugin reference for `NoSQL`] + +[#NoSqlAppender-formatting] +=== Formatting + +This appender transforms log events into JSON-like structures in two ways: + +* If the optional <<NoSqlAppender-element-Layout,`Layout`>> configuration element is provided, the +xref:manual/messages.adoc#MapMessage[`MapMessage`] returned by the layout will be converted into its JSON representation. +* Otherwise, a default conversion will be applied. +You enhance the format with additional top level key/value pairs using nested +<<NoSqlAppender-element-KeyValuePair,`KeyValuePair`>> configuration elements. ++ +.Click to see an example of default log event formatting +[%collapsible] +==== +[source,json] +---- +include::example$manual/appenders/database/nosql-log-event.json[] +---- +==== + +[#NoSqlProvider] +=== Providers + +The NoSQL Appender only handles the conversion of log events into NoSQL objects and delegates database-specific tasks to a NoSQL provider. +NoSQL providers are Log4j plugins that implement the +link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/nosql/NoSqlProvider.html[`NoSqlProvider`] +interface. +Log4j Core currently provides the following providers: + +* Multiple providers for different versions of the +https://www.mongodb.com/[MongoDB database]. +See <<NoSQLProvider-MongoDB>> below for more details. +* A provider for the +https://couchdb.apache.org/[Apache CouchDB database]. +See <<CouchDbProvider>> below for more details. + +[#NoSQLProvider-MongoDB] +=== MongoDB Providers + +Starting with version 2.11.0, Log4j supplies providers for the +https://www.mongodb.com/[MongoDB] +NoSQL database engine, based on the +https://www.mongodb.com/docs/drivers/java/sync/current/[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 https://www.mongodb.com/docs/drivers/java/sync/current/legacy/[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**: + +* `org.mongodb:mongo-java-driver` +* `org.mongodb:mongodb-driver-legacy` + +If you application only uses `org.mongodb:mongodb-driver-sync`, it uses the **Modern API**. +==== + +[WARNING] +==== +The version of the MongoDB Java driver is not the same as the version of the MongoDB server. +See +https://www.mongodb.com/docs/drivers/java/sync/current/compatibility/[MongoDB compatibility matrix] +for more information. +==== + +In order to use a Log4j MongoDB appender you need to add the following dependencies to your application: + +.MongoDB providers compatibility table +[cols="2,2,2,5"] +|=== +| Driver version | Driver API | Log4j artifact | Notes + +| `2.x` +| Legacy +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb2[`log4j-mongodb2`] +| Reached end-of-support. + +Last released version: `2.12.4` + +| [[NoSQLAppenderMongoDB3]]`3.x` +| Legacy +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb3[`log4j-mongodb3`] +| Reached end-of-support. + +Last released version: `2.23.1` + +| `4.x` +| Modern +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb4[`log4j-mongodb4`] +| + +| `5.x` or later +| Modern +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb[`log4j-mongodb`] +| +|=== + +[TIP] +==== +If you are note sure, which implementation to choose, `log4j-mongodb` is the recommended choice. +==== + +[#MongoDbProvider] +==== MongoDb Provider (current) + +The `MongoDb` provider is based on the +https://www.mongodb.com/docs/drivers/java/sync/current/[current version of the MongoDB Java driver]. +It supports the following configuration options: + +[#MongoDbProvider-attributes] +.MongoDb Provider configuration attributes +[cols="1m,1,2,5"] +|=== +| Attribute | Type | Default value | Description + +| [[MongoDbProvider-attr-connection]]connection +| https://mongodb.github.io/mongo-java-driver/5.1/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html[`ConnectionString`] +| +| +It specifies the connection URI used to reach the server. + +See +https://www.mongodb.com/docs/drivers/java/sync/current/fundamentals/connection/connect/#connection-uri[Connection URI documentation] +for its format. + +**Required** + +| [[MongoDbProvider-attr-capped]]capped +| `boolean` +| `false` +| +If `true`, a +https://www.mongodb.com/docs/manual/core/capped-collections/[capped collection] +will be used. + +| [[MongoDbProvider-attr-collectionSize]]collectionSize +| `long` +| `512 MiB` +| +It specifies the capped collection size of bytes. + +|=== + +Additional runtime dependencies are required to use the `MongoDb` provider: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-mongodb</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-mongodb' +---- +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-mongodb_org-apache-logging-log4j-mongodb-MongoDbProvider[{open-book} Plugin reference for `MongoDb`] + +[#MongoDb4Provider] +==== MongoDb4 Provider (deprecated) + +The `log4j-mongodb4` module is deprecated in favor of the <<MongoDbProvider,current `MongoDB` provider>>. +It supports the following configuration attributes: + +[#MongoDb4Provider-attributes] +.MongoDb4 provider configuration attributes +[cols="1m,1,2,5"] +|=== +| Attribute | Type | Default value | Description + +| [[MongoDb4Provider-attr-connection]]connection +| https://mongodb.github.io/mongo-java-driver/5.1/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html[`ConnectionString`] +| +| +It specifies the connection URI used to reach the server. + +See +https://www.mongodb.com/docs/drivers/java/sync/current/fundamentals/connection/connect/#connection-uri[Connection URI documentation] +for its format. + +**Required** + +| [[MongoDb4Provider-attr-capped]]capped +| `boolean` +| `false` +| +If `true`, a +https://www.mongodb.com/docs/manual/core/capped-collections/[capped collection] +will be used. + +| [[MongoDb4Provider-attr-collectionSize]]collectionSize +| `long` +| `512 MiB` +| +It specifies the capped collection size of bytes. + +|=== + +Additional runtime dependencies are required to use the `MongoDb4` provider: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-mongodb4</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-mongodb4' +---- +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-mongodb4_org-apache-logging-log4j-mongodb4-MongoDb4Provider[{open-book} Plugin reference for `MongoDb4`] + +[#CouchDbProvider] +=== Apache CouchDB provider + +The `CouchDb` Provider allows using the <<NoSqlAppender>> with an +https://couchdb.apache.org/[Apache CouchDB database]. +The provider can be configured by: + +* either providing some <<CouchDbProvider-attr-standard,standard configuration attributes>>, +* or providing a <<CouchDbProvider-attr-factory,factory method>>. + +[#CouchDbProvider-attributes] +.CouchDb provider configuration attributes +[cols="1m,1,2,5"] +|=== +| Attribute | Type | Default value | Description + + +4+h| [[CouchDbProvider-attr-standard]]Standard configuration attributes + +| [[CouchDbProvider-attr-protocol]]protocol +| _enumeration_ +| `http` +a| +It specifies the protocol to use to connect to the server. +Can be one of: + +* `http` +* `https` + +| [[CouchDbProvider-attr-server]]server +| `String` +| `localhost` +| +The host name of the CouchDB server. + +| [[CouchDbProvider-attr-port]]port +| `int` +a| +`80`:: for `http` +`443`:: for `https` +| +It specifies the TCP port to use. + +| [[CouchDbProvider-attr-databaseName]]databaseName +| `String` +| +| +The name of the database to connect to. + +| [[CouchDbProvider-attr-username]]username +| `String` +| +| +The username for authentication. + +| [[CouchDbProvider-attr-password]]password +| `String` +| +| +The password for authentication. + +4+h| [[CouchDbProvider-attr-factory]]Factory method configuration attributes + +| [[CouchDbProvider-attr-factoryClassName]]factoryClassName +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| +a| +The fully qualified class name that contains a factory method that returns either a +https://javadoc.io/static/org.lightcouch/lightcouch/0.2.0/org/lightcouch/CouchDbClient.html[`CouchDbClient`] +or +https://javadoc.io/static/org.lightcouch/lightcouch/0.2.0/org/lightcouch/CouchDbProperties.html[`CouchDbProperties`] +object. + +The class must be public. + +| [[CouchDbProvider-attr-factoryMethodName]]factoryMethodName +| `String` +| +a| +The name of the factory method. +The method: + +* Must be `public` and `static`. +* Have an empty parameter list. +* Returns either a +https://javadoc.io/static/org.lightcouch/lightcouch/0.2.0/org/lightcouch/CouchDbClient.html[`CouchDbClient`] +or +https://javadoc.io/static/org.lightcouch/lightcouch/0.2.0/org/lightcouch/CouchDbProperties.html[`CouchDbProperties`] +object. + +|=== + +Additional runtime dependencies are required to use the `CouchDb` provider: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-couchdb</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-couchdb' +---- +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-couchdb_org-apache-logging-log4j-couchdb-CouchDbProvider[{open-book} Plugin reference for `CouchDb`] + +[#NoSqlAppender-examples] +=== Configuration examples + +Here are a few sample configurations for the NoSQLAppender and MongoDB4 provider: + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<Configuration status="WARN"> + <Appenders> + <NoSql name="MongoDbAppender"> + <MongoDb connection="mongodb://log4jUser:12345678@localhost:${sys:MongoDBTestPort:-27017}/testDb.testCollection" /> + </NoSql> + </Appenders> + <Loggers> + <Root level="ALL"> + <AppenderRef ref="MongoDbAppender" /> + </Root> + </Loggers> +</Configuration> +---- + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> Review Comment: Fixed in https://github.com/apache/logging-log4j2/pull/2790/commits/fad8d7f8603086a8abaa44c0c9e2d1dd6d7524fe ########## src/site/antora/modules/ROOT/pages/manual/appenders/database.adoc: ########## @@ -0,0 +1,1505 @@ +//// + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// + += Database Appenders +:open-book: 📖 + +Log4j Core provides multiple appenders to send log events directly to your database. + +[#common-concerns] +== Common concerns + +[#ColumnMapping] +=== Column mapping + +Since relational databases and some NoSQL databases split data into columns, Log4j Core provides a reusable +link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/db/ColumnMapping.html[`ColumnMapping`] +configuration element to allow specifying the content of each column. + +The Column Mapping element supports the following configuration properties: + +[#attributes] +.Common configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[attr-name]]name +| `String` +| +| The name of the column. + +4+h| Optional + +| [[attr-columnType]]columnType +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| https://docs.oracle.com/javase/8/docs/api/java/lang/String.html[`String`] +a| +It specifies the Java type that will be stored in the column. + +If set to: + +`org.apache.logging.log4j.util.ReadOnlyStringMap`:: +`org.apache.logging.log4j.spi.ThreadContextMap`:: +The column will be filled with the contents of the log event's xref:manual/thread-context.adoc#mdc[context map]. + +`org.apache.logging.log4j.spi.ThreadContextStack`:: +The column will be filled with the contents of the log event's xref:manual/thread-context.adoc#ndc[context stack]. + +`java.util.Date`:: +The column will be filled with the log event's timestamp. + +For any other value: + +. The log event will be formatted using the <<element-Layout,nested `Layout`>>. +. The resulting `String` will be converted to the specified type using a +link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/convert/TypeConverter.html[`TypeConverter`]. +See the +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverter[plugin reference] +for a list of available type converters. + +| [[attr-type]]type +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| https://docs.oracle.com/javase/8/docs/api/java/lang/String.html[`String`] +| +**Deprecated**: since `2.21.0` use <<attr-columnType,`columnType`>> instead. + +| [[attr-literal]]literal +| `String` +| +a| +If set, the value will be added **directly** in the insert statement of the database-specific query language. + +[CAUTION] +==== +This value is added as-is, without any validation. +Never use user-provided data to determine its value. +==== + +| [[attr-parameter]]parameter +| `String` +| +a| +It specifies the database-specific parameter marker to use. +Otherwise, the default parameter marker for the database language will be used. + +[CAUTION] +==== +This value is added as-is, without any validation. +Never use user-provided data to determine its value. +==== + +| [[attr-pattern]]pattern +| `String` +| +| +This is a shortcut configuration attribute to set the +<<element-Layout,nested `Layout` element>> +to a xref:manual/pattern-layout.adoc[`PatternLayout`] +instance with the specified `pattern` property. + +| [[attr-source]]source +| `String` +| <<attr-name,`name`>> +a| +It specifies which key of a xref:manual/messages.adoc#MapMessage[`MapMessage`] will be stored in the column. +This attribute is used only if: + +* The <<element-Layout,nested `Layout` element>> +is a +link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MessageLayout.html[`MessageLayout`]. +* The message being logged is a `MapMessage` +|=== + +[#elements] +.Common nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[element-Layout]]xref:manual/layouts.adoc[`Layout`] +| zero or one +| +Formats the value to store in the column. + +See xref:manual/layouts.adoc[] for more information. + +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-ColumnMapping[Plugin reference for `ColumnMapping`] + +[#CassandraAppender] +== Cassandra Appender + +The Cassandra Appender writes its output to an +https://cassandra.apache.org/_/index.html[Apache Cassandra] +database. +The appender supports the following configuration properties: + +[#CassandraAppender-attributes] +.Cassandra Appender configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[CassandraAppender-attr-name]]name +| `String` +| +| The name of the Appender. + +4+h| Optional + +| [[CassandraAppender-attr-batched]]batched +| `boolean` +| `false` +| Whether to use batch statements to write log messages to Cassandra. + +| [[CassandraAppender-attr-batchType]]batchType +| https://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/BatchStatement.Type.html[BatchStatement.Type] +| https://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/BatchStatement.Type.html#LOGGED[`LOGGED`] +| The batch type to use when using batched writes. + +| [[CassandraAppender-attr-bufferSize]]bufferSize +| `int` +| `0` +| +The number of log messages to buffer or batch before writing. +If `0`, buffering is disabled. + +| [[CassandraAppender-attr-clusterName]]clusterName +| `String` +| +| The name of the Cassandra cluster to connect to. + +| [[CassandraAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +| [[CassandraAppender-attr-keyspace]]keyspace +| String +| +| The name of the keyspace containing the table that log messages will be written to. + +| 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` +| `false` +| Whether to use the configured `org.apache.logging.log4j.core.util.Clock` as a timestamp generator. + +| `username` +| `String` +| +| The username to use to connect to Cassandra. By default, no username or password is used. + +| useTls +| `boolean` +| `true` +| Whether to use TLS/SSL to connect to Cassandra. This is `false` by default. +|=== + +[#CassandraAppender-elements] +.Cassandra Appender nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[CassandraAppender-element-Filter]]xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. + +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. + +| [[CassandraAppender-element-ColumnMapping]]<<ColumnMapping,`ColumnMapping`>> +| one or more +a| +A list of <<ColumnMapping,column mapping>> configurations. +The following database-specific restrictions apply: + +* the <<attr-name,`name` attribute>> must be a valid +https://cassandra.apache.org/doc/stable/cassandra/cql/definitions.html#identifiers[CQL identifier]. +* the <<attr-literal,`literal` attribute>> must be a valid +https://cassandra.apache.org/doc/stable/cassandra/cql/definitions.html#terms[CQL term]. +* the <<attr-parameter,`parameter` attribute>> has a fixed value of `?`. + +| [[CassandraAppender-element-SocketAddress]]<<SocketAddress,`SocketAddress`>> +| one or more +| A list of Cassandra node addresses to connect to. +If absent, `localhost:9042` will be used. + +See <<SocketAddress>> for the configuration syntax. +|=== + +Additional runtime dependencies are required for using the Cassandra Appender: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-cassandra</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-cassandra' +---- + +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-cassandra_org-apache-logging-log4j-cassandra-CassandraAppender[{open-book} Plugin reference for `Cassandra`] + +[#SocketAddress] +=== Socket Addresses + +The address of the Cassandra server is specified using the `SocketAddress` element, which supports the following configuration options: + +[#SocketAddress-attributes] +.`SocketAddress` configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[SocketAddress-attr-host]]host +| https://docs.oracle.com/javase/8/docs/api/java/net/InetAddress.html[`InetAddress`] +| `localhost` +| The host to connect to. + +| [[SocketAddress-attr-port]]port +| `int` +| `0` +| The port to connect to. + +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-SocketAddress[{open-book} Plugin reference for `SocketAddress`] + +[#CassandraAppender-examples] +=== Configuration examples + +Here is an example Cassandra Appender 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> +); +---- + +[#JdbcAppender] +== JDBC Appender + +The JDBCAppender writes log events to a relational database table using standard JDBC. +It can be configured to get JDBC connections from different <<ConnectionSource,connection sources>>. + +If batch statements are supported by the configured JDBC driver and +<<JdbcAppender-attr-bufferSize,`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. +==== + +[#JdbcAppender-attributes] +.JDBC Appender configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[JdbcAppender-attr-name]]name +| `String` +| +| The name of the Appender. + +| [[JdbcAppender-attr-tableName]]tableName +| `String` +| +| The name of the table to use. + +4+h| Optional + +| [[JdbcAppender-attr-bufferSize]]bufferSize +| `int` +| `0` +| +The number of log messages to batch before writing. +If `0`, batching is disabled. + +| [[JdbcAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +| [[JdbcAppender-attr-immediateFail]]immediateFail +| `boolean` +| `false` +| +When set to `true`, log events will not wait to try to reconnect and will fail immediately if the JDBC resources are not available. + +| [[JdbcAppender-attr-reconnectIntervalMillis]]reconnectIntervalMillis +| `long` +| `5000` +| +If set to a value greater than 0, after an error, the `JdbcDatabaseManager` will attempt to reconnect to the database after waiting the specified number of milliseconds. + +If the reconnecting fails then an exception will be thrown and can be caught by the application if +<<JdbcAppender-attr-ignoreExceptions,`ignoreExceptions`>> +is set to `false`. +|=== + +[#JdbcAppender-elements] +.JDBC Appender nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[JdbcAppender-element-Filter]]xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. + +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. + +| [[JdbcAppender-element-ColumnMapping]]<<ColumnMapping,`ColumnMapping`>> +| zero or more +a| +A list of <<ColumnMapping,column mapping>> configurations. +The following database-specific restrictions apply: + +* the <<attr-name,`name` attribute>> must be a valid SQL identifier. +* the <<attr-literal,`literal` attribute>> must be a valid SQL term. +* the <<attr-parameter,`parameter` attribute>> must be a valid SQL term containing a `?` placeholder. + +**Required**, unless <<JdbcAppender-element-ColumnConfig,`ColumnConfig`>> is used. + +| [[JdbcAppender-element-ColumnConfig]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-ColumnConfig[`ColumnConfig`] +| zero or more +| **Deprecated**: an older mechanism to define <<JdbcAppender-element-ColumnMapping,column mappings>>. + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-ColumnConfig[{open-book} Plugin reference for `ColumnConfig`] + +| [[JdbcAppender-element-ConnectionSource]]<<ConnectionSource,`ConnectionSource`>> +| **one** +| +It specifies how to retrieve JDBC +https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html[`Connection`] +objects. + +See <<ConnectionSource>> for more details. + +| [[JdbcAppender-element-Layout]]<<JdbcAppender-MapMessage,`Layout`>> +| zero or one +| +An optional +link:../javadoc/log4j-core/org/apache/logging/log4j/core/Layout.html[`Layout<? extends Message>`] +implementation that formats a log event as +xref:manual/messages.adoc[log `Message`]. + +If supplied ``MapMessage``s will be treated in a special way. + +See <<JdbcAppender-MapMessage>> for more details. + +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-JdbcAppender[{open-book} Plugin reference for `JDBC`] + +[#ConnectionSource] +=== Connection Sources + +When configuring the JDBC Appender, you must specify an implementation of +link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/db/jdbc/ConnectionSource.html[`ConnectionSource`] +that the appender will use to get +https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html[`Connection`] objects. + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-ConnectionSource[{open-book} Plugin reference for `ConnectionSource`] + +The following connection sources are available out-of-the-box: + +[#DataSourceConnectionSource] +==== `DataSource` + +This connection source uses JNDI to locate a JDBC +https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[`DataSource`]. + +[IMPORTANT] +==== +As of Log4j `2.17.0` you need to enable the `DataSource` connection source **explicitly** by setting the +xref:manual/systemproperties.adoc#log4j2.enableJndiJdbc[`log4j2.enableJndiJdbc`] +configuration property to `true`. +==== + +[#DataSourceConnectionSource-attributes] +.`DataSource` configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[DataSourceConnectionSource-attr-jndiName]]jndiName +| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/naming/Name.html[`Name`] +| +| +It specifies the JNDI name of a JDBC +https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[`DataSource`]. + +Only the `java:` JNDI protocol is supported. + +**Required** +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-DataSourceConnectionSource[{open-book} Plugin reference for `DataSource`] + +[#FactoryMethodConnectionSource] +==== `ConnectionFactory` + +This connection source can use any factory method. +The method must: + +* Be `public` and `static`. +* Have an empty parameter list. +* Return either +https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html[`Connection`] +or +https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[`DataSource`]. + +[#FactoryMethodConnectionSource-attributes] +.`ConnectionFactory` configuration attributes +[cols="1m,2,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[FactoryMethodConnectionSource-attr-class]]class +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| +| +The fully qualified class name of the class containing the factory method. + +**Required** + +| [[FactoryMethodConnectionSource-attr-method]]method +| `String` +| +| +The name of the factory method. + +**Required** +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-FactoryMethodConnectionSource[{open-book} Plugin reference for `ConnectionFactory`] + +[#DriverManagerConnectionSource] +==== `DriverManager` + +This connection source uses +https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html[`DriverManager`] +to directly create connections using a JDBC +https://docs.oracle.com/javase/8/docs/api/java/sql/Driver.html[`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 <<PoolingDriverConnectionSource,`PoolingDriver`>> for a variant of this connection source that uses a connection pool. +==== + +[#DriverManagerConnectionSource-attributes] +.`DriverManager` configuration attributes +[cols="1m,2,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[DriverManagerConnectionSource-attr-connectionString]]connectionString +| `String` +| +| +The driver-specific JDBC connection string. + +**Required** + +| [[DriverManagerConnectionSource-attr-driverClassName]]driverClassName +| `String` +| _autodetected_ +| +The fully qualified class name of the JDBC driver to use. + +JDBC 4.0 drivers can be automatically detected by `DriverManager`. +See +https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html[`DriverManager`] +for more details. + +| [[DriverManagerConnectionSource-attr-userName]]userName +| `String` +| +| +The username to use to connect to the database. + +| [[DriverManagerConnectionSource-attr-password]]password +| `String` +| +| +The password to use to connect to the database. +|=== + +[#DriverManagerConnectionSource-elements] +.`DriverManager` nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[DriverManagerConnectionSource-element-Property]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Property[`Property`] +| zero or more +| +A list of key/value pairs to pass to `DriverManager`. + +If supplied, the <<DriverManagerConnectionSource-attr-userName,`userName`>> and <<DriverManagerConnectionSource-attr-password,`password`>> attributes will be ignored. +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-DriverManagerConnectionSource[{open-book} Plugin reference for `DriverManager`] + +[#PoolingDriverConnectionSource] +==== `PoolingDriver` + +The `PoolingDriver` uses +https://commons.apache.org/proper/commons-dbcp/[Apache Commons DBCP 2] +to configure a JDBC connection pool. + +[#PoolingDriverConnectionSource-attributes] +.`PoolingDriver` configuration attributes +[cols="1m,2,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[PoolingDriverConnectionSource-attr-connectionString]]connectionString +| `String` +| +| +The driver-specific JDBC connection string. + +**Required** + +| [[PoolingDriverConnectionSource-attr-driverClassName]]driverClassName +| `String` +| _autodetected_ +| +The fully qualified class name of the JDBC driver to use. + +JDBC 4.0 drivers can be automatically detected by `DriverManager`. +See +https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html[`DriverManager`] +for more details. + +| [[PoolingDriverConnectionSource-attr-userName]]userName +| `String` +| +| +The username to use to connect to the database. + +| [[PoolingDriverConnectionSource-attr-password]]password +| `String` +| +| +The password to use to connect to the database. + +| [[PoolingDriverConnectionSource-attr-poolName]]poolName +| `String` +| `example` +| + +|=== + +[#PoolingDriverConnectionSource-elements] +.`PoolingDriver` nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[PoolingDriverConnectionSource-element-Property]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Property[`Property`] +| zero or more +| +A list of key/value pairs to pass to `DriverManager`. + +If supplied, the <<DriverManagerConnectionSource-attr-userName,`userName`>> and <<DriverManagerConnectionSource-attr-password,`password`>> attributes will be ignored. + +| [[PoolingDriverConnectionSource-element-PoolingConnectionFactoryConfig]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-jdbc-dbcp2_org-apache-logging-log4j-core-appender-db-jdbc-PoolableConnectionFactoryConfig[`PoolableConnectionFactory`] +| 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 +https://commons.apache.org/proper/commons-dbcp/configuration.html[DBCP 2 configuration] for more details. + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-jdbc-dbcp2_org-apache-logging-log4j-core-appender-db-jdbc-PoolableConnectionFactoryConfig[{open-book} Plugin reference for `PoolableConnectionFactory`] +|=== + +Additional runtime dependencies are required for using `PoolingDriver`: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-jdbc-dbcp2</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-jdbc-dbcp2' +---- + +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-jdbc-dbcp2_org-apache-logging-log4j-core-appender-db-jdbc-PoolingDriverConnectionSource[{open-book} Plugin reference for `PoolingDriver`] + +[#JdbcAppender-MapMessage] +=== Map Message handling + +If the optional <<JdbcAppender-element-Layout,nested element of type `Layout<? Extends Message>`>> is provided, log events containing messages of type +xref:manual/messages.adoc#MapMessage[`MapMessage`] +will be treated specially. +For each <<ColumnMapping,column mapping>> (except those containing literals) the <<attr-source,`source`>> attribute will be used as key to the value in `MapMessage` that will be stored in column <<attr-name,`name`>>. + +[#JdbcAppender-examples] +=== Configuration examples + +Here are a couple of 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> +---- + +The following configuration uses no layout 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 lets you insert rows for custom values in a database table based on a Log4j `MapMessage` instead of values from `LogEvent`. + +[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" /> + </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> +---- + +[#JpaAppender] +== JPA Appender + +The JPA Appender writes log events to a relational database table using the +https://jakarta.ee/specifications/persistence/2.2/[Jakarta Persistence API 2.2]. +To use the appender, you need to: + +* configure your JPA persistence unit. +See <<JpaAppender-persistence>> below. +* configure the JPA Appender. +See <<JpaAppender-configuration>> below. + +[#JpaAppender-persistence] +=== Persistence configuration + +To store log events using JPA, you need to implement a JPA Entity that extends the +link:../javadoc/log4j-jpa/org/apache/logging/log4j/core/appender/db/jpa/AbstractLogEventWrapperEntity.html[`AbstractLogEventWrapperEntity`] +class. +To help you with the implementation, Log4j provides a +link:../javadoc/log4j-jpa/org/apache/logging/log4j/core/appender/db/jpa/BasicLogEventEntity.html[`BasicLogEventEntity`] +class that only lacks an identity field. + +A simple `AbstractLogEventWrapperEntity` implementation might look like: + +.Snippet from a {antora-examples-url}/manual/appenders/database/LogEventEntity.java[`LogEventEntity.java`] +[source,java] +---- +include::example$manual/appenders/database/LogEventEntity.java[tags=!setter;entity] +---- + +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: + +[source,xml] +---- +include::example$manual/appenders/database/persistence.xml[lines=1;18..-1] +---- + +<1> Specify you JPA provider. +<2> A non-JTA source should be used for performance. +<3> If your log event entity extends `BasicLogEventEntity`, you need to declare these converters. +<4> Declare your log event entity. +<5> Cache sharing should be set to `NONE`. + +[#JpaAppender-configuration] +=== Appender configuration + +The JPA appender supports these configuration options: + +[#JpaAppender-attributes] +.JPA Appender configuration attributes +[cols="1m,2,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[JpaAppender-attr-name]]name +| `String` +| +| The name of the Appender. + +| [[JpaAppender-attr-tableName]]tableName +| `String` +| +| The name of the table to use. + +| [[JpaAppender-attr-persistenceUnit]]persistenceUnitName +| `String` +| +| The name of the persistence unit to use. + +| [[JpaAppender-attr-entityClassName]]entityClassName +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| +| The fully qualified name of the entity class to use. + +The type must extend +link:../javadoc/log4j-jpa/org/apache/logging/log4j/core/appender/db/jpa/AbstractLogEventWrapperEntity.html[`AbstractLogEventWrapperEntity`]. + +4+h| Optional + +| [[JpaAppender-attr-bufferSize]]bufferSize +| `int` +| `0` +| +The number of log messages to batch before writing. +If `0`, batching is disabled. + +| [[JpaAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +|=== + +[#JpaAppender-elements] +.JPA Appender nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[JpaAppender-element-Filter]]xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. + +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. + +|=== + +Additional runtime dependencies are required for using the Cassandra Appender: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-jpa</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-jpa' +---- +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-jpa_org-apache-logging-log4j-core-appender-db-jpa-JpaAppender[{open-book} Plugin reference for `JPA`] + +[#JpaAppender-examples] +=== Configuration examples + +[source,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> +---- + +[#NoSqlAppender] +== NoSQL Appender + +The NoSQL Appender writes log events to a NoSQL database using an internal lightweight provider interface. +It supports the following configuration options + +[#NoSqlAppender-attributes] +.NoSQL Appender configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[NoSqlAppender-attr-name]]name +| `String` +| +| The name of the Appender. + +4+h| Optional + +| [[NoSqlAppender-attr-bufferSize]]bufferSize +| `int` +| `0` +| +The number of log messages to batch before writing to the database. +If `0`, batching is disabled. + +| [[NoSqlAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +|=== + +[#NoSqlAppender-elements] +.NoSQL Appender nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[NoSqlAppender-element-Filter]]xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. + +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. + +| [[NoSqlAppender-element-KeyValuePair]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-util-KeyValuePair[`KeyValuePair`] +| Zero or more +a| Adds a simple key/value field to the NoSQL object. + +The `value` attribute of the pair supports +xref:manual/configuration.adoc#lazy-property-substitution[runtime property substitution] +using the +xref:manual/lookups.adoc#event-context[current event as context]. + +| [[NoSqlAppender-element-Layout]]<<NoSqlAppender-formatting,`Layout`>> +| zero or one +| +An optional +link:../javadoc/log4j-core/org/apache/logging/log4j/core/Layout.html[`Layout<? extends MapMessage>`] +implementation that formats a log event as +xref:manual/messages.adoc#MapMessage[`MapMessage`]. + +See <<NoSqlAppender-formatting>> for more details. +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-nosql-NoSqlAppender[{open-book} Plugin reference for `NoSQL`] + +[#NoSqlAppender-formatting] +=== Formatting + +This appender transforms log events into JSON-like structures in two ways: + +* If the optional <<NoSqlAppender-element-Layout,`Layout`>> configuration element is provided, the +xref:manual/messages.adoc#MapMessage[`MapMessage`] returned by the layout will be converted into its JSON representation. +* Otherwise, a default conversion will be applied. +You enhance the format with additional top level key/value pairs using nested +<<NoSqlAppender-element-KeyValuePair,`KeyValuePair`>> configuration elements. ++ +.Click to see an example of default log event formatting +[%collapsible] +==== +[source,json] +---- +include::example$manual/appenders/database/nosql-log-event.json[] +---- +==== + +[#NoSqlProvider] +=== Providers + +The NoSQL Appender only handles the conversion of log events into NoSQL objects and delegates database-specific tasks to a NoSQL provider. +NoSQL providers are Log4j plugins that implement the +link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/nosql/NoSqlProvider.html[`NoSqlProvider`] +interface. +Log4j Core currently provides the following providers: + +* Multiple providers for different versions of the +https://www.mongodb.com/[MongoDB database]. +See <<NoSQLProvider-MongoDB>> below for more details. +* A provider for the +https://couchdb.apache.org/[Apache CouchDB database]. +See <<CouchDbProvider>> below for more details. + +[#NoSQLProvider-MongoDB] +=== MongoDB Providers + +Starting with version 2.11.0, Log4j supplies providers for the +https://www.mongodb.com/[MongoDB] +NoSQL database engine, based on the +https://www.mongodb.com/docs/drivers/java/sync/current/[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 https://www.mongodb.com/docs/drivers/java/sync/current/legacy/[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**: + +* `org.mongodb:mongo-java-driver` +* `org.mongodb:mongodb-driver-legacy` + +If you application only uses `org.mongodb:mongodb-driver-sync`, it uses the **Modern API**. +==== + +[WARNING] +==== +The version of the MongoDB Java driver is not the same as the version of the MongoDB server. +See +https://www.mongodb.com/docs/drivers/java/sync/current/compatibility/[MongoDB compatibility matrix] +for more information. +==== + +In order to use a Log4j MongoDB appender you need to add the following dependencies to your application: + +.MongoDB providers compatibility table +[cols="2,2,2,5"] +|=== +| Driver version | Driver API | Log4j artifact | Notes + +| `2.x` +| Legacy +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb2[`log4j-mongodb2`] +| Reached end-of-support. + +Last released version: `2.12.4` + +| [[NoSQLAppenderMongoDB3]]`3.x` +| Legacy +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb3[`log4j-mongodb3`] +| Reached end-of-support. + +Last released version: `2.23.1` + +| `4.x` +| Modern +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb4[`log4j-mongodb4`] +| + +| `5.x` or later +| Modern +| https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-mongodb[`log4j-mongodb`] +| +|=== + +[TIP] +==== +If you are note sure, which implementation to choose, `log4j-mongodb` is the recommended choice. +==== + +[#MongoDbProvider] +==== MongoDb Provider (current) + +The `MongoDb` provider is based on the +https://www.mongodb.com/docs/drivers/java/sync/current/[current version of the MongoDB Java driver]. +It supports the following configuration options: + +[#MongoDbProvider-attributes] +.MongoDb Provider configuration attributes +[cols="1m,1,2,5"] +|=== +| Attribute | Type | Default value | Description + +| [[MongoDbProvider-attr-connection]]connection +| https://mongodb.github.io/mongo-java-driver/5.1/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html[`ConnectionString`] +| +| +It specifies the connection URI used to reach the server. + +See +https://www.mongodb.com/docs/drivers/java/sync/current/fundamentals/connection/connect/#connection-uri[Connection URI documentation] +for its format. + +**Required** + +| [[MongoDbProvider-attr-capped]]capped +| `boolean` +| `false` +| +If `true`, a +https://www.mongodb.com/docs/manual/core/capped-collections/[capped collection] +will be used. + +| [[MongoDbProvider-attr-collectionSize]]collectionSize +| `long` +| `512 MiB` +| +It specifies the capped collection size of bytes. + +|=== + +Additional runtime dependencies are required to use the `MongoDb` provider: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-mongodb</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-mongodb' +---- +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-mongodb_org-apache-logging-log4j-mongodb-MongoDbProvider[{open-book} Plugin reference for `MongoDb`] + +[#MongoDb4Provider] +==== MongoDb4 Provider (deprecated) + +The `log4j-mongodb4` module is deprecated in favor of the <<MongoDbProvider,current `MongoDB` provider>>. +It supports the following configuration attributes: + +[#MongoDb4Provider-attributes] +.MongoDb4 provider configuration attributes +[cols="1m,1,2,5"] +|=== +| Attribute | Type | Default value | Description + +| [[MongoDb4Provider-attr-connection]]connection +| https://mongodb.github.io/mongo-java-driver/5.1/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html[`ConnectionString`] +| +| +It specifies the connection URI used to reach the server. + +See +https://www.mongodb.com/docs/drivers/java/sync/current/fundamentals/connection/connect/#connection-uri[Connection URI documentation] +for its format. + +**Required** + +| [[MongoDb4Provider-attr-capped]]capped +| `boolean` +| `false` +| +If `true`, a +https://www.mongodb.com/docs/manual/core/capped-collections/[capped collection] +will be used. + +| [[MongoDb4Provider-attr-collectionSize]]collectionSize +| `long` +| `512 MiB` +| +It specifies the capped collection size of bytes. + +|=== + +Additional runtime dependencies are required to use the `MongoDb4` provider: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-mongodb4</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-mongodb4' +---- +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-mongodb4_org-apache-logging-log4j-mongodb4-MongoDb4Provider[{open-book} Plugin reference for `MongoDb4`] + +[#CouchDbProvider] +=== Apache CouchDB provider + +The `CouchDb` Provider allows using the <<NoSqlAppender>> with an +https://couchdb.apache.org/[Apache CouchDB database]. +The provider can be configured by: + +* either providing some <<CouchDbProvider-attr-standard,standard configuration attributes>>, +* or providing a <<CouchDbProvider-attr-factory,factory method>>. + +[#CouchDbProvider-attributes] +.CouchDb provider configuration attributes +[cols="1m,1,2,5"] +|=== +| Attribute | Type | Default value | Description + + +4+h| [[CouchDbProvider-attr-standard]]Standard configuration attributes + +| [[CouchDbProvider-attr-protocol]]protocol +| _enumeration_ +| `http` +a| +It specifies the protocol to use to connect to the server. +Can be one of: + +* `http` +* `https` + +| [[CouchDbProvider-attr-server]]server +| `String` +| `localhost` +| +The host name of the CouchDB server. + +| [[CouchDbProvider-attr-port]]port +| `int` +a| +`80`:: for `http` +`443`:: for `https` +| +It specifies the TCP port to use. + +| [[CouchDbProvider-attr-databaseName]]databaseName +| `String` +| +| +The name of the database to connect to. + +| [[CouchDbProvider-attr-username]]username +| `String` +| +| +The username for authentication. + +| [[CouchDbProvider-attr-password]]password +| `String` +| +| +The password for authentication. + +4+h| [[CouchDbProvider-attr-factory]]Factory method configuration attributes + +| [[CouchDbProvider-attr-factoryClassName]]factoryClassName +| https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html[`Class<?>`] +| +a| +The fully qualified class name that contains a factory method that returns either a +https://javadoc.io/static/org.lightcouch/lightcouch/0.2.0/org/lightcouch/CouchDbClient.html[`CouchDbClient`] +or +https://javadoc.io/static/org.lightcouch/lightcouch/0.2.0/org/lightcouch/CouchDbProperties.html[`CouchDbProperties`] +object. + +The class must be public. + +| [[CouchDbProvider-attr-factoryMethodName]]factoryMethodName +| `String` +| +a| +The name of the factory method. +The method: + +* Must be `public` and `static`. +* Have an empty parameter list. +* Returns either a +https://javadoc.io/static/org.lightcouch/lightcouch/0.2.0/org/lightcouch/CouchDbClient.html[`CouchDbClient`] +or +https://javadoc.io/static/org.lightcouch/lightcouch/0.2.0/org/lightcouch/CouchDbProperties.html[`CouchDbProperties`] +object. + +|=== + +Additional runtime dependencies are required to use the `CouchDb` provider: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<!-- We assume you use `log4j-bom` for dependency management --> +<dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-couchdb</artifactId> + <scope>runtime</scope> +</dependency> +---- + +Gradle:: ++ +[source,groovy] +---- +// We assume you use `log4j-bom` for dependency management +runtimeOnly 'org.apache.logging.log4j:log4j-couchdb' +---- +==== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-couchdb_org-apache-logging-log4j-couchdb-CouchDbProvider[{open-book} Plugin reference for `CouchDb`] + +[#NoSqlAppender-examples] +=== Configuration examples + +Here are a few sample configurations for the NoSQLAppender and MongoDB4 provider: + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<Configuration status="WARN"> + <Appenders> + <NoSql name="MongoDbAppender"> + <MongoDb connection="mongodb://log4jUser:12345678@localhost:${sys:MongoDBTestPort:-27017}/testDb.testCollection" /> + </NoSql> + </Appenders> + <Loggers> + <Root level="ALL"> + <AppenderRef ref="MongoDbAppender" /> + </Root> + </Loggers> +</Configuration> +---- + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<Configuration status="WARN"> + <Appenders> + <NoSql name="MongoDbAppender"> + <MongoDb + connection="mongodb://localhost:${sys:MongoDBTestPort:-27017}/testDb.testCollection" + capped="true" + collectionSize="1073741824"/> + </NoSql> + </Appenders> + <Loggers> + <Root level="ALL"> + <AppenderRef ref="MongoDbAppender" /> + </Root> + </Loggers> +</Configuration> +---- + +You can define additional fields to log using KeyValuePair elements, for example: + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> Review Comment: Fixed in https://github.com/apache/logging-log4j2/pull/2790/commits/fad8d7f8603086a8abaa44c0c9e2d1dd6d7524fe -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
