diff --git a/log4j-jpa/pom.xml b/log4j-jpa/pom.xml index b2c873b12a9..6a3d8ed5671 100644 --- a/log4j-jpa/pom.xml +++ b/log4j-jpa/pom.xml @@ -32,6 +32,7 @@ Apache Log4j Java Persistence API Appender. + false + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/cassandra.yaml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/cassandra.yaml new file mode 100644 index 00000000000..ade8502275a --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/cassandra.yaml @@ -0,0 +1,58 @@ +# +# 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. +# +Configuration: + Appenders: + # tag::appender[] + Cassandra: + name: "CASSANDRA" + clusterName: "test-cluster" + keyspace: "test" + table: "logs" + # <1> + bufferSize: 10 + batched: true + # <2> + SocketAddress: + - host: "server1" + port: "9042" + - host: "server2" + port: "9042" + # <3> + ColumnMapping: + - name: "id" + pattern: "%uuid{TIME}" + columnType: "java.util.UUID" + - name: "timestamp" + columnType: "java.util.Date" + - name: "level" + pattern: "%level" + - name: "marker" + pattern: "%marker" + - name: "logger" + pattern: "%logger" + - name: "message" + pattern: "%message" + - name: "mdc" + columnType: "org.apache.logging.log4j.spi.ThreadContextMap" + - name: "ndc" + columnType: "org.apache.logging.log4j.spi.ThreadContextStack" + # end::appender[] + Loggers: + Root: + level: "INFO" + AppenderRef: + ref: "CASSANDRA" diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/column-mapping.json b/src/site/antora/modules/ROOT/examples/manual/appenders/database/column-mapping.json new file mode 100644 index 00000000000..119170bce59 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/column-mapping.json @@ -0,0 +1,61 @@ +{ + "Configuration": { + "Appenders": { + "JDBC": { + "name": "JDBC_LOG", + "tableName": "logs", + "MessageLayout": {}, + // tag::mapping[] + "ColumnMapping": [ + // <1> + { + "name": "id", + "literal": "currval('logging_seq')" + }, + // <2> + { + "name": "uuid", + "pattern": "%uuid{TIME}", + "columnType": "java.util.UUID" + }, + { + "name": "message", + "pattern": "%m" + }, + // <3> + { + "name": "timestamp", + "columnType": "java.util.Date" + }, + { + "name": "mdc", + "columnType": "org.apache.logging.log4j.spi.ThreadContextMap" + }, + { + "name": "ndc", + "columnType": "org.apache.logging.log4j.spi.ThreadContextStack" + }, + // <4> + { + "name": "asJson", + "JsonTemplateLayout": {} + }, + // <5> + { + "name": "resource", + "source": "resourceId" + } + ] + // end::mapping[] + } + }, + "Loggers": { + "Root": { + "level": "INFO", + "AppenderRef": { + "ref": "JDBC_LOG" + } + } + } + } +} \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/column-mapping.properties b/src/site/antora/modules/ROOT/examples/manual/appenders/database/column-mapping.properties new file mode 100644 index 00000000000..eb854ecc4ca --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/column-mapping.properties @@ -0,0 +1,63 @@ +# +# 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. +# +appender.0.type = JDBC +appender.0.name = JDBC_LOG +appender.0.tableName = logs + +appender.0.layout.type = MessageLayout +# tag::mapping[] +# <1> +appender.0.col[0].type = ColumnMapping +appender.0.col[0].name = id +appender.0.col[0].literal = currval('logging_seq') + +# <2> +appender.0.col[1].type = ColumnMapping +appender.0.col[1].name = uuid +appender.0.col[1].pattern = %uuid{TIME} +appender.0.col[1].columnType = java.util.UUID + +appender.0.col[2].type = ColumnMapping +appender.0.col[2].name = message +appender.0.col[2].pattern = %m + +# <3> +appender.0.col[3].type = ColumnMapping +appender.0.col[3].name = timestamp +appender.0.col[3].timestamp = java.util.Date + +appender.0.col[4].type = ColumnMapping +appender.0.col[4].name = mdc +appender.0.col[4].columnType = org.apache.logging.log4j.spi.ThreadContextMap + +appender.0.col[5].type = ColumnMapping +appender.0.col[5].name = ndc +appender.0.col[5].columnType = org.apache.logging.log4j.spi.ThreadContextStack + +# <4> +appender.0.col[6].type = ColumnMapping +appender.0.col[6].name = asJson +appender.0.col[6].layout.type = JsonTemplateLayout + +# <5> +appender.0.col[7].type = ColumnMapping +appender.0.col[7].name = resource +appender.0.col[7].source = resourceId +# end::mapping[] + +rootLogger.level = INFO +rootLogger.appenderRef.0.ref= JDBC_LOG diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/column-mapping.xml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/column-mapping.xml new file mode 100644 index 00000000000..fc732253951 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/column-mapping.xml @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/column-mapping.yaml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/column-mapping.yaml new file mode 100644 index 00000000000..d26e37e933a --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/column-mapping.yaml @@ -0,0 +1,52 @@ +# +# 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. +# +Configuration: + Appenders: + JDBC: + name: "JDBC_LOG" + tableName: "logs" + MessageLayout: {} + # tag::mapping[] + ColumnMapping: + # <1> + - name: "id" + literal: "currval('logging_seq')" + # <2> + - name: "uuid" + pattern: "%uuid{TIME}" + columnType: "java.util.UUID" + - name: "message" + pattern: "%m" + # <3> + - name: "timestamp" + columnType: "java.util.Date" + - name: "mdc" + columnType: "org.apache.logging.log4j.spi.ThreadContextMap" + - name: "ndc" + columnType: "org.apache.logging.log4j.spi.ThreadContextStack" + # <4> + - name: "asJson" + JsonTemplateLayout: {} + # <5> + - name: "resource" + source: "resourceId" + # end::mapping[] + Loggers: + Root: + level: "INFO" + AppenderRef: + ref: "JDBC_LOG" diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.json b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.json new file mode 100644 index 00000000000..203c1a502b2 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.json @@ -0,0 +1,62 @@ +{ + "Configuration": { + "Appenders": { + // tag::appender[] + "JDBC": { + "name": "JDBC", + "tableName": "logs", + // <1> + "bufferSize": 10, + // <2> + "DataSource": { + "jndiName": "java:comp/env/jdbc/logging" + }, + // <3> + "ColumnMapping": [ + { + "name": "id", + "pattern": "%uuid{TIME}", + "columnType": "java.util.UUID" + }, + { + "name": "timestamp", + "columnType": "java.util.Date" + }, + { + "name": "level", + "pattern": "%level" + }, + { + "name": "marker", + "pattern": "%marker" + }, + { + "name": "logger", + "pattern": "%logger" + }, + { + "name": "message", + "pattern": "%m" + }, + { + "name": "mdc", + "columnType": "org.apache.logging.log4j.spi.ThreadContextMap" + }, + { + "name": "ndc", + "columnType": "org.apache.logging.log4j.spi.ThreadContextStack" + } + ] + } + // end::appender[] + }, + "Loggers": { + "Root": { + "level": "INFO", + "AppenderRef": { + "ref": "JDBC" + } + } + } + } +} \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.properties b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.properties new file mode 100644 index 00000000000..2191532d3af --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.properties @@ -0,0 +1,65 @@ +# +# 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. +# +## +# tag::appender[] +appender.0.type = JDBC +appender.0.name = JDBC +appender.0.tableName = logs +# <1> +appender.0.bufferSize = 10 + +# <2> +appender.0.ds.type = DataSource +appender.0.ds.jndiName = java:comp/env/jdbc/logging + +# <3> +appender.0.col[0].type = ColumnMapping +appender.0.col[0].name = uuid +appender.0.col[0].pattern = %uuid{TIME} +appender.0.col[0].columnType = java.util.UUID + +appender.0.col[1].type = ColumnMapping +appender.0.col[1].name = timestamp +appender.0.col[1].timestamp = java.util.Date + +appender.0.col[2].type = ColumnMapping +appender.0.col[2].name = level +appender.0.col[2].pattern = %level + +appender.0.col[3].type = ColumnMapping +appender.0.col[3].name = marker +appender.0.col[3].pattern = %marker + +appender.0.col[4].type = ColumnMapping +appender.0.col[4].name = logger +appender.0.col[4].pattern = %logger + +appender.0.col[5].type = ColumnMapping +appender.0.col[5].name = message +appender.0.col[5].pattern = %message + +appender.0.col[6].type = ColumnMapping +appender.0.col[6].name = mdc +appender.0.col[6].columnType = org.apache.logging.log4j.spi.ThreadContextMap + +appender.0.col[7].type = ColumnMapping +appender.0.col[7].name = ndc +appender.0.col[7].columnType = org.apache.logging.log4j.spi.ThreadContextStack +# end::appender[] + +rootLogger.level = INFO +rootLogger.appenderRef.0.ref= JDBC diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.sql b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.sql new file mode 100644 index 00000000000..7d16d8bb88b --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.sql @@ -0,0 +1,27 @@ +/* + * 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. + */ +CREATE TABLE logs +( + id BIGINT PRIMARY KEY, + level VARCHAR, + marker VARCHAR, + logger VARCHAR, + message VARCHAR, + timestamp TIMESTAMP, + mdc VARCHAR, + ndc VARCHAR +); \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.xml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.xml new file mode 100644 index 00000000000..7c7667e4c85 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.xml @@ -0,0 +1,51 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.yaml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.yaml new file mode 100644 index 00000000000..7cafe2c8c8f --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jdbc.yaml @@ -0,0 +1,52 @@ +# +# 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. +# +Configuration: + Appenders: + # tag::appender[] + JDBC: + name: "JDBC" + tableName: "logs" + # <1> + bufferSize: 10 + # <2> + DataSource: + jndiName: "java:comp/env/jdbc/logging" + # <3> + ColumnMapping: + - name: "id" + pattern: "%uuid{TIME}" + columnType: "java.util.UUID" + - name: "timestamp" + columnType: "java.util.Date" + - name: "level" + pattern: "%level" + - name: "marker" + pattern: "%marker" + - name: "logger" + pattern: "%logger" + - name: "message" + pattern: "%message" + - name: "mdc" + columnType: "org.apache.logging.log4j.spi.ThreadContextMap" + - name: "ndc" + columnType: "org.apache.logging.log4j.spi.ThreadContextStack" + # end::appender[] + Loggers: + Root: + level: "INFO" + AppenderRef: + ref: "JDBC" diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/jpa.json b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jpa.json new file mode 100644 index 00000000000..e44b149beb9 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jpa.json @@ -0,0 +1,21 @@ +{ + "Configuration": { + "Appenders": { + // tag::appender[] + "JPA": { + "name": "JPA", + "persistenceUnitName": "logging", + "entityClassName": "com.example.logging.LogEventEntity" + } + // end::appender[] + }, + "Loggers": { + "Root": { + "level": "INFO", + "AppenderRef": { + "ref": "JPA" + } + } + } + } +} \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/jpa.properties b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jpa.properties new file mode 100644 index 00000000000..01aabfc4a14 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jpa.properties @@ -0,0 +1,26 @@ +# +# 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. +# +## +# tag::appender[] +appender.0.type = JPA +appender.0.name = JPA +appender.0.persistenceUnitName = logging +appender.0.entityClassName = com.example.logging.LogEventEntity +# end::appender[] + +rootLogger.level = INFO +rootLogger.appenderRef.0.ref = JPA diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/jpa.xml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jpa.xml new file mode 100644 index 00000000000..9f6d38dfa67 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jpa.xml @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/jpa.yaml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jpa.yaml new file mode 100644 index 00000000000..55870a0c112 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/jpa.yaml @@ -0,0 +1,29 @@ +# +# 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. +# +Configuration: + Appenders: + # tag::appender[] + JPA: + name: "JPA" + persistenceUnitName: "logging" + entityClassName: "com.example.logging.LogEventEntity" + # end::appender[] + Loggers: + Root: + level: "INFO" + AppenderRef: + ref: "JPA" diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-couch.json b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-couch.json new file mode 100644 index 00000000000..19fb3f59c24 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-couch.json @@ -0,0 +1,27 @@ +{ + "Configuration": { + "Appenders": { + // tag::appender[] + "CouchDb": { + "name": "COUCH", + "CouchDB": { + "protocol": "https", + "username": "${env:DB_USER}", + "password": "${env:DB_PASS"}, + "server": "localhost", + "port": 5984, + "databaseName": "logging" + } + } + // end::appender[] + }, + "Loggers": { + "Root": { + "level": "INFO", + "AppenderRef": { + "ref": "COUCH" + } + } + } + } +} \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-couch.properties b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-couch.properties new file mode 100644 index 00000000000..7700174930e --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-couch.properties @@ -0,0 +1,31 @@ +# +# 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. +# +## +# tag::appender[] +appender.0.type = NoSql +appender.0.name = COUCH +appender.0.provider.type = CouchDB +appender.0.provider.protocol = https +appender.0.provider.username = ${env:DB_USER} +appender.0.provider.password = ${env:DB_PASS} +appender.0.provider.server = localhost +appender.0.provider.port = 5984 +appender.0.provider.databaseName = logging +# end::appender[] + +rootLogger.level = INFO +rootLogger.appenderRef.0.ref = COUCH diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-couch.xml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-couch.xml new file mode 100644 index 00000000000..1a580e4480d --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-couch.xml @@ -0,0 +1,40 @@ + + + + + + + + + + + + + + + + diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-couch.yaml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-couch.yaml new file mode 100644 index 00000000000..b6da195a834 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-couch.yaml @@ -0,0 +1,34 @@ +# +# 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. +# +Configuration: + Appenders: + # tag::appender[] + NoSql: + name: "COUCH" + CouchDB: + protocol: "https" + username: "${env:DB_USER}" + password: "${env:DB_PASS}" + server: "localhost" + port: 5984 + databaseName: "logging" + # end::appender[] + Loggers: + Root: + level: "INFO" + AppenderRef: + ref: "COUCH" diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-log-event.json b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-log-event.json new file mode 100644 index 00000000000..454ec5ffb0e --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-log-event.json @@ -0,0 +1,95 @@ +{ + "level": "WARN", + "loggerName": "com.example.application.MyClass", + "message": "Something happened that you might want to know about.", + "source": { + "className": "com.example.application.MyClass", + "methodName": "exampleMethod", + "fileName": "MyClass.java", + "lineNumber": 81 + }, + "marker": { + "name": "SomeMarker", + "parent": { + "name": "SomeParentMarker" + } + }, + "threadName": "Thread-1", + "millis": 1368844166761, + "date": "2013-05-18T02:29:26.761Z", + "thrown": { + "type": "java.sql.SQLException", + "message": "Could not insert record. Connection lost.", + "stackTrace": [ + { + "className": "org.example.sql.driver.PreparedStatement$1", + "methodName": "responder", + "fileName": "PreparedStatement.java", + "lineNumber": 1049 + }, + { + "className": "org.example.sql.driver.PreparedStatement", + "methodName": "executeUpdate", + "fileName": "PreparedStatement.java", + "lineNumber": 738 + }, + { + "className": "com.example.application.MyClass", + "methodName": "exampleMethod", + "fileName": "MyClass.java", + "lineNumber": 81 + }, + { + "className": "com.example.application.MainClass", + "methodName": "main", + "fileName": "MainClass.java", + "lineNumber": 52 + } + ], + "cause": { + "type": "java.io.IOException", + "message": "Connection lost.", + "stackTrace": [ + { + "className": "java.nio.channels.SocketChannel", + "methodName": "write", + "fileName": null, + "lineNumber": -1 + }, + { + "className": "org.example.sql.driver.PreparedStatement$1", + "methodName": "responder", + "fileName": "PreparedStatement.java", + "lineNumber": 1032 + }, + { + "className": "org.example.sql.driver.PreparedStatement", + "methodName": "executeUpdate", + "fileName": "PreparedStatement.java", + "lineNumber": 738 + }, + { + "className": "com.example.application.MyClass", + "methodName": "exampleMethod", + "fileName": "MyClass.java", + "lineNumber": 81 + }, + { + "className": "com.example.application.MainClass", + "methodName": "main", + "fileName": "MainClass.java", + "lineNumber": 52 + } + ] + } + }, + "contextMap": { + "ID": "86c3a497-4e67-4eed-9d6a-2e5797324d7b", + "username": "JohnDoe" + }, + "contextStack": [ + "topItem", + "anotherItem", + "bottomItem" + ] +} \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo-keys.json b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo-keys.json new file mode 100644 index 00000000000..2b47690c0b5 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo-keys.json @@ -0,0 +1,32 @@ +{ + "Configuration": { + "Appenders": { + // tag::appender[] + "NoSql": { + "name": "MONGO", + "MongoDb": { + "connection": "mongodb://${env:DB_USER}:${env:DB_PASS}@localhost:27017/logging.logs" + }, + "KeyValuePair": [ + { + "key": "startTime", + "value": "${date:yyyy-MM-dd hh:mm:ss.SSS}" // <1> + }, + { + "key": "currentTime", + "value": "$${date:yyyy-MM-dd hh:mm:ss.SSS}" // <2> + } + ] + } + // end::appender[] + }, + "Loggers": { + "Root": { + "level": "INFO", + "AppenderRef": { + "ref": "MONGO" + } + } + } + } +} \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo-keys.properties b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo-keys.properties new file mode 100644 index 00000000000..e0e97ac2872 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo-keys.properties @@ -0,0 +1,36 @@ +# +# 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. +# +## +# tag::appender[] +appender.0.type = NoSql +appender.0.name = MONGO +appender.0.provider.type = MongoDB +appender.0.provider.connection = mongodb://${env:DB_USER}:${env:DB_PASS}@localhost:27017/logging.logs + +appender.0.kv[0].type = KeyValuePair +appender.0.kv[0].key = startTime +# <1> +appender.0.kv[0].value = ${date:yyyy-MM-dd hh:mm:ss.SSS} + +appender.0.kv[1].type = KeyValuePair +appender.0.kv[1].key = currentTime +# <1> +appender.0.kv[1].value = $${date:yyyy-MM-dd hh:mm:ss.SSS} +# end::appender[] + +rootLogger.level = INFO +rootLogger.appenderRef.0.ref = MONGO diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo-keys.xml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo-keys.xml new file mode 100644 index 00000000000..cd9f458ac3a --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo-keys.xml @@ -0,0 +1,37 @@ + + + + + + + + + + + + + + + + + + diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo-keys.yaml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo-keys.yaml new file mode 100644 index 00000000000..2cb5df2c85f --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo-keys.yaml @@ -0,0 +1,34 @@ +# +# 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. +# +Configuration: + Appenders: + # tag::appender[] + NoSql: + name: "MONGO" + MongoDb: + connection: "mongodb://${env:DB_USER}:${env:DB_PASS}@localhost:27017/logging.logs" + KeyValuePair: + - key: "startTime" + value: "${date:yyyy-MM-dd hh:mm:ss.SSS}" # <1> + - key: "currentTime" + value: "$${date:yyyy-MM-dd hh:mm:ss.SSS}" # <2> + # end::appender[] + Loggers: + Root: + level: "INFO" + AppenderRef: + ref: "MONGO" diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo.json b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo.json new file mode 100644 index 00000000000..4e42604efd2 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo.json @@ -0,0 +1,22 @@ +{ + "Configuration": { + "Appenders": { + // tag::appender[] + "NoSql": { + "name": "MONGO", + "MongoDb": { + "connection": "mongodb://${env:DB_USER}:${env:DB_PASS}@localhost:27017/logging.logs" + } + } + // end::appender[] + }, + "Loggers": { + "Root": { + "level": "INFO", + "AppenderRef": { + "ref": "MONGO" + } + } + } + } +} \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo.properties b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo.properties new file mode 100644 index 00000000000..9f313e56f21 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo.properties @@ -0,0 +1,26 @@ +# +# 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. +# +## +# tag::appender[] +appender.0.type = NoSql +appender.0.name = MONGO +appender.0.provider.type = MongoDB +appender.0.provider.connection = mongodb://${env:DB_USER}:${env:DB_PASS}@localhost:27017/logging.logs +# end::appender[] + +rootLogger.level = INFO +rootLogger.appenderRef.0.ref = MONGO diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo.xml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo.xml new file mode 100644 index 00000000000..fe3a4059968 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo.xml @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + + + diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo.yaml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo.yaml new file mode 100644 index 00000000000..a3a596e618a --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/nosql-mongo.yaml @@ -0,0 +1,29 @@ +# +# 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. +# +Configuration: + Appenders: + # tag::appender[] + NoSql: + name: "MONGO" + MongoDb: + connection: "mongodb://${env:DB_USER}:${env:DB_PASS}@localhost:27017/logging.logs" + # end::appender[] + Loggers: + Root: + level: "INFO" + AppenderRef: + ref: "MONGO" diff --git a/src/site/antora/modules/ROOT/examples/manual/appenders/database/persistence.xml b/src/site/antora/modules/ROOT/examples/manual/appenders/database/persistence.xml new file mode 100644 index 00000000000..64f5a126197 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/appenders/database/persistence.xml @@ -0,0 +1,60 @@ + + + + + + org.eclipse.persistence.jpa.PersistenceProvider + + jdbc/logging + + + org.apache.logging.log4j.core.appender.db.jpa.converter.ContextMapAttributeConverter + + + org.apache.logging.log4j.core.appender.db.jpa.converter.ContextStackAttributeConverter + + + org.apache.logging.log4j.core.appender.db.jpa.converter.InstantAttributeConverter + + + org.apache.logging.log4j.core.appender.db.jpa.converter.LevelAttributeConverter + + + org.apache.logging.log4j.core.appender.db.jpa.converter.MarkerAttributeConverter + + + org.apache.logging.log4j.core.appender.db.jpa.converter.MessageAttributeConverter + + + org.apache.logging.log4j.core.appender.db.jpa.converter.StackTraceElementAttributeConverter + + + org.apache.logging.log4j.core.appender.db.jpa.converter.ThrowableAttributeConverter + + + + com.example.logging.LogEventEntity + + + NONE + + diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc index 59bab7b1e38..c379039437c 100644 --- a/src/site/antora/modules/ROOT/nav.adoc +++ b/src/site/antora/modules/ROOT/nav.adoc @@ -45,6 +45,7 @@ ** xref:manual/appenders.adoc[] *** xref:manual/appenders/file.adoc[] *** xref:manual/appenders/rolling-file.adoc[] +*** xref:manual/appenders/database.adoc[] *** xref:manual/appenders/delegating.adoc[] ** xref:manual/layouts.adoc[] *** xref:manual/json-template-layout.adoc[] diff --git a/src/site/antora/modules/ROOT/pages/javadoc.adoc b/src/site/antora/modules/ROOT/pages/javadoc.adoc index cc2bee3d5b0..173a814df53 100644 --- a/src/site/antora/modules/ROOT/pages/javadoc.adoc +++ b/src/site/antora/modules/ROOT/pages/javadoc.adoc @@ -29,4 +29,7 @@ The table below contains links to the Javadoc API Documentation for the componen | link:javadoc/log4j-jakarta-web/index.html[Log4j Web] | Tools to use Log4j Core in Jakarta EE applications. + +| link:javadoc/log4j-jpa/index.html[Log4j JPA] +| Tools to use Log4j Core with the Java Persistence API. |=== diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc index f6cb1adbcbb..18964fde99a 100644 --- a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc @@ -224,6 +224,26 @@ See xref:manual/appenders/file.adoc[] for details. Rolling file appenders::: See xref:manual/appenders/rolling-file.adoc[] for details. +[#database-appenders] +=== Database appenders + +The appenders write log events directly to a database. + +xref:manual/appenders/database.adoc#CassandraAppender[Cassandra appender]:: +Sends log events to +https://cassandra.apache.org/_/index.html[Apache Cassandra] + +xref:manual/appenders/database.adoc#JdbcAppender[JDBC appender]:: +Sends log events to a JDBC driver + +xref:manual/appenders/database.adoc#JpaAppender[JPA appender]:: +Uses Jakarta Persistence API to deliver log events to a database + +xref:manual/appenders/database.adoc#NoSqlAppender[NoSQL appender]:: +Store log events to a document-oriented database + +See xref:manual/appenders/database.adoc[] for details. + [#delegating-appenders] === Delegating appenders @@ -243,146 +263,6 @@ Dynamically choose a different appender for each log event See xref:manual/appenders/delegating.adoc[] for details. -[#CassandraAppender] -=== CassandraAppender - -The CassandraAppender writes its output to an -https://cassandra.apache.org/_/index.html[Apache Cassandra] -database. -A keyspace and table must be configured ahead of time, and the columns of that table are mapped in a configuration file. -Each column can specify either a xref:manual/pattern-layout.adoc[]https://logging.apache.org/log4j/2.x/manual/layouts.html#PatternLayout[StringLayout] (e.g., a PatternLayout) along with an optional conversion type, or only a conversion type for `org.apache.logging.log4j.spi.ThreadContextMap` or -`org.apache.logging.log4j.spi.ThreadContextStack` to store the MDC or NDC in a map or list column respectively. -A conversion type compatible with `java.util.Date` will use the log event timestamp converted to that type (e.g., use `java.util.Date` to fill a -`timestamp` column type in Cassandra). - -.CassandraAppender Parameters -[cols="1,1,3",options="header"] -|=== -| Parameter Name | Type | Description - -| batched -| boolean -| Whether or not to use batch statements to write log messages to Cassandra. By default, this is `false`. - -| batchType -| https://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/BatchStatement.Type.html[BatchStatement.Type] -| The batch type to use when using batched writes. By default, this is `LOGGED`. - -| bufferSize -| int -| The number of log messages to buffer or batch before writing. By default, no buffering is done. - -| clusterName -| String -| The name of the Cassandra cluster to connect to. - -| columns -| ColumnMapping[] -| A list of column mapping configurations. Each column must specify a column name. Each column can -have a conversion type specified by its fully qualified class name. By default, the conversion type is -`String`. If the configured type is assignment-compatible with -ReadOnlyStringMap / -ThreadContextMap or -ThreadContextStack, -then that column will be populated with the MDC or NDC respectively. If the configured type is -assignment-compatible with `java.util.Date`, then the log timestamp will be converted to -that configured date type. If a `literal` attribute is given, then its value will be used as -is in the `INSERT` query without any escaping. Otherwise, the layout or pattern specified -will be converted into the configured type and stored in that column. - -| contactPoints -| SocketAddress[] -| A list of hosts and ports of Cassandra nodes to connect to. These must be valid hostnames or IP -addresses. By default, if a port is not specified for a host or it is set to 0, then the default -Cassandra port of 9042 will be used. By default, `localhost:9042` will be used. - -| filter -| Filter -| A Filter to determine if the event should be handled by this Appender. More than one Filter may be used -by using a CompositeFilter. - -| ignoreExceptions -| boolean -| The default is `true`, causing exceptions encountered while appending events to be -internally logged and then ignored. When set to `false` exceptions will be propagated to the -caller, instead. You must set this to `false` when wrapping this Appender in a -FailoverAppender. - -| keyspace -| String -| The name of the keyspace containing the table that log messages will be written to. - -| name -| String -| The name of the Appender. - -| password -| String -| The password to use (along with the username) to connect to Cassandra. - -| table -| String -| The name of the table to write log messages to. - -| useClockForTimestampGenerator -| boolean -| Whether or not to use the configured `org.apache.logging.log4j.core.util.Clock` as a -TimestampGenerator. By default, this is `false`. - -| username -| String -| The username to use to connect to Cassandra. By default, no username or password is used. - -| useTls -| boolean -| Whether or not to use TLS/SSL to connect to Cassandra. This is `false` by default. -|=== - -Here is an example `CassandraAppender` configuration: - -[source,xml] ----- - - - - - - - - - - - - - - - - - - - - - - ----- - -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, - ndc list -); ----- - [id=consoleappender] === [[ConsoleAppender]] ConsoleAppender @@ -446,7 +326,6 @@ A typical Console configuration might look like: ---- - [#FlumeAppender] === FlumeAppender @@ -679,401 +558,6 @@ A sample FlumeAppender configuration that is configured with a primary and a sec ---- -[#JDBCAppender] -=== JDBCAppender - -As of Log4j 2.11.0, JDBC support has moved from the existing module -`log4j-core` to the new module `log4j-jdbc`. - -The JDBC Appender configured with a `DataSource` requires JNDI support so as of release 2.17.1 this appender will not function unless `log4j2.enableJndiJdbc=true` is configured as a system property or environment variable. -See the xref:manual/systemproperties.adoc#log4j2.enableJndiJdbc[`log4j2.enableJndiJdbc`] system property. - -The JDBCAppender writes log events to a relational database table using standard JDBC. -It can be configured to obtain JDBC connections using a JNDI `DataSource` or a custom factory method. -Whichever approach you take, it *_must_* be backed by a connection pool. -Otherwise, logging performance will suffer greatly. -If batch statements are supported by the configured JDBC driver and a `bufferSize` is configured to be a positive number, then log events will be batched. -Note that as of Log4j 2.8, there are two ways to configure log event to column mappings: the original `ColumnConfig` style that only allows strings and timestamps, and the new `ColumnMapping` plugin that uses Log4j's built-in type conversion to allow for more data types. - -To get off the ground quickly during development, an alternative to using a connection source based on JNDI is to use the non-pooling -`DriverManager` connection source. -This connection source uses a JDBC connection string, a username, and a password. -Optionally, you can also use properties. - -.JDBCAppender Parameters -[cols="20%,20%,60%",options="header",] -|======================================================================= -|Parameter Name |Type |Description -|name |String |_Required._ The name of the Appender. - -|ignoreExceptions |boolean |The default is `true`, causing exceptions -encountered while appending events to be internally logged and then -ignored. When set to `false` exceptions will be propagated to the -caller, instead. You must set this to `false` when wrapping this -Appender in a <>. - -|filter |Filter |A Filter to determine if the event should be handled by -this Appender. More than one Filter may be used by using a -CompositeFilter. - -|bufferSize |int |If an integer is greater than 0, this causes the appender -to buffer log events and flush whenever the buffer reaches this size. - -|connectionSource |ConnectionSource |_Required._ The connection source -from which database connections should be retrieved. - -|tableName |String |_Required._ The name of the database table to insert -log events into. - -|columnConfigs |ColumnConfig[] |_Required (and/or columnMappings)._ -Information about the columns that log event data should be inserted -into and how to insert that data. This is represented by multiple -`` elements. - -|columnMappings |ColumnMapping[] |_Required (and/or columnConfigs)._ A -list of column mapping configurations. Each column must specify a column -name. Each column can have a conversion type specified by its fully -qualified class name. By default, the conversion type is `String`. If -the configured type is assignment-compatible with -link:../javadoc/log4j-api/org/apache/logging/log4j/util/ReadOnlyStringMap.html[`ReadOnlyStringMap`] -/ -link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap.html[`ThreadContextMap`] -or -link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextStack.html[`ThreadContextStack`], -then that column will be populated with the MDC or NDC respectively -(this is database-specific how they handle inserting a `Map` or `List` -value). If the configured type is assignment-compatible with -`java.util.Date`, then the log timestamp will be converted to that -configured date type. If the configured type is assignment-compatible -with `java.sql.Clob` or `java.sql.NClob`, then the formatted event will -be set as a Clob or NClob respectively (similar to the traditional -ColumnConfig plugin). If a `literal` attribute is given, then its value -will be used as is in the `INSERT` query without any escaping. -Otherwise, the layout or pattern specified will be converted into the -configured type and stored in that column. - -|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. New in 2.11.2. - -|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 reconnect -fails then an exception will be thrown (which can be caught by the -application if `ignoreExceptions` is set to `false`). New in 2.11.2. -|======================================================================= - -When configuring the JDBCAppender, you must specify a `ConnectionSource` -implementation from which the Appender gets JDBC connections. -You must use exactly one of the following nested elements: - -* <`>>: Uses JNDI. -* <`>>: Points to a class-method pair to provide JDBC connections. -* <`>>: A quick and dirty way to get off the ground, no connection pooling. -* <`>>: Uses Apache Commons DBCP to provide connection pooling. - -[#JDBCDataSource] -.DataSource Parameters -[cols="20%,20%,60%",options="header",] -|======================================================================= -|Parameter Name |Type |Description -|jndiName |String |_Required._ The full, prefixed JNDI name that the -`javax.sql.DataSource` is bound to, such as -`java:/comp/env/jdbc/LoggingDatabase`. The `DataSource` must be backed -by a connection pool; otherwise, logging will be very slow. -|======================================================================= - -[#JDBCConnectionFactory] -.ConnectionFactory Parameters -[cols="20%,20%,60%",options="header",] -|======================================================================= -|Parameter Name |Type |Description -|class |Class |_Required._ The fully qualified name of a class -containing a static factory method for obtaining JDBC connections. - -|method |Method |_Required._ The name of a static factory method for -obtaining JDBC connections. This method must have no parameters and its -return type must be either `java.sql.Connection` or `DataSource`. If the -method returns `Connection`, it must obtain them from a connection pool -(and they will be returned to the pool when Log4j is done with them); -otherwise, logging will be very slow. If the method returns a -`DataSource`, the `DataSource` will only be retrieved once, and it must -be backed by a connection pool for the same reasons. -|======================================================================= - -[#JDBCDriverManager] -.DriverManager Parameters -[cols="20%,20%,60%",options="header",] -|======================================================================= -|Parameter Name |Type |Description -|connectionString |String |_Required._ The driver-specific JDBC -connection string. - -|userName |String |The database user name. You cannot specify both -properties and a username or password. - -|password |String |The database password. You cannot specify both -properties and a username or password. - -|driverClassName |String |The JDBC driver class name. Some old JDBC -driver can only be discovered by explicitly loading them by class name. - -|properties |Property[] |A list of properties. You cannot specify both -properties and a username or password. -|======================================================================= - -[#JDBCPoolingDriver] -.PoolingDriver Parameters (Apache Commons DBCP) -[cols="20%,20%,60%",options="header",] -|======================================================================= -|Parameter Name |Type |Description -|DriverManager parameters |DriverManager parameters |This connection -source inherits all parameters from the DriverManager connection source. - -|poolName |String |The pool name used to pool JDBC Connections. Defaults -to `example`. You can use the JDBC connection string prefix -`jdbc:apache:commons:dbcp:` followed by the pool name if you want to use -a pooled connection elsewhere. For example: -`jdbc:apache:commons:dbcp:example`. - -|PoolableConnectionFactory |PoolableConnectionFactory element |Defines a PoolableConnectionFactory. -|======================================================================= - -[#JDBCPoolableConnectionFactory] -.PoolableConnectionFactory Parameters (Apache Commons DBCP) -[cols="20%,20%,60%",options="header",] -|======================================================================= -|Parameter Name |Type |Description -|autoCommitOnReturn |boolean | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|cacheState |boolean | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|connectionInitSqls |Strings | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|defaultAutoCommit |Boolean | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|defaultCatalog |String | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|defaultQueryTimeoutSeconds |Integer | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|defaultReadOnly |Boolean | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|defaultTransactionIsolation |int | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|disconnectionSqlCodes |Strings | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|fastFailValidation |boolean | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|maxConnLifetimeMillis |long | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|maxOpenPreparedStatements |int | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|poolStatements |boolean | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|rollbackOnReturn |boolean | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|validationQuery |String | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|validationQueryTimeoutSeconds |int | See https://commons.apache.org/proper/commons-dbcp/configuration.html[Apache Commons DBCP configuration]. -|======================================================================= - -When configuring the JDBCAppender, use the nested `` elements to specify which columns in the table should be written to and how to write to them. -The JDBCAppender uses this information to formulate a -`PreparedStatement` to insert records without SQL injection vulnerability. - -.Column Parameters -[width="100%",cols="20%,20%,60%",options="header",] -|======================================================================= -|Parameter Name |Type |Description -|name |String |_Required._ The name of the database column. - -|pattern |String |Use this attribute to insert a value or values from -the log event in this column using a `PatternLayout` pattern. Simply -specify any legal pattern in this attribute. Either this attribute, -`literal`, or `isEventTimestamp="true"` must be specified, but not more -than one of these. - -|literal |String |Use this attribute to insert a literal value in this -column. The value will be included directly in the insert SQL, without -any quoting (which means that if you want this to be a string, your -value should contain single quotes around it like this: -`literal="'Literal String'"`). This is especially useful for databases -that don't support identity columns. For example, if you are using -Oracle you could specify `literal="NAME_OF_YOUR_SEQUENCE.NEXTVAL"` to -insert a unique ID in an ID column. Either this attribute, `pattern`, or -`isEventTimestamp="true"` must be specified, but not more than one of -these. - -|parameter |String a| -Use this attribute to insert an expression with a parameter marker '?' -in this column. The value will be included directly in the insert SQL, -without any quoting (which means that if you want this to be a string, -your value should contain single quotes around it like this: - -`` - -You can only specify one of `literal` or `parameter`. - -|isEventTimestamp |boolean |Use this attribute to insert the event -timestamp in this column, which should be a SQL `datetime`. The value will -be inserted as a `java.sql.Types.TIMESTAMP`. Either this attribute -(equal to `true`), `pattern`, or `isEventTimestamp` must be specified, -but not more than one of these. - -|isUnicode |boolean |This attribute is ignored unless `pattern` is -specified. If `true` or omitted (default), the value will be inserted as -unicode (`setNString` or `setNClob`). Otherwise, the value will be -inserted non-Unicode (`setString` or `setClob`). - -|isClob |boolean |This attribute is ignored unless `pattern` is -specified. Use this attribute to indicate that the column stores -Character Large Objects (CLOBs). If `true`, the value will be inserted -as a CLOB (`setClob` or `setNClob`). If `false` or omitted (default), -the value will be inserted as a VARCHAR or NVARCHAR (`setString` or -`setNString`). -|======================================================================= - -.ColumnMapping Parameters -[cols="20%,20%,60%",options="header",] -|======================================================================= -|Parameter Name |Type |Description -|name |String |_Required._ The name of the database column. - -|pattern |String |Use this attribute to insert a value or values from -the log event in this column using a `PatternLayout` pattern. Simply -specify any legal pattern in this attribute. Either this attribute, -`literal`, or `isEventTimestamp="true"` must be specified, but not more -than one of these. - -|literal |String |Use this attribute to insert a literal value in this -column. The value will be included directly in the insert SQL, without -any quoting (which means that if you want this to be a string, your -value should contain single quotes around it like this: -`literal="'Literal String'"`). This is especially useful for databases -that don't support identity columns. For example, if you are using -Oracle you could specify `literal="NAME_OF_YOUR_SEQUENCE.NEXTVAL"` to -insert a unique ID in an ID column. Either this attribute, `pattern`, or -`isEventTimestamp="true"` must be specified, but not more than one of -these. - -|layout |Layout |The Layout to format the LogEvent. - -|type |String |Conversion type name, a fully qualified class name. -|======================================================================= - -Here are a couple 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] ----- - - - - - - - - - - - - - - - - - - ----- - -[source,xml] ----- - - - - - - - - - - - - - - - - - - - ----- - -[source,java] ----- -package net.example.db; - -import java.sql.Connection; -import java.sql.SQLException; -import java.util.Properties; - -import javax.sql.DataSource; - -import org.apache.commons.dbcp.DriverManagerConnectionFactory; -import org.apache.commons.dbcp.PoolableConnection; -import org.apache.commons.dbcp.PoolableConnectionFactory; -import org.apache.commons.dbcp.PoolingDataSource; -import org.apache.commons.pool.impl.GenericObjectPool; - -public class ConnectionFactory { - private interface Singleton { - ConnectionFactory INSTANCE = new ConnectionFactory(); - } - - private final DataSource dataSource; - - private ConnectionFactory() { - Properties properties = new Properties(); - properties.setProperty("user", "logging"); - properties.setProperty("password", "abc123"); // or get properties from some configuration file - - GenericObjectPool pool = new GenericObjectPool(); - DriverManagerConnectionFactory connectionFactory = new DriverManagerConnectionFactory( - "jdbc:mysql://example.org:3306/exampleDb", properties - ); - new PoolableConnectionFactory( - connectionFactory, pool, null, "SELECT 1", 3, false, false, Connection.TRANSACTION_READ_COMMITTED - ); - - this.dataSource = new PoolingDataSource(pool); - } - - public static Connection getDatabaseConnection() throws SQLException { - return Singleton.INSTANCE.dataSource.getConnection(); - } -} ----- - -This appender is xref:manual/messages.adoc#MapMessage[`MapMessage`]-aware. - -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] ----- - - - - - - - - - - - - - - - - - - - - - - - - - ----- - [#jms-appender] === [[JMSAppender]]JMS Appender @@ -1211,184 +695,6 @@ To map your Log4j `MapMessage` to JMS `javax.jms.MapMessage`, set the layout of ---- -[[JPAAppender]] -=== JPAAppender - -As of Log4j 2.11.0, JPA support has moved from the existing module `log4j-core` to the new module `log4j-jpa`. - -The JPAAppender writes log events to a relational database table using the Java Persistence API 2.1. -It requires the API and a provider implementation to be on the classpath. -It also requires a decorated entity configured to persist to the table desired. - -If you want to use the default mappings, you can extend `org.apache.logging.log4j.core.appender.db.jpa.BasicLogEventEntity` and provide an `@Id` property. -If you want to significantly customize the mappings, you can extend `org.apache.logging.log4j.core.appender.db.jpa.AbstractLogEventWrapperEntity`. - -See the Javadoc or source code for these two classes for more information and examples. - -[width="100%",options="header"] -|=== -|Parameter Name |Type |Description - -|name -|String -|_Required._ The name of the Appender. - -|ignoreExceptions -|boolean -|The default is `true`, causing exceptions encountered while appending events to be internally logged and then ignored. When set to `false` exceptions will be propagated to the caller, instead. You must set this to `false` when wrapping this Appender in a FailoverAppender. - -|filter -|Filter -|A Filter to determine if the event should be handled by this Appender. More than one Filter may be used by using a CompositeFilter. - -|bufferSize -|int -|If an integer is greater than 0, this causes the appender to buffer log events and flush whenever the buffer reaches this size. - -|entityClassName -|String -|_Required._ The fully qualified name of the concrete LogEventWrapperEntity implementation that has JPA annotations mapping it to a database table. - -|persistenceUnitName -|String -|_Required._ The name of the JPA persistence unit that should be used for persisting log events. -|=== - -Here is a sample configuration for the JPAAppender. -The first XML sample is the Log4j configuration file, the second is the `persistence.xml` file. -EclipseLink is assumed here, but any JPA 2.1 or higher provider will do. -You should _always_ create a _separate_ persistence unit for logging, for two reasons. -First, `` _must_ be set to "NONE," which is usually not desired in normal JPA usage. -Also, for performance reasons the logging entity should be isolated in its persistence unit away from all other entities and you should use a non-JTA data source. -Note that your persistence unit _must_ also contain `` elements for all of the `org.apache.logging.log4j.core.appender.db.jpa.converter` converter classes. - -[source,xml] ----- - - - - - - - - - - - ----- - -[source,xml] ----- - - - - - org.eclipse.persistence.jpa.PersistenceProvider - org.apache.logging.log4j.core.appender.db.jpa.converter.ContextMapAttributeConverter - org.apache.logging.log4j.core.appender.db.jpa.converter.ContextMapJsonAttributeConverter - org.apache.logging.log4j.core.appender.db.jpa.converter.ContextStackAttributeConverter - org.apache.logging.log4j.core.appender.db.jpa.converter.ContextStackJsonAttributeConverter - org.apache.logging.log4j.core.appender.db.jpa.converter.MarkerAttributeConverter - org.apache.logging.log4j.core.appender.db.jpa.converter.MessageAttributeConverter - org.apache.logging.log4j.core.appender.db.jpa.converter.StackTraceElementAttributeConverter - org.apache.logging.log4j.core.appender.db.jpa.converter.ThrowableAttributeConverter - com.example.logging.JpaLogEntity - jdbc/LoggingDataSource - NONE - - - ----- - -[source,java] ----- -package com.example.logging; -... -@Entity -@Table(name="application_log", schema="dbo") -public class JpaLogEntity extends BasicLogEventEntity { - private static final long serialVersionUID = 1L; - private long id = 0L; - - public TestEntity() { - super(null); - } - public TestEntity(LogEvent wrappedEvent) { - super(wrappedEvent); - } - - @Id - @GeneratedValue(strategy = GenerationType.IDENTITY) - @Column(name = "id") - public long getId() { - return this.id; - } - - public void setId(final long id) { - this.id = id; - } - - // If you want to override the mapping of any properties mapped in BasicLogEventEntity, - // just override the getters and re-specify the annotations. -} ----- - -[source,java] ----- -package com.example.logging; -... -@Entity -@Table(name="application_log", schema="dbo") -public class JpaLogEntity extends AbstractLogEventWrapperEntity { - private static final long serialVersionUID = 1L; - private long id = 0L; - - public TestEntity() { - super(null); - } - public TestEntity(final LogEvent wrappedEvent) { - super(wrappedEvent); - } - - @Id - @GeneratedValue(strategy = GenerationType.IDENTITY) - @Column(name = "logEventId") - public long getId() { - return this.id; - } - - public void setId(final long id) { - this.id = id; - } - - @Override - @Enumerated(EnumType.STRING) - @Column(name = "level") - public Level getLevel() { - return this.getWrappedEvent().getLevel(); - } - - @Override - @Column(name = "logger") - public String getLoggerName() { - return this.getWrappedEvent().getLoggerName(); - } - - @Override - @Column(name = "message") - @Convert(converter = MyMessageConverter.class) - public Message getMessage() { - return this.getWrappedEvent().getMessage(); - } - ... -} ----- - [#HttpAppender] === HttpAppender @@ -1559,428 +865,6 @@ _Note:_ Make sure to not let `org.apache.kafka` log to a Kafka appender on DEBUG ---- -[#NoSQLAppender] -=== NoSQLAppender - -The NoSQLAppender writes log events to a NoSQL database using an internal lightweight provider interface. -Provider implementations currently exist for MongoDB, and writing a custom provider is quite simple. - -.NoSQLAppender Parameters -[cols="20%,20%,60%",options="header",] -|======================================================================= -|Parameter Name |Type |Description -|name |String |_Required._ The name of the Appender. - -|ignoreExceptions |boolean |The default is `true`, causing exceptions -encountered while appending events to be internally logged and then -ignored. When set to `false` exceptions will be propagated to the -caller, instead. You must set this to `false` when wrapping this -Appender in a <>. - -|filter |Filter |A Filter to determine if the event should be handled by -this Appender. More than one Filter may be used by using a -CompositeFilter. - -|bufferSize |int |If an integer is greater than 0, this causes the appender -to buffer log events and flush whenever the buffer reaches this size. - -|NoSqlProvider |NoSQLProvider>> |_Required._ The NoSQL provider that provides -connections to the chosen NoSQL database. -|======================================================================= - -.`NoSqlAppender` -- nested elements -[cols="1m,1,4",id=NoSqlAppender-element-keyValuePairs] -|=== -| Type | Multiplicity | Description - -| 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]. - -|=== - -You specify which NoSQL provider to use by specifying the appropriate configuration element within the `` element. -The only type currently supported is ``. -To create your custom provider, read the JavaDoc for the `NoSQLProvider`, `NoSQLConnection`, and `NoSQLObject` classes and the documentation about creating Log4j plugins. -We recommend you review the source code for the MongoDB providers as a guide for creating your provider. - -The following example demonstrates how log events are persisted in NoSQL databases if represented in a JSON format: - -[source,json] ----- -{ - "level": "WARN", - "loggerName": "com.example.application.MyClass", - "message": "Something happened that you might want to know about.", - "source": { - "className": "com.example.application.MyClass", - "methodName": "exampleMethod", - "fileName": "MyClass.java", - "lineNumber": 81 - }, - "marker": { - "name": "SomeMarker", - "parent" { - "name": "SomeParentMarker" - } - }, - "threadName": "Thread-1", - "millis": 1368844166761, - "date": "2013-05-18T02:29:26.761Z", - "thrown": { - "type": "java.sql.SQLException", - "message": "Could not insert record. Connection lost.", - "stackTrace": [ - { "className": "org.example.sql.driver.PreparedStatement$1", "methodName": "responder", "fileName": "PreparedStatement.java", "lineNumber": 1049 }, - { "className": "org.example.sql.driver.PreparedStatement", "methodName": "executeUpdate", "fileName": "PreparedStatement.java", "lineNumber": 738 }, - { "className": "com.example.application.MyClass", "methodName": "exampleMethod", "fileName": "MyClass.java", "lineNumber": 81 }, - { "className": "com.example.application.MainClass", "methodName": "main", "fileName": "MainClass.java", "lineNumber": 52 } - ], - "cause": { - "type": "java.io.IOException", - "message": "Connection lost.", - "stackTrace": [ - { "className": "java.nio.channels.SocketChannel", "methodName": "write", "fileName": null, "lineNumber": -1 }, - { "className": "org.example.sql.driver.PreparedStatement$1", "methodName": "responder", "fileName": "PreparedStatement.java", "lineNumber": 1032 }, - { "className": "org.example.sql.driver.PreparedStatement", "methodName": "executeUpdate", "fileName": "PreparedStatement.java", "lineNumber": 738 }, - { "className": "com.example.application.MyClass", "methodName": "exampleMethod", "fileName": "MyClass.java", "lineNumber": 81 }, - { "className": "com.example.application.MainClass", "methodName": "main", "fileName": "MainClass.java", "lineNumber": 52 } - ] - } - }, - "contextMap": { - "ID": "86c3a497-4e67-4eed-9d6a-2e5797324d7b", - "username": "JohnDoe" - }, - "contextStack": [ - "topItem", - "anotherItem", - "bottomItem" - ] -} ----- - -[#NoSQLAppenderMongoDB] -==== NoSQL providers for MongoDB - -[#mongo-installation] -===== Installation - -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 user 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. -==== - -[#log4j-mongodb] -===== NoSQL provider for MongoDB (current) - -This section details specializations of the -<> provider for MongoDB using the current MongoDB driver (version 5). -The NoSQLAppender Appender writes log events to a NoSQL database using an internal lightweight provider interface. - -.MongoDB Provider Parameters -[cols="20%,20%,60%",options="header",] -|======================================================================= -|Parameter Name |Type |Description -|connection |String |_Required._ The MongoDB -http://mongodb.github.io/mongo-java-driver/5.0/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html?is-external=true"[connection string] -in the format `mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database.collection][?options]]`. - -|capped |boolean |Enable support for -https://www.mongodb.com/docs/manual/core/capped-collections/[capped -collections] - -|collectionSize |long |Specify the size in bytes of the capped collection -to use if enabled. The minimum size is 4096 bytes, and larger sizes will -be increased to the nearest integer multiple of 256. See the capped -collection documentation linked above for more information. -|======================================================================= - -This appender is xref:manual/messages.adoc#MapMessage[MapMessage]-aware. - -Here are a few sample configurations for the NoSQLAppender and MongoDB4 provider: - -[source,xml] ----- - - - - - - - - - - - - - ----- - -[source,xml] ----- - - - - - - - - - - - - - ----- - -You can define additional fields to log using KeyValuePair elements, for example: - -[source,xml] ----- - - - - - - - - - - - - - - - - - ----- - -[#log4j-mongodb4] -===== [[NoSQLAppenderMongoDB4]] NoSQL provider for MongoDB 4 (deprecated) - -The `log4j-mongodb4` module is deprecated in favor of <>. - -This section details specializations of the -<> provider for MongoDB using the MongoDB driver version 4. The NoSQLAppender Appender writes log events to a NoSQL database using an internal lightweight provider interface. - -.MongoDB Provider Parameters -[cols="20%,20%,60%",options="header",] -|======================================================================= -|Parameter Name |Type |Description -|connection |String |_Required._ The MongoDB -http://mongodb.github.io/mongo-java-driver/4.0/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html?is-external=true"[connection string] -in the format `mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database.collection][?options]]`. - -|capped |boolean |Enable support for -https://www.mongodb.com/docs/manual/core/capped-collections/[capped -collections] - -|collectionSize |long |Specify the size in bytes of the capped collection -to use if enabled. The minimum size is 4096 bytes, and larger sizes will -be increased to the nearest integer multiple of 256. See the capped -collection documentation linked above for more information. -|======================================================================= - -This appender is xref:manual/messages.adoc#MapMessage[MapMessage]-aware. - -Here are a few sample configurations for the NoSQLAppender and MongoDB4 provider: - -[source,xml] ----- - - - - - - - - - - - - - ----- - -[source,xml] ----- - - - - - - - - - - - - - ----- - -You can define additional fields to log using KeyValuePair elements, for example: - -[source,xml] ----- - - - - - - - - - - - - - - - - - ----- - -[[NoSQLAppenderApacheCouchDB]] -=== NoSQLAppender for Apache CouchDB - -This section details specializations of the <> provider for CouchDB. -The NoSQLAppender writes log events to a NoSQL database using an internal lightweight provider interface. - -[width="100%",options="header"] -|=== -|Parameter Name |Type |Description - -|factoryClassName -|Class -|To provide a connection to the CouchDB database, you can use this attribute and `factoryMethodName` to specify a class and static method to retrieve the connection. The method must return an `org.lightcouch.CouchDbClient` or a `org.lightcouch.CouchDbProperties`. If you use the factory method for providing a connection, you must not specify the `databaseName`, `protocol`, `server`, `port`, `username`, or `password` attributes. - -|factoryMethodName -|Method -|See the documentation for attribute `factoryClassName`. - -|databaseName -|String -|If you do not specify a `factoryClassName` and `factoryMethodName` for providing a CouchDB connection, you must specify a CouchDB database name using this attribute. You must also specify a `username` and `password`. You can optionally also specify a `protocol` (defaults to `http`), `server` (defaults to localhost), and a `port` (defaults to 80 for `http` and 443 for `https`). - -|protocol -|String -|Must either be "http" or "https." See the documentation for attribute `databaseName`. - -|server -|String -|See the documentation for attribute `databaseName`. - -|port -|int -|See the documentation for attribute `databaseName`. - -|username -|String -|See the documentation for attributes `databaseName`. - -|password -|String -|See the documentation for attributes `databaseName`. -|=== - -Here are a few sample configurations for the NoSQLAppender and CouchDB provider: - -[source,xml] ----- - - - - - - - - - - - - - ----- - [#servlet-appender] === Servlet appender diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders/database.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders/database.adoc new file mode 100644 index 00000000000..a6359c64478 --- /dev/null +++ b/src/site/antora/modules/ROOT/pages/manual/appenders/database.adoc @@ -0,0 +1,1580 @@ +//// + 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: + +[#ColumnMapping-attributes] +.`ColumnMapping` configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[ColumnMapping-attr-name]]name +| `String` +| +| The name of the column. + +4+h| Optional + +| [[ColumnMapping-attr-columnType]]columnType +| `Class` +| `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 <>. +. 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. + +| [[ColumnMapping-attr-type]]type +| `Class` +| `String` +| +**Deprecated**: since `2.21.0` use <> instead. + +| [[ColumnMapping-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. +==== + +| [[ColumnMapping-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. +==== + +| [[ColumnMapping-attr-pattern]]pattern +| `String` +| +| +This is a shortcut configuration attribute to set the +<> +to a xref:manual/pattern-layout.adoc[`PatternLayout`] +instance with the specified `pattern` property. + +| [[ColumnMapping-attr-source]]source +| `String` +| <> +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 <> +is a +link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MessageLayout.html[`MessageLayout`]. +* The message being logged is a `MapMessage` +|=== + +[#ColumnMapping-elements] +.`ColumnMapping` nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[ColumnMapping-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`] + +An example column mapping might look like this: + +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/column-mapping.xml[`log4j2.xml`] +[source,xml,indent=0] +---- +include::example$manual/appenders/database/column-mapping.xml[tag=mapping] +---- + +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/column-mapping.json[`log4j2.json`] +[source,json,indent=0] +---- +include::example$manual/appenders/database/column-mapping.json[tag=mapping] +---- + +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/column-mapping.yaml[`log4j2.yaml`] +[source,yaml,indent=0] +---- +include::example$manual/appenders/database/column-mapping.yaml[tag=mapping] +---- + +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/column-mapping.properties[`log4j2.properties`] +[source,properties,indent=0] +---- +include::example$manual/appenders/database/column-mapping.properties[tag=mapping] +---- +==== + +<1> A database-specific expression is added literally to the `INSERT` statement. +<2> A xref:manual/pattern-layout.adoc[] with the specified pattern is used for these columns. +The `uuid` column is additionally converted into a `java.util.UUID` before being sent to the JDBC driver. +<3> Three special column types are replaced with the log event timestamp, context map, and context stack. +<4> A xref:manual/json-template-layout.adoc[] is used to format this column. +<5> If the global layout of the appender returns a `MapMessage`, the value for key `resourceId` will be put into the `resource` column. + +[#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]]<> +| one or more +a| +A list of <> configurations. +The following database-specific restrictions apply: + +* the <> must be a valid +https://cassandra.apache.org/doc/stable/cassandra/cql/definitions.html#identifiers[CQL identifier]. +* the <> must be a valid +https://cassandra.apache.org/doc/stable/cassandra/cql/definitions.html#terms[CQL term]. +* the <> has a fixed value of `?`. + +| [[CassandraAppender-element-SocketAddress]]<> +| one or more +| A list of Cassandra node addresses to connect to. +If absent, `localhost:9042` will be used. + +See <> for the configuration syntax. +|=== + +Additional runtime dependencies are required for using the Cassandra Appender: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- + + + org.apache.logging.log4j + log4j-cassandra + runtime + +---- + +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: + +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/cassandra.xml[`log4j2.xml`] +[source,xml,indent=0] +---- +include::example$manual/appenders/database/cassandra.xml[tag=appender] +---- + +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/cassandra.json[`log4j2.json`] +[source,json,indent=0] +---- +include::example$manual/appenders/database/cassandra.json[tag=appender] +---- + +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/cassandra.yaml[`log4j2.yaml`] +[source,yaml,indent=0] +---- +include::example$manual/appenders/database/cassandra.yaml[tag=appender] +---- + +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/cassandra.properties[`log4j2.properties`] +[source,properties,indent=0] +---- +include::example$manual/appenders/database/cassandra.properties[tag=appender] +---- +==== + +<1> Enables buffering. +Messages are sent in batches of 10. +<2> Multiple server addresses can be used. +<3> An example of column mapping. +See <> for more details. + +The example above uses the following table schema: + +[source,sql] +---- +include::example$manual/appenders/database/cassandra.sql[lines=17..-1] +---- + +[#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 <>. + +If batch statements are supported by the configured JDBC driver and +<> +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 +<> +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]]<> +| zero or more +a| +A list of <> configurations. +The following database-specific restrictions apply: + +* the <> must be a valid SQL identifier. +* the <> must be a valid SQL term. +* the <> must be a valid SQL term containing a `?` placeholder. + +**Required**, unless <> 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 <>. + +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]]<> +| **one** +| +It specifies how to retrieve JDBC +https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html[`Connection`] +objects. + +See <> for more details. + +| [[JdbcAppender-element-Layout]]<> +| zero or one +| +An optional +link:../javadoc/log4j-core/org/apache/logging/log4j/core/Layout.html[`Layout`] +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 <> 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 +| `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 <> 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 <> and <> 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 <> and <> 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] +---- + + + org.apache.logging.log4j + log4j-jdbc-dbcp2 + runtime + +---- + +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 <`>> is provided, log events containing messages of type +xref:manual/messages.adoc#MapMessage[`MapMessage`] +will be treated specially. +For each <> (except those containing literals) the <> attribute will be used as key to the value in `MapMessage` that will be stored in column <>. + +[#JdbcAppender-examples] +=== Configuration examples + +Here is an example JDBC Appender configuration: + +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/jdbc.xml[`log4j2.xml`] +[source,xml,indent=0] +---- +include::example$manual/appenders/database/jdbc.xml[tag=appender] +---- + +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/jdbc.json[`log4j2.json`] +[source,json,indent=0] +---- +include::example$manual/appenders/database/jdbc.json[tag=appender] +---- + +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/jdbc.yaml[`log4j2.yaml`] +[source,yaml,indent=0] +---- +include::example$manual/appenders/database/jdbc.yaml[tag=appender] +---- + +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/jdbc.properties[`log4j2.properties`] +[source,properties,indent=0] +---- +include::example$manual/appenders/database/jdbc.properties[tag=appender] +---- +==== + +<1> Enables buffering. +Messages are sent in batches of 10. +<2> A <> is used. +<3> An example of column mapping. +See <> for more details. + +The example above uses the following table schema: + +[source,sql] +---- +include::example$manual/appenders/database/jdbc.sql[lines=17..-1] +---- + +[#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 <> below. +* configure the JPA Appender. +See <> 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 +| `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] +---- + + + org.apache.logging.log4j + log4j-jpa + runtime + +---- + +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 + +Using the persistence unit from section <>, the JPA appender can be easily configured as: + +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/jpa.xml[`log4j2.xml`] +[source,xml,indent=0] +---- +include::example$manual/appenders/database/jpa.xml[tag=appender] +---- + +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/jpa.json[`log4j2.json`] +[source,json,indent=0] +---- +include::example$manual/appenders/database/jpa.json[tag=appender] +---- + +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/jpa.yaml[`log4j2.yaml`] +[source,yaml,indent=0] +---- +include::example$manual/appenders/database/jpa.yaml[tag=appender] +---- + +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/jpa.properties[`log4j2.properties`] +[source,properties,indent=0] +---- +include::example$manual/appenders/database/jpa.properties[tag=appender] +---- +==== + +[#NoSqlAppender] +== NoSQL Appender + +The NoSQL Appender writes log events to a +https://en.wikipedia.org/wiki/Document-oriented_database#Implementations[document-oriented 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]]<> +| zero or one +| +An optional +link:../javadoc/log4j-core/org/apache/logging/log4j/core/Layout.html[`Layout`] +implementation that formats a log event as +xref:manual/messages.adoc#MapMessage[`MapMessage`]. + +See <> 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 NoSQL documents in two ways: + +* If the optional <> configuration element is provided, the +xref:manual/messages.adoc#MapMessage[`MapMessage`] returned by the layout will be converted into its NoSQL document. +* Otherwise, a default conversion will be applied. +You enhance the format with additional top level key/value pairs using nested +<> 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 documents, and it 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 <> below for more details. +* A provider for the +https://couchdb.apache.org/[Apache CouchDB database]. +See <> 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] +---- + + + org.apache.logging.log4j + log4j-mongodb + runtime + +---- + +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 <>. +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] +---- + + + org.apache.logging.log4j + log4j-mongodb4 + runtime + +---- + +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 <> with an +https://couchdb.apache.org/[Apache CouchDB database]. +The provider can be configured by: + +* either providing some <>, +* or providing a <>. + +[#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` (`http`) +`443` (`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 +| `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] +---- + + + org.apache.logging.log4j + log4j-couchdb + runtime + +---- + +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 + +To connect the NoSQL Appender to a MongoDB database, you only need to provide a connection string: + +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo.xml[`log4j2.xml`] +[source,xml,indent=0] +---- +include::example$manual/appenders/database/nosql-mongo.xml[tag=appender] +---- + +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo.json[`log4j2.json`] +[source,json,indent=0] +---- +include::example$manual/appenders/database/nosql-mongo.json[tag=appender] +---- + +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo.yaml[`log4j2.yaml`] +[source,yaml,indent=0] +---- +include::example$manual/appenders/database/nosql-mongo.yaml[tag=appender] +---- + +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo.properties[`log4j2.properties`] +[source,properties,indent=0] +---- +include::example$manual/appenders/database/nosql-mongo.properties[tag=appender] +---- +==== + +A similar configuration for an Apache CouchDB database looks like: + +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-couch.xml[`log4j2.xml`] +[source,xml,indent=0] +---- +include::example$manual/appenders/database/nosql-couch.xml[tag=appender] +---- + +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-couch.json[`log4j2.json`] +[source,json,indent=0] +---- +include::example$manual/appenders/database/nosql-couch.json[tag=appender] +---- + +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-couch.yaml[`log4j2.yaml`] +[source,yaml,indent=0] +---- +include::example$manual/appenders/database/nosql-couch.yaml[tag=appender] +---- + +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-couch.properties[`log4j2.properties`] +[source,properties,indent=0] +---- +include::example$manual/appenders/database/nosql-couch.properties[tag=appender] +---- +==== + +You can define additional fields to the NoSQL document using <>, for example: + +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo-keys.xml[`log4j2.xml`] +[source,xml,indent=0] +---- +include::example$manual/appenders/database/nosql-mongo-keys.xml[tag=appender] +---- + +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo-keys.json[`log4j2.json`] +[source,json,indent=0] +---- +include::example$manual/appenders/database/nosql-mongo-keys.json[tag=appender] +---- + +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo-keys.yaml[`log4j2.yaml`] +[source,yaml,indent=0] +---- +include::example$manual/appenders/database/nosql-mongo-keys.yaml[tag=appender] +---- + +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/database/nosql-mongo-keys.properties[`log4j2.properties`] +[source,properties,indent=0] +---- +include::example$manual/appenders/database/nosql-mongo-keys.properties[tag=appender] +---- +==== + +<1> This lookup is evaluated at configuration time and gives the time when Log4j was most recently reconfigured. +<2> This lookup is evaluated at runtime and gives the current date. +See xref:manual/configuration.adoc#lazy-property-substitution[runtime lookup evaluation] for more details. diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders/rolling-file.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders/rolling-file.adoc index 5d5c5fb00b7..c9756338068 100644 --- a/src/site/antora/modules/ROOT/pages/manual/appenders/rolling-file.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/appenders/rolling-file.adoc @@ -313,7 +313,7 @@ xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-loggin == Triggering Policies Triggering policies are Log4j plugins that implement the -link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/rolling/TriggeringPolicy.html[`TriggeringPolicy`] +link:../../javadoc/log4j-core/org/apache/logging/log4j/core/appender/rolling/TriggeringPolicy.html[`TriggeringPolicy`] interface and are used to decide when is it time to rollover the current log file. xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-TriggeringPolicy[{open-book} Plugin reference for `TriggeringPolicy`] diff --git a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc index d0677a4819f..6b8e2ff940e 100644 --- a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc @@ -16,6 +16,7 @@ //// = Layouts +:open-book: 📖 An xref:manual/appenders.adoc[appender] uses a *layout* to encode a link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html[`LogEvent`] into a form that meets the needs of whatever will be consuming the log event. This page will try to answer following questions: @@ -65,7 +66,7 @@ Refer to xref:manual/pattern-layout.adoc[]. Following sections explain all predefined layouts in detail. -xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-Layout[📖 Plugin reference for all `Layout` implementations] +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-Layout[{open-book} Plugin reference for all `Layout` implementations] [#csv-layouts] === [[CSVLayouts]] CSV Layouts @@ -78,7 +79,7 @@ There are two layouts performing https://en.wikipedia.org/wiki/Comma-separated_v `CsvParameterLayout` encodes *only* the parameters of the message of a log event. Generated CSV records will be composed of fields denoting the message parameters. -xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-CsvParameterLayout[📖 Plugin reference for `CsvParameterLayout`] +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-CsvParameterLayout[{open-book} Plugin reference for `CsvParameterLayout`] .Click here for examples [%collapsible] @@ -129,7 +130,7 @@ Generated CSV records will be composed of following fields in the given order: . Thread context map . Thread context stack -xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-CsvLogEventLayout[📖 Plugin reference for `CsvLogEventLayout`] +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-CsvLogEventLayout[{open-book} Plugin reference for `CsvLogEventLayout`] .Click here for examples [%collapsible] @@ -238,7 +239,7 @@ This layout does not implement chunking. Unless compression is needed, we advise you to use xref:manual/json-template-layout.adoc[JSON Template Layout] instead, which provides GELF Layout support out of the box and offers more capabilities and performance. ==== -xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-GelfLayout[📖 Plugin reference for `GelfLayout`] +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-GelfLayout[{open-book} Plugin reference for `GelfLayout`] GELF Layout is configured with the following parameters: @@ -385,6 +386,7 @@ Properties:: include::example$manual/gelf-layout/log4j2.properties[lines=17..48,indent=0] ---- ===== + <1> Configuration with additional key value pairs <2> Configuration for appending to a Graylog server using TCP <3> Configuration for appending to a Graylog server using UDP @@ -395,7 +397,7 @@ include::example$manual/gelf-layout/log4j2.properties[lines=17..48,indent=0] `HtmlLayout` generates an HTML page, and adds each log event to a row in a table. -xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-HtmlLayout[📖 Plugin reference for `HtmlLayout`] +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-HtmlLayout[{open-book} Plugin reference for `HtmlLayout`] It is configured with the following parameters: @@ -453,7 +455,7 @@ JSON Layout is considered deprecated. It is succeeded by <> providing more capabilities and efficiency. ==== -xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-JsonLayout[📖 Plugin reference for `JsonLayout`] +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-JsonLayout[{open-book} Plugin reference for `JsonLayout`] .Click for an example output [%collapsible] @@ -650,6 +652,7 @@ For instance, given the following event template stored in `MyLayout.json` in yo } } ---- + <1> Using the `timestamp` event template resolver to populate the `instant` field <2> Passing a constant that will be rendered as is <3> Using the `message` event template resolver to populate the `message` field @@ -697,6 +700,7 @@ JSON Template Layout generates JSON as follows: ---- {"instant":"2017-05-25T19:56:23.370Z","someConstant":1,"message":"Hello, error!"} //<1> ---- + <1> JSON pretty-printing is not supported for performance reasons. Good news is JSON Template Layout is perfectly production-ready without any configuration! @@ -704,6 +708,17 @@ It bundles several predefined event templates modeling popular JSON-based log fo Read more on xref:manual/json-template-layout.adoc[]... +[#MapMessageLayout] +=== Message Layout + +`MessageLayout` is a special layout that extracts the +xref:manual/messages.adoc[`Message`] +contained in a log event. +It is currently only useful with the +xref:manual/appenders/database.adoc#JdbcAppender[JDBC Appender]. + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-MessageLayout[{open-book} Plugin reference for `MessageLayout`] + [id=pattern-layout] === [[PatternLayout]] Pattern Layout @@ -745,7 +760,7 @@ Read more on xref:manual/pattern-layout.adoc[]... RFC 5424 obsoletes RFC 3164, implemented by <>. ==== -xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-Rfc5424Layout[📖 Plugin reference for `Rfc5424Layout`] +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-Rfc5424Layout[{open-book} Plugin reference for `Rfc5424Layout`] RFC 5424 Layout is configured with the following parameters: @@ -858,7 +873,7 @@ Java Serialization has inherent security weaknesses. *Serialized Layout users are strongly advised to migrate to another layout!* ==== - xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-SerializedLayout[📖 Plugin reference for `SerializedLayout`] + xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-SerializedLayout[{open-book} Plugin reference for `SerializedLayout`] [#SyslogLayout] === Syslog Layout @@ -871,7 +886,7 @@ This matches the same format used by {logging-services-url}/log4j/1.x/index.html RFC 3164, implemented by Syslog Layout, is obsoleted by RFC 5424, implemented by <>. ==== -xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-SyslogLayout[📖 Plugin reference for `SyslogLayout`] +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-SyslogLayout[{open-book} Plugin reference for `SyslogLayout`] Syslog Layout is configured with the following parameters: @@ -911,7 +926,7 @@ It defaults to `LOCAL0`. XML Layout users are strongly advised to migrate to another layout! ==== -xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-XmlLayout[📖 Plugin reference for `XmlLayout`] +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-XmlLayout[{open-book} Plugin reference for `XmlLayout`] .Click for an example output [%collapsible] @@ -1010,7 +1025,7 @@ YAML is a superset of JSON. *We strongly advise existing YAML Layout users to migrate to <>* providing more capabilities and efficiency. ==== -xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-YamlLayout[📖 Plugin reference for `YamlLayout`] +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-YamlLayout[{open-book} Plugin reference for `YamlLayout`] .Click for an example output [%collapsible] diff --git a/src/site/antora/modules/ROOT/pages/manual/thread-context.adoc b/src/site/antora/modules/ROOT/pages/manual/thread-context.adoc index a613f960c10..c22a14a3961 100644 --- a/src/site/antora/modules/ROOT/pages/manual/thread-context.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/thread-context.adoc @@ -29,7 +29,9 @@ The entry point for associating logging-related information with the executing t link:../javadoc/log4j-api/org/apache/logging/log4j/ThreadContext.html[`ThreadContext`]. It offers both +[#mdc] * map-structured – referred to as _Thread Context Map_ or _Mapped Diagnostic Context (MDC)_ +[#ndc] * stack-structured – referred to as _Thread Context Stack_ or _Nested Diagnostic Context (NDC)_ storage: