You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by vy...@apache.org on 2024/06/11 18:05:45 UTC
(logging-log4j2) branch 2.x updated: Revamp the `Layouts` page (#2645)
This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/2.x by this push:
new ab70d4864f Revamp the `Layouts` page (#2645)
ab70d4864f is described below
commit ab70d4864f461506a342f4a23d977f39105f2828
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Tue Jun 11 20:05:34 2024 +0200
Revamp the `Layouts` page (#2645)
Co-authored-by: Piotr P. Karwasz <pi...@karwasz.org>
---
src/site/antora/antora.tmpl.yml | 4 +-
src/site/antora/antora.yml | 4 +-
.../modules/ROOT/examples/hibernate/log4j2.json | 8 +-
.../ROOT/examples/manual/gelf-layout/log4j2.json | 68 +
.../examples/manual/gelf-layout/log4j2.properties | 53 +
.../ROOT/examples/manual/gelf-layout/log4j2.xml | 53 +
.../ROOT/examples/manual/gelf-layout/log4j2.yaml | 61 +
.../eventTemplateAdditionalField/log4j2.json | 41 +
.../eventTemplateAdditionalField/log4j2.properties | 38 +
.../eventTemplateAdditionalField/log4j2.xml | 52 +
.../eventTemplateAdditionalField/log4j2.yaml | 41 +
.../manual/json-template-layout/usage/log4j2.json | 20 +
.../json-template-layout/usage/log4j2.properties | 23 +
.../manual/json-template-layout/usage/log4j2.xml | 36 +
.../manual/json-template-layout/usage/log4j2.yaml | 29 +
.../marker-pattern-selector/log4j2.json | 28 +
.../marker-pattern-selector/log4j2.properties | 27 +
.../marker-pattern-selector/log4j2.xml | 40 +
.../marker-pattern-selector/log4j2.yaml | 33 +
.../script-pattern-selector/log4j2.json | 37 +
.../script-pattern-selector/log4j2.properties | 41 +
.../script-pattern-selector/log4j2.xml | 50 +
.../script-pattern-selector/log4j2.yaml | 46 +
.../manual/pattern-layout/usage/log4j2.json | 20 +
.../manual/pattern-layout/usage/log4j2.properties | 23 +
.../manual/pattern-layout/usage/log4j2.xml | 36 +
.../manual/pattern-layout/usage/log4j2.yaml | 29 +
src/site/antora/modules/ROOT/nav.adoc | 1 +
.../modules/ROOT/pages/manual/appenders.adoc | 2 +-
.../modules/ROOT/pages/manual/configuration.adoc | 20 +-
.../modules/ROOT/pages/manual/extending.adoc | 85 -
.../modules/ROOT/pages/manual/garbagefree.adoc | 2 +-
.../modules/ROOT/pages/manual/getting-started.adoc | 4 +-
.../modules/ROOT/pages/manual/installation.adoc | 3 +-
.../ROOT/pages/manual/json-template-layout.adoc | 1391 ++++++-----
.../antora/modules/ROOT/pages/manual/layouts.adoc | 2631 ++++++--------------
.../modules/ROOT/pages/manual/pattern-layout.adoc | 1739 +++++++++++++
.../modules/ROOT/pages/manual/performance.adoc | 2 +-
.../antora/modules/ROOT/pages/manual/plugins.adoc | 9 -
.../manual/dependencies-log4j-layout-json.adoc | 38 -
.../dependencies-log4j-layout-template-json.adoc | 38 -
.../manual/dependencies-log4j-layout-xml.adoc | 38 -
.../manual/dependencies-log4j-layout-yaml.adoc | 38 -
...s-log4j-csv.adoc => layouts-gcfree-lookup.adoc} | 25 +-
.../manual/layouts-location-information.adoc | 2 +-
.../ROOT/partials/manual/plugin-preliminaries.adoc | 25 +
src/site/resources/.htaccess | 41 +
47 files changed, 4199 insertions(+), 2876 deletions(-)
diff --git a/src/site/antora/antora.tmpl.yml b/src/site/antora/antora.tmpl.yml
index 32b48b1ac6..6be7c65d8c 100644
--- a/src/site/antora/antora.tmpl.yml
+++ b/src/site/antora/antora.tmpl.yml
@@ -39,8 +39,8 @@ start_page: index.adoc
asciidoc:
attributes:
# Commons
- antora-examples-url: "https://raw.githubusercontent.com/apache/logging-log4j2/2.x/src/site/antora/modules/ROOT/examples"
- project-github-url: "${scm.url}"
+ antora-examples-url: "${scm.url}/tree/${scm.tag}/src/site/antora/modules/ROOT/examples"
+ project-github-url: "${scm.url}/tree/${scm.tag}"
project-name: "Log4j"
project-id: "log4j"
java-target-version: "${maven.compiler.target}"
diff --git a/src/site/antora/antora.yml b/src/site/antora/antora.yml
index f1ce58368e..0feb6d46f3 100644
--- a/src/site/antora/antora.yml
+++ b/src/site/antora/antora.yml
@@ -39,8 +39,8 @@ start_page: index.adoc
asciidoc:
attributes:
# Commons
- antora-examples-url: "https://raw.githubusercontent.com/apache/logging-log4j2/2.x/src/site/antora/modules/ROOT/examples"
- project-github-url: "https://github.com/apache/logging-log4j2/"
+ antora-examples-url: "https://github.com/apache/logging-log4j2/tree/2.x/src/site/antora/modules/ROOT/examples"
+ project-github-url: "https://github.com/apache/logging-log4j2/tree/2.x"
project-name: "Log4j"
project-id: "log4j"
java-target-version: "8"
diff --git a/src/site/antora/modules/ROOT/examples/hibernate/log4j2.json b/src/site/antora/modules/ROOT/examples/hibernate/log4j2.json
index 593aa3c048..4859561c8c 100644
--- a/src/site/antora/modules/ROOT/examples/hibernate/log4j2.json
+++ b/src/site/antora/modules/ROOT/examples/hibernate/log4j2.json
@@ -36,10 +36,10 @@
],
"Root": {
- "level": "WARN"
- },
- "AppenderRef": {
- "ref": "CONSOLE"
+ "level": "WARN",
+ "AppenderRef": {
+ "ref": "CONSOLE"
+ }
}
}
}
diff --git a/src/site/antora/modules/ROOT/examples/manual/gelf-layout/log4j2.json b/src/site/antora/modules/ROOT/examples/manual/gelf-layout/log4j2.json
new file mode 100644
index 0000000000..06f037f77a
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/gelf-layout/log4j2.json
@@ -0,0 +1,68 @@
+{
+ "Configuration": {
+ "Appenders": {
+
+ "Console": {
+ "name": "CONSOLE",
+ "GelfLayout": { //<1>
+ "messagePattern": "%d %5p [%t] %c{1} %X{loginId, requestId} - %m%n",
+ "includeThreadContext": "true",
+ "threadContextIncludes": "loginId,requestId",
+ "KeyValuePair": [
+ {
+ "key": "additionalField1",
+ "value": "constant value"
+ },
+ {
+ "key": "additionalField2",
+ "value": "$${ctx:key}"
+ }
+ ]
+ }
+ },
+
+ "SocketTcp": { //<2>
+ "type": "Socket",
+ "name": "GRAYLOG_TCP",
+ "protocol": "TCP",
+ "host": "graylog.domain.com",
+ "port": 12201,
+ "GelfLayout": {
+ "host": "someserver",
+ "compressionType": "OFF",
+ "includeNullDelimiter": "true"
+ }
+ },
+
+ "SocketUdp": { //<3>
+ "type": "Socket",
+ "name": "GRAYLOG_UDP",
+ "protocol": "UDP",
+ "host": "graylog.domain.com",
+ "port": 12201,
+ "GelfLayout": {
+ "host": "someserver",
+ "compressionType": "ZLIB",
+ "compressionThreshold": 1024
+ }
+ }
+
+ },
+ "Loggers": {
+ "Root": {
+ "level": "WARN",
+ "AppenderRef": [
+ {
+ "ref": "CONSOLE"
+ },
+ {
+ "ref": "GRAYLOG_TCP"
+ },
+ {
+ "ref": "GRAYLOG_UDP"
+ }
+ ]
+ }
+ }
+ }
+}
diff --git a/src/site/antora/modules/ROOT/examples/manual/gelf-layout/log4j2.properties b/src/site/antora/modules/ROOT/examples/manual/gelf-layout/log4j2.properties
new file mode 100644
index 0000000000..42ea05fd01
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/gelf-layout/log4j2.properties
@@ -0,0 +1,53 @@
+#
+# 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 = Console #<1>
+appender.0.name = CONSOLE
+appender.0.layout.type = GelfLayout
+appender.0.layout.messagePattern = %d %5p [%t] %c{1} %X{loginId, requestId} - %m%n
+appender.0.layout.includeThreadContext = true
+appender.0.layout.threadContextIncludes = true
+appender.0.layout.KeyValuePair.0.type = KeyValuePair
+appender.0.layout.KeyValuePair.0.key = additionalField1
+appender.0.layout.KeyValuePair.0.value = constant value
+appender.0.layout.KeyValuePair.1.type = KeyValuePair
+appender.0.layout.KeyValuePair.1.key = additionalField2
+appender.0.layout.KeyValuePair.1.value = $${ctx:key}
+
+appender.1.type = Socket #<2>
+appender.1.name = GRAYLOG_TCP
+appender.1.protocol = TCP
+appender.1.host = graylog.domain.com
+appender.1.port = 12201
+appender.1.layout.type = GelfLayout
+appender.1.layout.host = someserver
+appender.1.layout.compressionType = OFF
+appender.1.layout.includeNullDelimiter = true
+
+appender.2.type = Socket #<3>
+appender.2.name = GRAYLOG_UDP
+appender.2.protocol = UDP
+appender.2.host = graylog.domain.com
+appender.2.port = 12201
+appender.2.layout.type = GelfLayout
+appender.2.layout.host = someserver
+appender.2.layout.compressionType = ZLIB
+appender.2.layout.compressionThreshold = 1024
+
+rootLogger.level = WARN
+rootLogger.appenderRef.0.ref = CONSOLE
+rootLogger.appenderRef.1.ref = GRAYLOG_TCP
+rootLogger.appenderRef.2.ref = GRAYLOG_UDP
diff --git a/src/site/antora/modules/ROOT/examples/manual/gelf-layout/log4j2.xml b/src/site/antora/modules/ROOT/examples/manual/gelf-layout/log4j2.xml
new file mode 100644
index 0000000000..e0fa0cf85b
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/gelf-layout/log4j2.xml
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ 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 xmlns="https://logging.apache.org/xml/ns"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+
+ <Appenders>
+
+ <Console name="CONSOLE"><!--1-->
+ <GelfLayout messagePattern="%d %5p [%t] %c{1} %X{loginId, requestId} - %m%n"
+ includeThreadContext="true"
+ threadContextIncludes="loginId,requestId">
+ <KeyValuePair key="additionalField1" value="constant value"/>
+ <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
+ </GelfLayout>
+ </Console>
+
+ <Socket name="GRAYLOG_TCP" protocol="TCP" host="graylog.domain.com" port="12201"><!--2-->
+ <GelfLayout host="someserver" compressionType="OFF" includeNullDelimiter="true"/>
+ </Socket>
+
+ <Socket name="GRAYLOG_UDP" protocol="UDP" host="graylog.domain.com" port="12201"><!--3-->
+ <GelfLayout host="someserver" compressionType="ZLIB" compressionThreshold="1024"/>
+ </Socket>
+
+ </Appenders>
+
+ <Loggers>
+ <Root level="WARN">
+ <AppenderRef ref="CONSOLE"/>
+ <AppenderRef ref="GRAYLOG_TCP"/>
+ <AppenderRef ref="GRAYLOG_UDP"/>
+ </Root>
+ </Loggers>
+
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/gelf-layout/log4j2.yaml b/src/site/antora/modules/ROOT/examples/manual/gelf-layout/log4j2.yaml
new file mode 100644
index 0000000000..01ca630368
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/gelf-layout/log4j2.yaml
@@ -0,0 +1,61 @@
+#
+# 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:
+
+ Console:
+ name: "CONSOLE"
+ GelfLayout: #<1>
+ messagePattern: "%d %5p [%t] %c{1} %X{loginId, requestId} - %m%n"
+ includeThreadContext: "true"
+ threadContextIncludes: "loginId,requestId"
+ KeyValuePair:
+ - key: "additionalField1"
+ value: "constant value"
+ - key: "additionalField2"
+ value: "$${ctx:key}"
+
+ SocketTcp: #<2>
+ type: "Socket"
+ name: "GRAYLOG_TCP"
+ protocol: "TCP"
+ host: "graylog.domain.com"
+ port: 12201
+ GelfLayout:
+ host: "someserver"
+ compressionType: "OFF"
+ includeNullDelimiter: "true"
+
+ SocketUdp: #<3>
+ type: "Socket"
+ name: "GRAYLOG_UDP"
+ protocol: "UDP"
+ host: "graylog.domain.com"
+ port: 12201
+ GelfLayout:
+ host: "someserver"
+ compressionType: "ZLIB"
+ compressionThreshold: 1024
+
+ Loggers:
+ Root:
+ level: "WARN"
+ AppenderRef:
+ - ref: "CONSOLE"
+ - ref: "GRAYLOG_TCP"
+ - ref: "GRAYLOG_UDP"
diff --git a/src/site/antora/modules/ROOT/examples/manual/json-template-layout/eventTemplateAdditionalField/log4j2.json b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/eventTemplateAdditionalField/log4j2.json
new file mode 100644
index 0000000000..b900cdf8dc
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/eventTemplateAdditionalField/log4j2.json
@@ -0,0 +1,41 @@
+{
+ "Configuration": {
+ "Appenders": {
+ "Console": {
+ "name": "CONSOLE",
+ "JsonTemplateLayout": {
+ "eventTemplateUri": "classpath:GelfLayout.json",
+ "eventTemplateAdditionalField": [
+ {
+ "key": "aString",
+ "value": "foo" //<1>
+ },
+ {
+ "key": "marker",
+ "value": "{\"$resolver\": \"marker\", \"field\": \"name\"}",
+ "format": "JSON"
+ },
+ {
+ "key": "aNumber",
+ "value": "1",
+ "format": "JSON"
+ },
+ {
+ "key": "aList",
+ "value": "[1, 2, \"three\"]",
+ "format": "JSON"
+ }
+ ]
+ }
+ }
+ },
+ "Loggers": {
+ "Root": {
+ "level": "WARN",
+ "AppenderRef": {
+ "ref": "CONSOLE"
+ }
+ }
+ }
+ }
+}
diff --git a/src/site/antora/modules/ROOT/examples/manual/json-template-layout/eventTemplateAdditionalField/log4j2.properties b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/eventTemplateAdditionalField/log4j2.properties
new file mode 100644
index 0000000000..ec1c15aea0
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/eventTemplateAdditionalField/log4j2.properties
@@ -0,0 +1,38 @@
+#
+# 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 = Console
+appender.0.name = CONSOLE
+appender.0.layout.type = JsonTemplateLayout
+appender.0.layout.eventTemplateUri = classpath:GelfLayout.json
+appender.0.layout.eventTemplateAdditionalField[0].type = EventTemplateAdditionalField
+appender.0.layout.eventTemplateAdditionalField[0].key = aString
+appender.0.layout.eventTemplateAdditionalField[0].value = foo #<1>
+appender.0.layout.eventTemplateAdditionalField[1].type = EventTemplateAdditionalField
+appender.0.layout.eventTemplateAdditionalField[1].key = marker
+appender.0.layout.eventTemplateAdditionalField[1].value = {"$resolver": "marker", "field": "name"}
+appender.0.layout.eventTemplateAdditionalField[1].format = JSON
+appender.0.layout.eventTemplateAdditionalField[2].type = EventTemplateAdditionalField
+appender.0.layout.eventTemplateAdditionalField[2].key = aNumber
+appender.0.layout.eventTemplateAdditionalField[2].value = 1
+appender.0.layout.eventTemplateAdditionalField[2].format = JSON
+appender.0.layout.eventTemplateAdditionalField[3].type = EventTemplateAdditionalField
+appender.0.layout.eventTemplateAdditionalField[3].key = aList
+appender.0.layout.eventTemplateAdditionalField[3].value = [1, 2, "three"]
+appender.0.layout.eventTemplateAdditionalField[3].format = JSON
+
+rootLogger.level = WARN
+rootLogger.appenderRef.0.ref = CONSOLE
diff --git a/src/site/antora/modules/ROOT/examples/manual/json-template-layout/eventTemplateAdditionalField/log4j2.xml b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/eventTemplateAdditionalField/log4j2.xml
new file mode 100644
index 0000000000..c6b2f32ae8
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/eventTemplateAdditionalField/log4j2.xml
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ 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 xmlns="https://logging.apache.org/xml/ns"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+
+ <Appenders>
+ <Console name="CONSOLE">
+ <JsonTemplateLayout eventTemplateUri="classpath:GelfLayout.json">
+ <EventTemplateAdditionalField
+ key="aString"
+ value="foo"/><!--1-->
+ <EventTemplateAdditionalField
+ key="marker"
+ format="JSON"
+ value='{"$resolver": "marker", "field": "name"}'/>
+ <EventTemplateAdditionalField
+ key="aNumber"
+ format="JSON"
+ value="1"/>
+ <EventTemplateAdditionalField
+ key="aList"
+ format="JSON"
+ value='[1, 2, "three"]'/>
+ </JsonTemplateLayout>
+ </Console>
+ </Appenders>
+
+ <Loggers>
+ <Root level="WARN">
+ <AppenderRef ref="CONSOLE"/>
+ </Root>
+ </Loggers>
+
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/json-template-layout/eventTemplateAdditionalField/log4j2.yaml b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/eventTemplateAdditionalField/log4j2.yaml
new file mode 100644
index 0000000000..0349dd2575
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/eventTemplateAdditionalField/log4j2.yaml
@@ -0,0 +1,41 @@
+#
+# 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:
+ Console:
+ name: "CONSOLE"
+ JsonTemplateLayout:
+ eventTemplateUri: "classpath:GelfLayout.json"
+ eventTemplateAdditionalField:
+ - key: "aString"
+ value: "foo" #<1>
+ - key: "marker"
+ value: '{"$resolver": "marker", "field": "name"}'
+ format: "JSON"
+ - key: "aNumber"
+ value: "1"
+ format: "JSON"
+ - key: "aList"
+ value: '[1, 2, "three"]'
+ format: "JSON"
+
+ Loggers:
+ Root:
+ level: "WARN"
+ AppenderRef:
+ ref: "CONSOLE"
diff --git a/src/site/antora/modules/ROOT/examples/manual/json-template-layout/usage/log4j2.json b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/usage/log4j2.json
new file mode 100644
index 0000000000..35fbd8e51e
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/usage/log4j2.json
@@ -0,0 +1,20 @@
+{
+ "Configuration": {
+ "Appenders": {
+ "Console": {
+ "name": "CONSOLE",
+ "JsonTemplateLayout": {
+ "eventTemplateUri": "classpath:MyLayout.json"
+ }
+ }
+ },
+ "Loggers": {
+ "Root": {
+ "level": "WARN",
+ "AppenderRef": {
+ "ref": "CONSOLE"
+ }
+ }
+ }
+ }
+}
diff --git a/src/site/antora/modules/ROOT/examples/manual/json-template-layout/usage/log4j2.properties b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/usage/log4j2.properties
new file mode 100644
index 0000000000..5d0cabbc88
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/usage/log4j2.properties
@@ -0,0 +1,23 @@
+#
+# 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 = Console
+appender.0.name = CONSOLE
+appender.0.layout.type = JsonTemplateLayout
+appender.0.layout.eventTemplateUri = classpath:MyLayout.json
+
+rootLogger.level = WARN
+rootLogger.appenderRef.0.ref = CONSOLE
diff --git a/src/site/antora/modules/ROOT/examples/manual/json-template-layout/usage/log4j2.xml b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/usage/log4j2.xml
new file mode 100644
index 0000000000..89abf7bc37
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/usage/log4j2.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ 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 xmlns="https://logging.apache.org/xml/ns"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+
+ <Appenders>
+ <Console name="CONSOLE">
+ <JsonTemplateLayout eventTemplateUri="classpath:MyLayout.json"/>
+ </Console>
+ </Appenders>
+
+ <Loggers>
+ <Root level="WARN">
+ <AppenderRef ref="CONSOLE"/>
+ </Root>
+ </Loggers>
+
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/json-template-layout/usage/log4j2.yaml b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/usage/log4j2.yaml
new file mode 100644
index 0000000000..ebc22455fa
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/json-template-layout/usage/log4j2.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:
+ Console:
+ name: "CONSOLE"
+ JsonTemplateLayout:
+ eventTemplateUri: "classpath:MyLayout.json"
+
+ Loggers:
+ Root:
+ level: "WARN"
+ AppenderRef:
+ ref: "CONSOLE"
diff --git a/src/site/antora/modules/ROOT/examples/manual/pattern-layout/marker-pattern-selector/log4j2.json b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/marker-pattern-selector/log4j2.json
new file mode 100644
index 0000000000..901d8ea124
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/marker-pattern-selector/log4j2.json
@@ -0,0 +1,28 @@
+{
+ "Configuration": {
+ "Appenders": {
+ "Console": {
+ "name": "CONSOLE",
+ "PatternLayout": {
+ "MarkerPatternSelector": {
+ "defaultPattern": "[%-5level] %c{1.} %msg%n",
+ "PatternMatch": [
+ {
+ "key": "FLOW",
+ "pattern": "[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "Loggers": {
+ "Root": {
+ "level": "WARN",
+ "AppenderRef": {
+ "ref": "CONSOLE"
+ }
+ }
+ }
+ }
+}
diff --git a/src/site/antora/modules/ROOT/examples/manual/pattern-layout/marker-pattern-selector/log4j2.properties b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/marker-pattern-selector/log4j2.properties
new file mode 100644
index 0000000000..06d4d14425
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/marker-pattern-selector/log4j2.properties
@@ -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.
+#
+appender.0.type = Console
+appender.0.name = CONSOLE
+appender.0.layout.type = PatternLayout
+appender.0.layout.patternSelector.type = MarkerPatternSelector
+appender.0.layout.patternSelector.defaultPattern = %-5p [%t]: %m%n
+appender.0.layout.patternSelector.patternMatch.0.type = PatternMatch
+appender.0.layout.patternSelector.patternMatch.0.key = FLOW
+appender.0.layout.patternSelector.patternMatch.0.pattern = [%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n
+
+rootLogger.level = WARN
+rootLogger.appenderRef.0.ref = CONSOLE
diff --git a/src/site/antora/modules/ROOT/examples/manual/pattern-layout/marker-pattern-selector/log4j2.xml b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/marker-pattern-selector/log4j2.xml
new file mode 100644
index 0000000000..3b37648754
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/marker-pattern-selector/log4j2.xml
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ 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 xmlns="https://logging.apache.org/xml/ns"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+
+ <Appenders>
+ <Console name="CONSOLE">
+ <PatternLayout>
+ <MarkerPatternSelector defaultPattern="[%-5level] %c{1.} %msg%n">
+ <PatternMatch key="FLOW" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
+ </MarkerPatternSelector>
+ </PatternLayout>
+ </Console>
+ </Appenders>
+
+ <Loggers>
+ <Root level="WARN">
+ <AppenderRef ref="CONSOLE"/>
+ </Root>
+ </Loggers>
+
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/pattern-layout/marker-pattern-selector/log4j2.yaml b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/marker-pattern-selector/log4j2.yaml
new file mode 100644
index 0000000000..9574ae89f6
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/marker-pattern-selector/log4j2.yaml
@@ -0,0 +1,33 @@
+#
+# 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:
+ Console:
+ name: "CONSOLE"
+ PatternLayout:
+ MarkerPatternSelector:
+ defaultPattern: "%-5p [%t]: %m%n"
+ PatternMatch:
+ - key: "FLOW"
+ pattern: "[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"
+
+ Loggers:
+ Root:
+ level: "WARN"
+ AppenderRef:
+ ref: "CONSOLE"
diff --git a/src/site/antora/modules/ROOT/examples/manual/pattern-layout/script-pattern-selector/log4j2.json b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/script-pattern-selector/log4j2.json
new file mode 100644
index 0000000000..3bb5ddb9ef
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/script-pattern-selector/log4j2.json
@@ -0,0 +1,37 @@
+{
+ "Configuration": {
+ "Appenders": {
+ "Console": {
+ "name": "CONSOLE",
+ "PatternLayout": {
+ "ScriptPatternSelector": {
+ "defaultPattern": "[%-5level] %c{1.} %msg%n",
+ "Script": {
+ "name": "BeanShellSelector",
+ "language": "bsh",
+ "scriptText": "if (logEvent.getLoggerName().equals(\"NoLocation\")) { return \"NoLocation\"; } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf(\"FLOW\")) { return \"Flow\"; } else { return null; }"
+ },
+ "PatternMatch": [
+ {
+ "key": "NoLocation",
+ "pattern": "[%-5level] %c{1.} %msg%n"
+ },
+ {
+ "key": "Flow",
+ "pattern": "[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "Loggers": {
+ "Root": {
+ "level": "WARN",
+ "AppenderRef": {
+ "ref": "CONSOLE"
+ }
+ }
+ }
+ }
+}
diff --git a/src/site/antora/modules/ROOT/examples/manual/pattern-layout/script-pattern-selector/log4j2.properties b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/script-pattern-selector/log4j2.properties
new file mode 100644
index 0000000000..ec7b7407cc
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/script-pattern-selector/log4j2.properties
@@ -0,0 +1,41 @@
+#
+# 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 = Console
+appender.0.name = CONSOLE
+appender.0.layout.type = PatternLayout
+appender.0.layout.patternSelector.type = ScriptPatternSelector
+appender.0.layout.patternSelector.defaultPattern = [%-5level] %c{1.} %C{1.}.%M.%L %msg%n
+appender.0.layout.patternSelector.script.type = Script
+appender.0.layout.patternSelector.script.name = BeanShellSelector
+appender.0.layout.patternSelector.script.language = bsh
+appender.0.layout.patternSelector.script.scriptText =\
+if (logEvent.getLoggerName().equals("NoLocation")) {\
+ return "NoLocation";\
+} else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {\
+ return "Flow";\
+} else {\
+ return null;\
+}
+appender.0.layout.patternSelector.patternMatch.0.type = PatternMatch
+appender.0.layout.patternSelector.patternMatch.0.key = NoLocation
+appender.0.layout.patternSelector.patternMatch.0.pattern = [%-5level] %c{1.} %msg%n
+appender.0.layout.patternSelector.patternMatch.1.type = PatternMatch
+appender.0.layout.patternSelector.patternMatch.1.key = Flow
+appender.0.layout.patternSelector.patternMatch.1.pattern = [%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n
+
+rootLogger.level = WARN
+rootLogger.appenderRef.0.ref = CONSOLE
diff --git a/src/site/antora/modules/ROOT/examples/manual/pattern-layout/script-pattern-selector/log4j2.xml b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/script-pattern-selector/log4j2.xml
new file mode 100644
index 0000000000..816b1ad03a
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/script-pattern-selector/log4j2.xml
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ 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 xmlns="https://logging.apache.org/xml/ns"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+
+ <Appenders>
+ <Console name="CONSOLE">
+ <PatternLayout>
+ <ScriptPatternSelector defaultPattern="[%-5level] %c{1.} %C{1.}.%M.%L %msg%n">
+ <Script name="BeanShellSelector" language="bsh"><![CDATA[
+ if (logEvent.getLoggerName().equals("NoLocation")) {
+ return "NoLocation";
+ } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
+ return "Flow";
+ } else {
+ return null;
+ }]]>
+ </Script>
+ <PatternMatch key="NoLocation" pattern="[%-5level] %c{1.} %msg%n"/>
+ <PatternMatch key="Flow" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
+ </ScriptPatternSelector>
+ </PatternLayout>
+ </Console>
+ </Appenders>
+
+ <Loggers>
+ <Root level="WARN">
+ <AppenderRef ref="CONSOLE"/>
+ </Root>
+ </Loggers>
+
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/pattern-layout/script-pattern-selector/log4j2.yaml b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/script-pattern-selector/log4j2.yaml
new file mode 100644
index 0000000000..02ad8df0b8
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/script-pattern-selector/log4j2.yaml
@@ -0,0 +1,46 @@
+#
+# 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:
+ Console:
+ name: "CONSOLE"
+ PatternLayout:
+ ScriptPatternSelector:
+ defaultPattern: "%-5p [%t]: %m%n"
+ Script:
+ name: "BeanShellSelector"
+ language: "bsh"
+ scriptText: |
+ if (logEvent.getLoggerName().equals("NoLocation")) {
+ return "NoLocation";
+ } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
+ return "Flow";
+ } else {
+ return null;
+ }
+ PatternMatch:
+ - key: "NoLocation"
+ pattern: "[%-5level] %c{1.} %msg%n"
+ - key: "Flow"
+ pattern: "[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"
+
+ Loggers:
+ Root:
+ level: "WARN"
+ AppenderRef:
+ ref: "CONSOLE"
diff --git a/src/site/antora/modules/ROOT/examples/manual/pattern-layout/usage/log4j2.json b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/usage/log4j2.json
new file mode 100644
index 0000000000..f7f90b4299
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/usage/log4j2.json
@@ -0,0 +1,20 @@
+{
+ "Configuration": {
+ "Appenders": {
+ "Console": {
+ "name": "CONSOLE",
+ "PatternLayout": {
+ "pattern": "%-5p [%t]: %m%n"
+ }
+ }
+ },
+ "Loggers": {
+ "Root": {
+ "level": "WARN",
+ "AppenderRef": {
+ "ref": "CONSOLE"
+ }
+ }
+ }
+ }
+}
diff --git a/src/site/antora/modules/ROOT/examples/manual/pattern-layout/usage/log4j2.properties b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/usage/log4j2.properties
new file mode 100644
index 0000000000..561dce7202
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/usage/log4j2.properties
@@ -0,0 +1,23 @@
+#
+# 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 = Console
+appender.0.name = CONSOLE
+appender.0.layout.type = PatternLayout
+appender.0.layout.pattern = %-5p [%t]: %m%n
+
+rootLogger.level = WARN
+rootLogger.appenderRef.0.ref = CONSOLE
diff --git a/src/site/antora/modules/ROOT/examples/manual/pattern-layout/usage/log4j2.xml b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/usage/log4j2.xml
new file mode 100644
index 0000000000..0043667de2
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/usage/log4j2.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ 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 xmlns="https://logging.apache.org/xml/ns"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+
+ <Appenders>
+ <Console name="CONSOLE">
+ <PatternLayout pattern="%-5p [%t]: %m%n"/>
+ </Console>
+ </Appenders>
+
+ <Loggers>
+ <Root level="WARN">
+ <AppenderRef ref="CONSOLE"/>
+ </Root>
+ </Loggers>
+
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/pattern-layout/usage/log4j2.yaml b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/usage/log4j2.yaml
new file mode 100644
index 0000000000..3d226e0ba7
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/pattern-layout/usage/log4j2.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:
+ Console:
+ name: "CONSOLE"
+ PatternLayout:
+ pattern: "%-5p [%t]: %m%n"
+
+ Loggers:
+ Root:
+ level: "WARN"
+ AppenderRef:
+ ref: "CONSOLE"
diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc
index 1c0af5b572..a3221fef6a 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/layouts.adoc[]
*** xref:manual/json-template-layout.adoc[]
+*** xref:manual/pattern-layout.adoc[]
** xref:manual/lookups.adoc[]
** xref:manual/filters.adoc[]
** xref:manual/scripts.adoc[]
diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc
index 1811478a78..aad5a661a3 100644
--- a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc
@@ -237,7 +237,7 @@ maximum capacity.
The CassandraAppender writes its output to an https://cassandra.apache.org/[Apache Cassandra]
database.
A keyspace and table must be configured ahead of time, and the columns of that table are mapped in a configuration file.
-Each column can specify either a 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
+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).
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
index 3651893ca8..ab744fc720 100644
--- a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
@@ -257,29 +257,19 @@ See also <<format-specific-notes>> for exceptions to the rules above.
Log4j Core's logging pipeline is quite complex (see xref:manual/architecture.adoc[Architecture]), but most users only require these elements:
Loggers::
-+
-Loggers are the entry point of the logging pipeline, which is directly used in the code.
+xref:manual/api.adoc#loggers[Loggers] are the entry point of the logging pipeline, which is directly used in the code.
Their configuration must specify which level of messages they log and to which appenders they send the messages.
-+
-See <<configuring-loggers>> for details.
+We will cover them while <<configuring-loggers, configuring loggers>>.
[id=configuring-appenders]
[[Appenders]] Appenders::
-+
-Appenders are the exit point of the logging pipeline.
+xref:manual/appenders.adoc[] are the exit point of the logging pipeline.
They decide which resource (console, file, database, or similar) the log event is sent to.
In the examples of this chapter, we will only use the xref:manual/appenders.adoc#consoleappender[console appender] and the xref:manual/appenders.adoc#fileappender[file appender].
-+
-See xref:manual/appenders.adoc[Appender configuration] for details.
Layouts::
-+
-Layouts tell appenders how to format the log event: text, JSON, XML, or similar.
-In the examples of this chapter, we will only use the xref:manual/layouts.adoc#pattern-layout[textual pattern layout]
-and
-xref:manual/json-template-layout.adoc[JSON template layout].
-+
-See xref:manual/layouts.adoc[Layout configuration] for details.
+xref:manual/layouts.adoc[] tell appenders how to format the log event: text, JSON, XML, or similar.
+In the examples of this chapter, we will only use xref:manual/pattern-layout.adoc[] and xref:manual/json-template-layout.adoc[].
A moderately complex configuration might look like this:
diff --git a/src/site/antora/modules/ROOT/pages/manual/extending.adoc b/src/site/antora/modules/ROOT/pages/manual/extending.adoc
index 554ec16948..b8d6395681 100644
--- a/src/site/antora/modules/ROOT/pages/manual/extending.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/extending.adoc
@@ -378,91 +378,6 @@ public final class StubAppender extends AbstractOutputStreamAppender<StubManager
}
----
-[#Layouts]
-== Layouts
-
-Layouts perform the formatting of events into the printable text that is
-written by Appenders to some destination. All Layouts must implement the
-`Layout` interface. Layouts that format the event into a `String` should
-extend `AbstractStringLayout`, which will take care of converting the
-`String` into the required byte array.
-
-Every Layout must declare itself as a plugin using the `@Plugin`
-annotation and a `@Configurable` annotation with an `elementType` of "layout". `printObject` should be set to "true" if the plugin's `toString`
-method will provide a representation of the object and its parameters.
-The name of the plugin must match the value users should use to specify
-it as an element in their Appender configuration. The plugin also must
-provide a static method annotated as a `@PluginFactory` and with each of
-the methods parameters annotated with `@PluginAttribute` or `@PluginElement` as
-appropriate. The plugin can alternatively use the plugin builder notation.
-
-[source,java]
-----
-@Plugin(name = "SampleLayout", category = "Core", elementType = "layout", printObject = true)
-public class SampleLayout extends AbstractStringLayout {
-
- protected SampleLayout(boolean locationInfo, boolean properties, boolean complete,
- Charset charset) {
- super(charset);
- // handle the boolean parameters
- }
-
- @PluginFactory
- public static SampleLayout createLayout(@PluginAttribute boolean locationInfo,
- @PluginAttribute boolean properties,
- @PluginAttribute boolean complete,
- @PluginAttribute(defaultStringValue = "UTF-8") Charset charset) {
- return new SampleLayout(locationInfo, properties, complete, charset);
- }
-}
-----
-
-[#PatternConverters]
-== PatternConverters
-
-PatternConverters are used by the PatternLayout to format the log event
-into a printable `String`. Each Converter is responsible for a single kind
-of manipulation, however Converters are free to format the event in
-complex ways. For example, there are several converters that manipulate
-Throwables and format them in various ways.
-
-A PatternConverter must first declare itself as a Plugin using the
-standard `@Plugin` annotation and the `@Namespace` annotation with the value "Converter". Furthermore, the Converter must also specify the
-`@ConverterKeys` annotation to define the tokens that can be specified in
-the pattern (preceded by a '%' character) to identify the Converter.
-
-Unlike most other Plugins, Converters do not use a `@PluginFactory`.
-Instead, each Converter is required to provide a static `newInstance`
-method that accepts an array of `String` as the only parameter. The
-`String[]` is the values that are specified within the curly braces
-that can follow the converter key.
-
-The following shows the skeleton of a Converter plugin.
-
-[source,java]
-----
-@Plugin("query")
-@ConverterKeys({"q", "query"})
-public final class QueryConverter extends LogEventPatternConverter {
-
- public QueryConverter(String[] options) {
- }
-
- public static QueryConverter newInstance(final String[] options) {
- return new QueryConverter(options);
- }
-
- @Override
- public void format(LogEvent event, StringBuilder toAppendTo) {
- // get the data from 'event', to the work and append the result to 'toAppendTo'.
- }
-}
-----
-
-A pattern to use this converter could be specified as `... %q ...` or `... %q\{argument} ...`.
-The "argument" will be passed as first (and only) value to the `options` parameter of the
-`newInstance(...)` method.
-
[#Plugin_Builders]
== Plugin Builders
diff --git a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
index d06ea276c4..e776c37267 100644
--- a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
@@ -80,7 +80,7 @@ To understand which configuration knobs exhibit what kind of allocation behaviou
// Maintain the alphabetical ordering while making changes, please!
* xref:manual/layouts.adoc#GELFLayout[`GelfLayout`]
* xref:manual/json-template-layout.adoc#faq-garbage-free[`JsonTemplateLayout`]
-* xref:manual/layouts.adoc#PatternLayout-gcfree[`PatternLayout`]
+* xref:manual/pattern-layout.adoc#garbage-free[`PatternLayout`]
.Implementation notes
[%collapsible]
diff --git a/src/site/antora/modules/ROOT/pages/manual/getting-started.adoc b/src/site/antora/modules/ROOT/pages/manual/getting-started.adoc
index 7735ffce89..90af742550 100644
--- a/src/site/antora/modules/ROOT/pages/manual/getting-started.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/getting-started.adoc
@@ -437,7 +437,7 @@ Contrast to xref:#config-app[an application's more conservative Log4j setup], fo
. the logs are pretty-printed to the console, and
. logging verbosity is increased.
-While it is not recommended to use xref:manual/layouts.adoc#pattern-layout[Pattern Layout] in production for security reasons, it is a good choice for tests to encode log events.
+While it is not recommended to use xref:manual/pattern-layout.adoc[] in production for security reasons, it is a good choice for tests to encode log events.
We will use it to pretty-print the log event to the console with extra fields: timestamp, thread name, log level, class name, etc.
The rest of the configuration should look familiar from earlier sections.
@@ -468,7 +468,7 @@ Save the following XML-formatted Log4j configuration file to `src/**test**/resou
</Configuration>
----
-<1> xref:manual/layouts.adoc#pattern-layout[Pattern Layout] is used for encoding the log event in a human-readable way.
+<1> xref:manual/pattern-layout.adoc[] is used for encoding the log event in a human-readable way.
<2> Increased logging verbosity for the `com.mycompany` package.
[#next]
diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
index 97881b7e8a..42edc9f272 100644
--- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
@@ -542,8 +542,7 @@ rootLogger.appenderRef.0.ref = CONSOLE
----
====
-<1> While xref:manual/layouts.adoc#pattern-layout[Pattern Layout] is a good first choice and preferable for tests, we recommend
-using a structured format such as xref:manual/json-template-layout.adoc[] for production deployments.
+<1> While xref:manual/pattern-layout.adoc[] is a good first choice and preferable for tests, we recommend using a structured format such as xref:manual/json-template-layout.adoc[] for production deployments.
To use these formats, the following additional dependencies are required:
diff --git a/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc b/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
index c600488a67..8408762e53 100644
--- a/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
@@ -16,422 +16,487 @@
////
= JSON Template Layout
-`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON
-generating layout. It encodes ``LogEvent``s according to the structure described
-by the JSON template provided. In a nutshell, it shines with its
+`JsonTemplateLayout` is a customizable, xref:#performance[efficient], and xref:#faq-garbage-free[garbage-free] JSON generating layout.
+It encodes ``LogEvent``s according to the structure described by the JSON template provided.
+In a nutshell, it shines with its
-* Customizable JSON structure (see `eventTemplate[Uri]` and
- `stackTraceElementTemplate[Uri]` xref:#layout-config[layout configuration] parameters)
+* Customizable JSON structure (see `eventTemplate[Uri]` and `stackTraceElementTemplate[Uri]` xref:#layout-config[layout configuration] parameters)
-* Customizable timestamp formatting (see xref:#event-template-resolver-timestamp[]
- event template resolver)
+* Customizable timestamp formatting (see xref:#event-template-resolver-timestamp[] event template resolver)
-* Feature rich exception formatting (see xref:#event-template-resolver-exception[]
- and xref:#event-template-resolver-exceptionRootCause[] event template resolvers)
+* Feature rich exception formatting (see xref:#event-template-resolver-exception[] and xref:#event-template-resolver-exceptionRootCause[] event template resolvers)
* xref:manual/extending.adoc[Extensible plugin support]
* Customizable object xref:#recycling-strategy[recycling strategy]
+[TIP]
+====
+JSON Template Layout is intended for production deployments where the generated logs are expected to be delivered to an external log ingestion system such as Elasticsearch or Google Cloud Logging.
+While running tests or developing locally, you can use xref:manual/pattern-layout.adoc[] for human-readable log output.
+====
+
[#usage]
== Usage
-Adding `log4j-layout-template-json` artifact to your list of dependencies is
-enough to enable access to `JsonTemplateLayout` in your Log4j configuration:
+Adding `log4j-layout-template-json` artifact to your list of dependencies is enough to enable access to JSON Template Layout in your Log4j configuration:
+[tabs]
+====
+Maven::
++
[source,xml,subs="+attributes"]
----
-<dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-layout-template-json</artifactId>
- <version>{log4j-layout-template-json-version}</version>
-</dependency>
+<project>
+
+ <!-- Assuming `log4j-bom` is imported --><!--1-->
+
+ <dependency>
+
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-layout-template-json</artifactId>
+ <scope>runtime</scope><!--2-->
+ </dependency>
+
+ </dependency>
+
+</project>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
+----
+dependencies {
+
+ // Assuming `log4j-bom` is imported <1>
+
+ runtimeOnly // <2>
+ 'org.apache.logging.log4j:log4j-slf4j2-impl'
+
+}
+----
+====
+<1> Assuming you xref:manual/installation.adoc#bom[imported `org.apache.logging.log4j:log4j-bom`]
+<2> For applications, logging implementation dependencies are required at _runtime_.
+If you want to use JSON Template Layout for tests, you need to switch the scope to _test_.
+See xref:manual/installation.adoc[] for details.
+
+JSON Template Layout is primarily configured through an *event template* describing the structure log events should be JSON-encoded in.
+Event templates themselves are also JSON documents, where objects containing `$resolver` members, such as,
+
+[source,json]
----
+{
+ "$resolver": "message", // <1>
+ "stringified": true // <2>
+}
+----
+<1> Indicating that this object should be replaced with the output from the xref:#event-template-resolver-message[`message` *event template resolver*]
+<2> Passing a configuration to the `message` event template resolver
+
+are interpreted by the JSON Template Layout compiler, and replaced with the referenced event or stack trace *template resolver* rendering that particular item.
-For instance, given the following JSON template modelling
-https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the Elastic Common Schema (ECS) specification]
-(accessible via `classpath:EcsLayout.json`)
+For instance, given the following event template stored in `MyLayout.json` in your classpath:
[source,json]
----
{
- "@timestamp": {
+ "instant": { // <1>
"$resolver": "timestamp",
"pattern": {
"format": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
"timeZone": "UTC"
}
},
- "ecs.version": "1.2.0",
- "log.level": {
- "$resolver": "level",
- "field": "name"
- },
- "message": {
+ "someConstant": 1, // <2>
+ "message": { // <3>
"$resolver": "message",
"stringified": true
- },
- "process.thread.name": {
- "$resolver": "thread",
- "field": "name"
- },
- "log.logger": {
- "$resolver": "logger",
- "field": "name"
- },
- "labels": {
- "$resolver": "mdc",
- "flatten": true,
- "stringified": true
- },
- "tags": {
- "$resolver": "ndc"
- },
- "error.type": {
- "$resolver": "exception",
- "field": "className"
- },
- "error.message": {
- "$resolver": "exception",
- "field": "message"
- },
- "error.stack_trace": {
- "$resolver": "exception",
- "field": "stackTrace",
- "stackTrace": {
- "stringified": true
- }
}
}
----
+<1> Using xref:#event-template-resolver-timestamp[the `timestamp` event template resolver] to populate the `instant` field
+<2> Passing a constant that will be rendered as is
+<3> Using xref:#event-template-resolver-message[the `message` event template resolver] to populate the `message` field
-in combination with the below `log4j2.xml` configuration:
+in combination with the below layout configuration:
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.xml[`log4j2.xml`]
[source,xml]
----
-<JsonTemplateLayout eventTemplateUri="classpath:EcsLayout.json"/>
+include::example$manual/json-template-layout/usage/log4j2.xml[lines=26..26,indent=0]
----
-or with the below `log4j2.properties` configuration:
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/json-template-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/json-template-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
-[source,properties]
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
----
-appender.console.layout.type = JsonTemplateLayout
-appender.console.layout.eventTemplateUri = classpath:EcsLayout.json
+include::example$manual/json-template-layout/usage/log4j2.properties[lines=19..20,indent=0]
----
+====
-`JsonTemplateLayout` generates JSON as follows:
+JSON Template Layout generates JSON as follows:
[source,json]
----
-{
- "@timestamp": "2017-05-25T19:56:23.370Z",
- "ecs.version": "1.2.0",
- "log.level": "ERROR",
- "message": "Hello, error!",
- "process.thread.name": "main",
- "log.logger": "org.apache.logging.log4j.JsonTemplateLayoutDemo",
- "error.type": "java.lang.RuntimeException",
- "error.message": "test",
- "error.stack_trace": "java.lang.RuntimeException: test\n\tat org.apache.logging.log4j.JsonTemplateLayoutDemo.main(JsonTemplateLayoutDemo.java:11)\n"
-}
+{"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!*
+The event template defaults to `EcsLayout.json`, bundled in the classpath, modelling https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the Elastic Common Schema (ECS) specification].
+JSON Template Layout bundles several more xref:#event-templates[predefined event templates] modeling popular JSON-based log formats.
+
+[#config]
+== Configuration
+
+This section explains how to configure JSON Template Layout plugin element in a Log4j configuration file.
+
+[TIP]
+====
+Are you trying to implement your own event (or stack trace) template and looking for help on available resolvers?
+Please refer to xref:#template-config[] instead.
+====
+
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-JsonTemplateLayout[📖 Plugin reference for `JsonTemplateLayout`]
-[#layout-config]
-== Layout Configuration
+[#plugin-attrs]
+=== Plugin attributes
-`JsonTemplateLayout` is configured with the following parameters:
+JSON Template Layout plugin configuration accepts the following attributes:
-.`JsonTemplateLayout` parameters
-[cols="1m,1m,4"]
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
|===
-| Parameter Name
-| Type
-| Description
-
-| charset
-| Charset
-| `Charset` used for `String` encoding
-
-| [[locationInfoEnabled]]locationInfoEnabled
-| boolean
-| toggles access to the `LogEvent` source; file name, line number, etc.
- (defaults to `false` set by `log4j.layout.jsonTemplate.locationInfoEnabled`
- property)
-
-| stackTraceEnabled
-| boolean
-| toggles access to the stack traces (defaults to `true` set by
- `log4j.layout.jsonTemplate.stackTraceEnabled` property)
-
-| eventTemplate
-| String
-| inline JSON template for rendering ``LogEvent``s (has priority over
- `eventTemplateUri`, defaults to `null` set by
- `log4j.layout.jsonTemplate.eventTemplate` property)
-
-| eventTemplateUri
-| String
-| URI pointing to the JSON template for rendering ``LogEvent``s (defaults to
- `classpath:EcsLayout.json` set by `log4j.layout.jsonTemplate.eventTemplateUri`
- property)
-
-| eventTemplateRootObjectKey
-| String
-| if present, the event template is put into a JSON object composed of a single
- member with the provided key (defaults to `null` set by
- `log4j.layout.jsonTemplate.eventTemplateRootObjectKey`
- property)
-
-| eventTemplateAdditionalField
-| EventTemplateAdditionalField[]
-| additional key-value pairs appended to the root of the event template
-
-| stackTraceElementTemplate
-| String
-| inline JSON template for rendering ``StackTraceElement``s (has priority over
- `stackTraceElementTemplateUri`, defaults to `null` set by
- `log4j.layout.jsonTemplate.stackTraceElementTemplate` property)
-
-| stackTraceElementTemplateUri
-| String
-| URI pointing to the JSON template for rendering ``StackTraceElement``s
- (defaults to `classpath:StackTraceElementLayout.json` set by
- `log4j.layout.jsonTemplate.stackTraceElementTemplateUri` property)
-
-| eventDelimiter
-| String
-| delimiter used for separating rendered ``LogEvent``s (defaults to
- `System.lineSeparator()` set by `log4j.layout.jsonTemplate.eventDelimiter`
- property)
-
-| nullEventDelimiterEnabled
-| boolean
-| append `\0` (`null`) character to the end of every `eventDelimiter`
- separating rendered ``LogEvent``s (defaults to `false` set by
- `log4j.layout.jsonTemplate.nullEventDelimiterEnabled` property)
-
-| [[maxStringLength]] maxStringLength
-| int
-| truncate string values longer than the specified limit (defaults to 16384 set
- by `log4j.layout.jsonTemplate.maxStringLength` property)
-
-| truncatedStringSuffix
-| String
-| suffix to append to strings truncated due to exceeding `maxStringLength`
- (defaults to `…` set by `log4j.layout.jsonTemplate.truncatedStringSuffix`
- property)
-
-| recyclerFactory
-| RecyclerFactory
-| recycling strategy that can either be `dummy`, `threadLocal`, or `queue`
- (set by `log4j.layout.jsonTemplate.recyclerFactory` property)
+|Type |`Charset`
+|Default value |`UTF-8`
+|Configuration property |`log4j.layout.jsonTemplate.charset`
|===
-[#additional-event-template-fields]
-=== Additional event template fields
+`Charset` used for encoding the produced JSON into bytes
-Additional event template fields are a convenient short-cut to add custom fields
-to a template or override the existing ones. Following configuration overrides
-the `host` field of the `GelfLayout.json` template and adds two new custom
-fields:
+[WARNING]
+====
+While https://datatracker.ietf.org/doc/html/rfc4627#section-3[RFC 4627, the JSON specification, supports multiple Unicode encodings], we strongly advise you to stick to the layout default, and use UTF-8 for https://stackoverflow.com/a/594881/1278899[several practical reasons].
+====
-.XML configuration with additional fields
-[source,xml]
-----
-<JsonTemplateLayout eventTemplateUri="classpath:GelfLayout.json">
- <EventTemplateAdditionalField key="host" value="www.apache.org"/>
- <EventTemplateAdditionalField key="_serviceName" value="auth-service"/>
- <EventTemplateAdditionalField key="_containerId" value="6ede3f0ca7d9"/>
-</JsonTemplateLayout>
-----
+[#plugin-attr-locationInfoEnabled]
+==== [[locationInfoEnabled]]`locationInfoEnabled`
-The default `format` for the added new fields are `String`.
-One can also provide JSON-formatted additional fields:
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|Configuration property |`log4j.layout.jsonTemplate.locationInfoEnabled`
+|===
-.XML-formatted configuration with JSON-formatted additional fields
-[source,xml]
-----
-<JsonTemplateLayout eventTemplateUri="classpath:GelfLayout.json">
- <EventTemplateAdditionalField
- key="marker"
- format="JSON"
- value='{"$resolver": "marker", "field": "name"}'/>
- <EventTemplateAdditionalField
- key="aNumber"
- format="JSON"
- value="1"/>
- <EventTemplateAdditionalField
- key="aList"
- format="JSON"
- value='[1, 2, "three"]'/>
-</JsonTemplateLayout>
-----
-
-Additional event template fields can very well be introduced using properties-,
-YAML-, and JSON-formatted configurations:
-
-.Properties-formatted configuration with JSON-formatted additional fields
-[source,properties]
-----
-appender.console.layout.type = JsonTemplateLayout
-appender.console.layout.eventTemplateUri = classpath:GelfLayout.json
-appender.console.layout.eventTemplateAdditionalField[0].type = EventTemplateAdditionalField
-appender.console.layout.eventTemplateAdditionalField[0].key = marker
-appender.console.layout.eventTemplateAdditionalField[0].value = {"$resolver": "marker", "field": "name"}
-appender.console.layout.eventTemplateAdditionalField[0].format = JSON
-appender.console.layout.eventTemplateAdditionalField[1].type = EventTemplateAdditionalField
-appender.console.layout.eventTemplateAdditionalField[1].key = aNumber
-appender.console.layout.eventTemplateAdditionalField[1].value = 1
-appender.console.layout.eventTemplateAdditionalField[1].format = JSON
-appender.console.layout.eventTemplateAdditionalField[2].type = EventTemplateAdditionalField
-appender.console.layout.eventTemplateAdditionalField[2].key = aList
-appender.console.layout.eventTemplateAdditionalField[2].value = [1, 2, "three"]
-appender.console.layout.eventTemplateAdditionalField[2].format = JSON
-----
-
-.YAML-formatted configuration with JSON-formatted additional fields
-[source,yaml]
-----
-JsonTemplateLayout:
- eventTemplateAdditionalField:
- - key: "marker"
- value: '{"$resolver": "marker", "field": "name"}'
- format: "JSON"
- - key: "aNumber"
- value: "1"
- format: "JSON"
- - key: "aList"
- value: '[1, 2, "three"]'
- format: "JSON"
-----
-
-.JSON-formatted configuration with JSON-formatted additional fields
+Toggles access to the `LogEvent` source; file name, line number, etc.
+See also xref:manual/layouts.adoc#LocationInformation[location information].
+
+[#plugin-attr-stackTraceEnabled]
+==== `stackTraceEnabled`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|Configuration property |`log4j.layout.jsonTemplate.stackTraceEnabled`
+|===
+
+Toggles access to the stack traces
+
+[#plugin-attr-eventTemplate]
+==== `eventTemplate`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`null`
+|Configuration property |`log4j.layout.jsonTemplate.eventTemplate`
+|===
+
+Inline xref:#event-templates[event template] JSON for rendering ``LogEvent``s.
+If present, this configuration overrides xref:#plugin-attr-eventTemplateUri[].
+
+[#plugin-attr-eventTemplateUri]
+==== `eventTemplateUri`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`classpath:EcsLayout.json`
+|Configuration property |`log4j.layout.jsonTemplate.eventTemplateUri`
+|===
+
+URI pointing to the xref:#event-templates[event template] JSON for rendering ``LogEvent``s.
+This configuration is overriden by xref:#plugin-attr-eventTemplate[], if present.
+
+[#plugin-attr-eventTemplateRootObjectKey]
+==== `eventTemplateRootObjectKey`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`null`
+|Configuration property |`log4j.layout.jsonTemplate.eventTemplateRootObjectKey`
+|===
+
+If present, the event template is put into a JSON object composed of a single member with the provided key.
+
+[#plugin-attr-stackTraceElementTemplate]
+==== `stackTraceElementTemplate`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`null`
+|Configuration property |`log4j.layout.jsonTemplate.stackTraceElementTemplate`
+|===
+
+Inline xref:#stack-trace-element-templates[stack trace element template] JSON for rendering ``StackTraceElement``s
+If present, this configuration overrides xref:#plugin-attr-stackTraceElementTemplateUri[].
+
+[#plugin-attr-stackTraceElementTemplateUri]
+==== `stackTraceElementTemplateUri`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`classpath:StackTraceElementLayout.json`
+|Configuration property |`log4j.layout.jsonTemplate.stackTraceElementTemplateUri`
+|===
+
+URI pointing to the xref:#stack-trace-element-templates[stack trace element template] JSON for rendering ``StackTraceElement``s.
+This configuration is overriden by xref:#plugin-attr-stackTraceElementTemplate[], if present.
+
+[#plugin-attr-eventDelimiter]
+==== `eventDelimiter`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`System.lineSeparator()`
+|Configuration property |`log4j.layout.jsonTemplate.eventDelimiter`
+|===
+
+Delimiter used for separating rendered ``LogEvent``s.
+if xref:#plugin-attr-nullEventDelimiterEnabled[] is `true`, this value will be suffixed with `\0` (null) character.
+
+[#plugin-attr-nullEventDelimiterEnabled]
+==== `nullEventDelimiterEnabled`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`false`
+|Configuration property |`log4j.layout.jsonTemplate.nullEventDelimiterEnabled`
+|===
+
+If `true`, xref:#plugin-attr-eventDelimiter[] will be suffixed with `\0` (null) character.
+
+[#plugin-attr-maxStringLength]
+==== `maxStringLength`
+
+[cols="2h,6"]
+|===
+|Type |`int`
+|Default value |`16384` (16 KiB)
+|Configuration property |`log4j.layout.jsonTemplate.maxStringLength`
+|===
+
+Causes _truncation_ of string values longer than the specified limit.
+When a string value is truncated, its length will be shortened to the `maxStringLength` provided and xref:#plugin-attr-truncatedStringSuffix[] will be appended to indicate the truncation.
+
+[WARNING]
+====
+Note that this doesn't cap the maximum length of the JSON document produced!
+Consider a JSON document rendered using a `LogEvent` containing 20,000 thread context map (aka. MDC) entries such that each key/value is less than 16,384 characters.
+This document will certainly exceed 16,384 characters, yet it will not be subject to any truncation, since every string value in the JSON document is less than 16,384 characters.
+That is,
+
+.An example JSON document exceeding 16,384 characters in length, yet subject to no truncation
[source,json]
----
{
- "JsonTemplateLayout": {
- "eventTemplateAdditionalField": [
- {
- "key": "marker",
- "value": "{\"$resolver\": \"marker\", \"field\": \"name\"}",
- "format": "JSON"
- },
- {
- "key": "aNumber",
- "value": "1",
- "format": "JSON"
- },
- {
- "key": "aList",
- "value": "[1, 2, \"three\"]",
- "format": "JSON"
- }
- ]
+ "mdc": {
+ "key00001": "value00001",
+ "key00002": "value00002",
+ "key00003": "value00003",
+ // ...
+ "key16384": "value16384",
}
}
----
+====
-[#recycling-strategy]
-=== Recycling strategy
-
-`RecyclerFactory` plays a crucial role for determining the memory footprint of
-the layout. Template resolvers employ it to create recyclers for objects that
-they can reuse. The behavior of each `RecyclerFactory` and when one should
-prefer one over another is explained below:
-
-* `dummy` performs no recycling, hence each recycling attempt will result in a
-new instance. This will obviously create a load on the garbage-collector. It
-is a good choice for applications with low and medium log rate.
-
-* `threadLocal` performs the best, since every instance is stored in
-``ThreadLocal``s and accessed without any synchronization cost. Though this
-might not be a desirable option for applications running with hundreds of
-threads or more, e.g., a web servlet.
-
-* `queue` is the best of both worlds. It allows recycling of objects up to a
-certain number (`capacity`). When this limit is exceeded due to excessive
-concurrent load (e.g., `capacity` is 50 but there are 51 threads concurrently
-trying to log), it starts allocating. `queue` is a good strategy where
-`threadLocal` is not desirable.
+[#plugin-attr-truncatedStringSuffix]
+==== `truncatedStringSuffix`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`…`
+|Configuration property |`log4j.layout.jsonTemplate.truncatedStringSuffix`
+|===
+
+Suffix to append to strings truncated due to exceeding xref:#plugin-attr-maxStringLength[]
+
+[#plugin-attr-recyclerFactory]
+==== `recyclerFactory`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |Refer to xref:#recycling-strategy[]
+|Configuration property |`log4j.layout.jsonTemplate.recyclerFactory`
+|===
+
+Name of the xref:#recycling-strategy[] employed
+
+[#plugin-elements]
+=== Plugin elements
+
+JSON Template Layout plugin configuration accepts the following elements:
+
+[#plugin-element-EventTemplateAdditionalField]
+==== [[additional-event-template-fields]] `EventTemplateAdditionalField`
+
+Additional event template fields are convenient shortcuts to add custom fields to a template or override existing ones.
+You can specify an additional event template field using an `EventTemplateAdditionalField` element composed of following attributes:
+
+`key`:: Entry key
+`value`:: Entry value
+`format`::
+Format of the value.
+Accepted values are:
+`STRING` (default)::: Indicates that the entry value will be string-encoded
+`JSON`::: Indicates the the entry value is already formatted in JSON and will be appended to the event template verbatim
+
+Below we share an example configuration overriding the `GelfLayout.json` event template with certain custom fields:
+
+[tabs]
+====
+XML::
+
-`queue` also accepts optional `supplier` (of type `java.util.Queue`, defaults to
- `org.jctools.queues.MpmcArrayQueue.new` if JCTools is in the classpath;
-otherwise `java.util.concurrent.ArrayBlockingQueue.new`) and `capacity` (of
-type `int`, defaults to `max(8,2*cpuCount+1)`) parameters:
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/eventTemplateAdditionalField/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/json-template-layout/eventTemplateAdditionalField/log4j2.xml[lines=26..42,indent=0]
+----
+
+JSON::
+
-.Example configurations of `queue` recycling strategy
-[source]
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/eventTemplateAdditionalField/log4j2.json[`log4j2.json`]
+[source,json]
----
-queue:supplier=org.jctools.queues.MpmcArrayQueue.new
-queue:capacity=10
-queue:supplier=java.util.concurrent.ArrayBlockingQueue.new,capacity=50
+include::example$manual/json-template-layout/eventTemplateAdditionalField/log4j2.json[lines=6..29,indent=0]
----
-The default `RecyclerFactory` is `threadLocal`, if
-`log4j2.enable.threadlocals=true`; otherwise, `queue`.
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/eventTemplateAdditionalField/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/json-template-layout/eventTemplateAdditionalField/log4j2.yaml[lines=22..35,indent=0]
+----
-See <<extending-recycler>> for details on how to introduce custom
-`RecyclerFactory` implementations.
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/eventTemplateAdditionalField/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/json-template-layout/eventTemplateAdditionalField/log4j2.properties[lines=19..35,indent=0]
+----
+====
+<1> Since the `format` attribute is not explicitly set, the default (i.e., `STRING`) will be used
[#template-config]
-== Template Configuration
+== Template configuration
+
+Templates are JSON documents, where objects containing `$resolver` members, such as,
+
+[source,json]
+----
+{
+ "$resolver": "message", // <1>
+ "stringified": true // <2>
+}
+----
+<1> Indicating that this object should be replaced with the output from the xref:#event-template-resolver-message[`message` *event template resolver*]
+<2> Passing a configuration to the `message` event template resolver
-Templates are configured by means of the following `JsonTemplateLayout`
-parameters:
+are interpreted by the JSON Template Layout compiler, and replaced with the referenced event or stack trace *template resolver* rendering that particular item.
-- `eventTemplate[Uri]` (for serializing ``LogEvent``s)
-- `stackTraceElementTemplate[Uri]` (for serializing ``StackStraceElement``s)
-- `eventTemplateAdditionalField` (for extending the used event template)
+Templates are configured by means of the following JSON Template Layout plugin attributes:
+
+- xref:#plugin-attr-eventTemplate[] and xref:#plugin-attr-eventTemplateUri[] (for encoding ``LogEvent``s)
+- xref:#plugin-attr-stackTraceElementTemplate[] and xref:#plugin-attr-stackTraceElementTemplateUri[] (for encoding ``StackStraceElement``s)
+- xref:#plugin-element-EventTemplateAdditionalField[] (for extending the event template)
[#event-templates]
-=== Event Templates
-
-`eventTemplate[Uri]` describes the JSON structure `JsonTemplateLayout` uses to
-serialize ``LogEvent``s. The default configuration (accessible by
-`log4j.layout.jsonTemplate.eventTemplate[Uri]` property) is set to
-`classpath:EcsLayout.json` provided by the `log4j-layout-template-json`
-artifact, which contains the following predefined event templates:
-
-- https://github.com/apache/logging-log4j2/tree/main/log4j-layout-template-json/src/main/resources/EcsLayout.json[`EcsLayout.json`]
- described by https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the Elastic Common Schema (ECS) specification]
-
-- https://github.com/apache/logging-log4j2/tree/main/log4j-layout-template-json/src/main/resources/LogstashJsonEventLayoutV1.json[`LogstashJsonEventLayoutV1.json`]
- described in https://github.com/logstash/log4j-jsonevent-layout[Logstash
- `json_event` pattern for log4j]
-
-- https://github.com/apache/logging-log4j2/tree/main/log4j-layout-template-json/src/main/resources/GelfLayout.json[`GelfLayout.json`]
- described by https://docs.graylog.org/en/3.1/pages/gelf.html#gelf-payload-specification[the
- Graylog Extended Log Format (GELF) payload specification] with additional
- `_thread` and `_logger` fields. (Here it is advised to override the obligatory
- `host` field with a user provided constant via
- xref:#additional-event-template-fields[additional event template fields]
- to avoid `hostName` property lookup at runtime, which incurs an extra cost.)
-
-- https://github.com/apache/logging-log4j2/tree/main/log4j-layout-template-json/src/main/resources/GcpLayout.json[`GcpLayout.json`]
- described by https://cloud.google.com/logging/docs/structured-logging[Google
- Cloud Platform structured logging] with additional
- `_thread`, `_logger` and `_exception` fields. The exception trace, if any,
- is written to the `_exception` field as well as the `message` field –
- the former is useful for explicitly searching/analyzing structured exception
- information, while the latter is Google's expected place for the exception,
- and integrates with https://cloud.google.com/error-reporting[Google Error Reporting].
-
-- https://github.com/apache/logging-log4j2/tree/main/log4j-layout-template-json/src/main/resources/JsonLayout.json[`JsonLayout.json`]
- providing the exact JSON structure generated by xref:manual/layouts.adoc#JSONLayout[`JsonLayout`]
- with the exception of `thrown` field. (`JsonLayout` serializes the `Throwable`
- as is via Jackson `ObjectMapper`, whereas `JsonLayout.json` template of
- `JsonTemplateLayout` employs the `StackTraceElementLayout.json` template
- for stack traces to generate a document-store-friendly flat structure.)
+=== Event templates
+
+xref:#plugin-attr-eventTemplate[] and xref:#plugin-attr-eventTemplateUri[] describe the JSON structure JSON Template Layout uses to encode ``LogEvent``s.
+JSON Template Layout contains the following predefined event templates:
+
+{project-github-url}/tree/2.x/log4j-layout-template-json/src/main/resources/EcsLayout.json[`EcsLayout.json`]::
+The **default event template** modelling the https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the Elastic Common Schema (ECS) specification]
+
+{project-github-url}/tree/2.x/log4j-layout-template-json/src/main/resources/LogstashJsonEventLayoutV1.json[`LogstashJsonEventLayoutV1.json`]::
+Models https://github.com/logstash/log4j-jsonevent-layout[Logstash `json_event` pattern for Log4j]
+
+{project-github-url}/tree/2.x/log4j-layout-template-json/src/main/resources/GelfLayout.json[`GelfLayout.json`]::
+Models https://docs.graylog.org/en/3.1/pages/gelf.html#gelf-payload-specification[the Graylog Extended Log Format (GELF) payload specification] with additional `_thread` and `_logger` fields.
++
+[TIP]
+====
+If used, it is advised to override the obligatory `host` field with a user provided constant via xref:#additional-event-template-fields[additional event template fields] to avoid `hostName` property lookup at runtime, which incurs an extra cost.
+====
+
+{project-github-url}/tree/2.x/log4j-layout-template-json/src/main/resources/GcpLayout.json[`GcpLayout.json`]::
+Models the structure described by https://cloud.google.com/logging/docs/structured-logging[Google Cloud Platform structured logging] with additional `_thread`, `_logger` and `_exception` fields.
+The exception trace, if any, is written to the `_exception` field as well as the `message` field – the former is useful for explicitly searching/analyzing structured exception information, while the latter is Google's expected place for the exception, and integrates with https://cloud.google.com/error-reporting[Google Error Reporting].
+
+{project-github-url}/tree/2.x/log4j-layout-template-json/src/main/resources/JsonLayout.json[`JsonLayout.json`]::
+Models the exact structure generated by the deprecated xref:manual/layouts.adoc#JSONLayout[`JsonLayout`] with the exception of `thrown` field.
+`JsonLayout` serializes the `Throwable` as is via Jackson `ObjectMapper`, whereas `JsonLayout.json` event template employs the `StackTraceElementLayout.json` stack trace template for stack traces to generate a document-store-friendly flat structure.
++
+[WARNING]
+====
+This event template is only meant for existing users of the deprecated `JsonLayout` to migrate to JSON Template Layout without much trouble, and other than that purpose, is not recommended to be used!
+====
[#event-template-resolvers]
-==== Event Template Resolvers
+==== Event template resolvers
-Event template resolvers consume a `LogEvent` and render a certain property of
-it at the point of the JSON where they are declared. For instance, `marker`
-resolver renders the marker of the event, `level` resolver renders the level,
-and so on. An event template resolver is denoted with a special object
-containing a `$resolver` key:
+Event template resolvers consume a `LogEvent` and render a certain property of it at the point of the JSON where they are declared.
+For instance, `marker` resolver renders the marker of the event, `level` resolver renders the level, and so on.
+An event template resolver is denoted with a special object containing a `$resolver` key:
.Example event template demonstrating the usage of `level` resolver
[source,json]
@@ -457,12 +522,14 @@ That is, this template will generate JSON similar to the following:
}
----
-The complete list of available event template resolvers are provided below in
-detail.
+The complete list of available event template resolvers are provided below in detail.
[#event-template-resolver-counter]
===== `counter`
+Resolves a number from an internal counter
+
+.`counter` event template resolver grammar
[source]
----
config = [ start ] , [ overflowing ] , [ stringified ]
@@ -471,26 +538,17 @@ overflowing = "overflowing" -> boolean
stringified = "stringified" -> boolean
----
-Resolves a number from an internal counter.
+Unless provided, `start` and `overflowing` are respectively set to `0` (zero) and `true` by default.
-Unless provided, `start` and `overflowing` are respectively set to zero and
-`true` by default.
+When `overflowing` is set to `true`, the internal counter is created using a `long`, which is subject to overflow while incrementing, though faster and garbage-free.
+Otherwise, a `BigInteger` is used, which does not overflow, but incurs allocation costs.
-When `stringified` is enabled, which is set to `false by default, the resolved
-number will be converted to a string.
+When `stringified` is enabled, which is set to `false` by default, the resolved number will be converted to a string.
-[WARNING]
+.See examples
+[%collapsible]
====
-When `overflowing` is set to `true`, the internal counter is created using a
-`long`, which is subject to overflow while incrementing, though garbage-free.
-Otherwise, a `BigInteger` is used, which does not overflow, but incurs
-allocation costs.
-====
-
-====== Examples
-
-Resolves a sequence of numbers starting from 0. Once `Long.MAX_VALUE` is
-reached, counter overflows to `Long.MIN_VALUE`.
+Resolves a sequence of numbers starting from 0. Once `Long.MAX_VALUE` is reached, counter overflows to `Long.MIN_VALUE`.
[source,json]
----
@@ -499,8 +557,7 @@ reached, counter overflows to `Long.MIN_VALUE`.
}
----
-Resolves a sequence of numbers starting from 1000. Once `Long.MAX_VALUE` is
-reached, counter overflows to `Long.MIN_VALUE`.
+Resolves a sequence of numbers starting from 1000. Once `Long.MAX_VALUE` is reached, counter overflows to `Long.MIN_VALUE`.
[source,json]
----
@@ -510,8 +567,7 @@ reached, counter overflows to `Long.MIN_VALUE`.
}
----
-Resolves a sequence of numbers starting from 0 and keeps on doing as long as
-JVM heap allows.
+Resolves a sequence of numbers starting from 0 and keeps on doing as long as JVM heap allows.
[source,json]
----
@@ -520,10 +576,14 @@ JVM heap allows.
"overflowing": false
}
----
+====
[#event-template-resolver-caseConverter]
===== `caseConverter`
+Converts the case of string values
+
+.`caseConverter` event template resolver grammar
[source]
----
config = case , input , [ locale ] , [ errorHandlingStrategy ]
@@ -542,40 +602,29 @@ errorHandlingStrategy = "errorHandlingStrategy" -> (
replacement = "replacement" -> JSON
----
-Converts the case of string values.
+`input` can be any available template value; e.g., a JSON literal, a lookup string, an object pointing to another resolver.
-`input` can be any available template value; e.g., a JSON literal, a lookup
-string, an object pointing to another resolver.
+Unless provided, `locale` points to the one returned by `JsonTemplateLayoutDefaults.getLocale()`, which is configured by the `log4j.layout.jsonTemplate.locale` system property and by default set to the default system locale.
-Unless provided, `locale` points to the one returned by
-`JsonTemplateLayoutDefaults.getLocale()`, which is configured by
-`log4j.layout.jsonTemplate.locale` system property and by default set to the
-default system locale.
+`errorHandlingStrategy` determines the behavior when either the input doesn't resolve to a string value or case conversion throws an exception:
-`errorHandlingStrategy` determines the behavior when either the input doesn't
-resolve to a string value or case conversion throws an exception:
-
-* `fail` propagates the failure
-* `pass` causes the resolved value to be passed as is
-* `replace` suppresses the failure and replaces it with the `replacement`,
-which is set to `null` by default
+`fail`:: Propagates the failure
+`pass`:: Causes the resolved value to be passed as is
+`replace`:: Suppresses the failure and replaces it with the `replacement`, which is set to `null` by default
`errorHandlingStrategy` is set to `replace` by default.
-Most of the time JSON logs are persisted to a storage solution (e.g.,
-Elasticsearch) that keeps a statically-typed index on fields. Hence, if a field
-is always expected to be of type string, using non-string ``replacement``s or
-`pass` in `errorHandlingStrategy` might result in type incompatibility issues at
-the storage level.
+Most of the time JSON logs are persisted to a storage solution (e.g., Elasticsearch) that keeps a statically-typed index on fields.
+Hence, if a field is always expected to be of type string, using non-string ``replacement``s or `pass` in `errorHandlingStrategy` might result in type incompatibility issues at the storage level.
[WARNING]
====
-Unless the input value is ``pass``ed intact or ``replace``d, case conversion is
-not garbage-free.
+Unless the input value is ``pass``ed intact or ``replace``d, case conversion is not garbage-free.
====
-====== Examples
-
+.See examples
+[%collapsible]
+====
Convert the resolved log level strings to upper-case:
[source,json]
@@ -590,8 +639,7 @@ Convert the resolved log level strings to upper-case:
}
----
-Convert the resolved `USER` environment variable to lower-case using `nl_NL`
-locale:
+Convert the resolved `USER` environment variable to lower-case using `nl_NL` locale:
[source,json]
----
@@ -618,9 +666,8 @@ Convert the resolved `sessionId` thread context data (MDC) to lower-case:
----
Above, if `sessionId` MDC resolves to a, say, number, case conversion will fail.
-Since `errorHandlingStrategy` is set to `replace` and replacement is set to
-`null` by default, the resolved value will be `null`. One can suppress this
-behavior and let the resolved `sessionId` number be left as is:
+Since `errorHandlingStrategy` is set to `replace` and replacement is set to `null` by default, the resolved value will be `null`.
+One can suppress this behavior and let the resolved `sessionId` number be left as is:
[source,json]
----
@@ -650,22 +697,19 @@ or replace it with a custom string:
"replacement": "unknown"
}
----
+====
[#event-template-resolver-endOfBatch]
===== `endOfBatch`
-[source,json]
-----
-{
- "$resolver": "endOfBatch"
-}
-----
-
-Resolves `logEvent.isEndOfBatch()` boolean flag.
+Resolves `LogEvent#isEndOfBatch()` boolean flag
[#event-template-resolver-exception]
===== `exception`
+Resolves fields of the `Throwable` returned by `LogEvent#getThrown()`
+
+.`exception` event template resolver grammar
[source]
----
config = field , [ stringified ] , [ stackTrace ]
@@ -689,60 +733,46 @@ pointMatcherRegexes = "pointMatcherRegexes" -> string[]
elementTemplate = "elementTemplate" -> object
----
-Resolves fields of the `Throwable` returned by `logEvent.getThrown()`.
+`stringified` is set to `false` by default.
+`stringified` at the root level is *deprecated* in favor of `stackTrace.stringified`, which has precedence if both are provided.
-`stringified` is set to `false` by default. `stringified` at the root level is
-*deprecated* in favor of `stackTrace.stringified`, which has precedence if both
-are provided.
+`pointMatcherStrings` and `pointMatcherRegexes` enable the truncation of stringified stack traces after the given matching point. If both parameters are provided, `pointMatcherStrings` will be checked first.
-`pointMatcherStrings` and `pointMatcherRegexes` enable the truncation of
-stringified stack traces after the given matching point. If both parameters are
-provided, `pointMatcherStrings` will be checked first.
+If a stringified stack trace truncation takes place, it will be indicated with a`suffix`, which by default is set to the configure `truncatedStringSuffix` in the layout, unless explicitly provided.
+Every truncation suffix is prefixed with a newline.
-If a stringified stack trace truncation takes place, it will be indicated with a
-`suffix`, which by default is set to the configured `truncatedStringSuffix` in
-the layout, unless explicitly provided. Every truncation suffix is prefixed with
-a newline.
+Stringified stack trace truncation operates in `Caused by:` and `Suppressed:` label blocks.
+That is, matchers are executed against each label in isolation.
-Stringified stack trace truncation operates in `Caused by:` and `Suppressed:`
-label blocks. That is, matchers are executed against each label in isolation.
-
-`elementTemplate` is an object describing the template to be used while
-resolving the `StackTraceElement` array. If `stringified` is set to `true`,
-`elementTemplate` will be discarded. By default, `elementTemplate` is set to
-`null` and rather populated from the layout configuration. That is, the stack
-trace element template can also be provided using
-`stackTraceElementTemplate[Uri]` layout configuration parameters. The template
-to be employed is determined in the following order:
+`elementTemplate` is an object describing the template to be used while resolving the `StackTraceElement` array.
+If `stringified` is set to `true`, `elementTemplate` will be discarded.
+By default, `elementTemplate` is set to `null` and rather populated from the layout configuration.
+That is, the stack trace element template can also be provided using xref:#plugin-attr-stackTraceElementTemplate[] and xref:#plugin-attr-stackTraceElementTemplateUri[] layout configuration attributes.
+The template to be employed is determined in the following order:
. `elementTemplate` provided in the resolver configuration
-. `stackTraceElementTemplate` parameter from layout configuration
-(the default is populated from `log4j.layout.jsonTemplate.stackTraceElementTemplate`
-system property)
+. xref:#plugin-attr-stackTraceElementTemplate[] layout configuration attribute
+(The default is populated from the `log4j.layout.jsonTemplate.stackTraceElementTemplate` system property.)
-. `stackTraceElementTemplateUri` parameter from layout configuration
-(the default is populated from `log4j.layout.jsonTemplate.stackTraceElementTemplateUri`
-system property)
+. xref:#plugin-attr-stackTraceElementTemplateUri[] layout configuration attribute
+(The default is populated from the `log4j.layout.jsonTemplate.stackTraceElementTemplateUri` system property.)
-See <<stack-trace-element-templates>>
-for the list of available resolvers in a stack trace element template.
+See xref:#stack-trace-element-templates[] for the list of available resolvers in a stack trace element template.
-Note that this resolver is toggled by
-`log4j.layout.jsonTemplate.stackTraceEnabled` property.
+Note that this resolver is toggled by the xref:#plugin-attr-stackTraceEnabled[] layout configuration attribute.
[WARNING]
====
-Since `Throwable#getStackTrace()` clones the original `StackTraceElement[]`,
-access to (and hence rendering of) stack traces are not garbage-free.
+Since `Throwable#getStackTrace()` clones the original `StackTraceElement[]`, access to (and hence rendering of) stack traces are not garbage-free.
-Each `pointMatcherRegexes` item triggers a `Pattern#matcher()` call, which is
-not garbage-free either.
+Each `pointMatcherRegexes` item triggers a `Pattern#matcher()` call, which is not garbage-free either.
====
-====== Examples
-
-Resolve `logEvent.getThrown().getClass().getCanonicalName()`:
+.See examples
+[%collapsible]
+====
+Resolve `LogEvent#getThrown().getClass().getCanonicalName()`:
[source,json]
----
@@ -775,8 +805,7 @@ Resolve the stack trace into a string field:
}
----
-Resolve the stack trace into a string field such that the content will be
-truncated after the given point matcher:
+Resolve the stack trace into a string field such that the content will be truncated after the given point matcher:
[source,json]
----
@@ -794,8 +823,7 @@ truncated after the given point matcher:
}
----
-Resolve the stack trace into an object described by the provided stack trace
-element template:
+Resolve the stack trace into an object described by the provided stack trace element template:
[source,json]
----
@@ -825,19 +853,21 @@ element template:
}
----
-See <<stack-trace-element-templates>> for further details on resolvers available
-for ``StackTraceElement`` templates.
+See xref:#stack-trace-element-templates[] for further details on resolvers available for `StackTraceElement` templates.
+====
[#event-template-resolver-exceptionRootCause]
===== `exceptionRootCause`
-Resolves the fields of the innermost `Throwable` returned by
-`logEvent.getThrown()`. Its syntax and garbage-footprint are identical to the
-xref:#event-template-resolver-exception[] resolver.
+Resolves the fields of the innermost `Throwable` returned by `LogEvent#getThrown()`.
+Its syntax and garbage-footprint are identical to the xref:#event-template-resolver-exception[] resolver.
[#event-template-resolver-level]
===== `level`
+Resolves the fields of the `LogEvent#getLevel()`
+
+.`level` event template resolver grammar
[source]
----
config = field , [ severity ]
@@ -846,10 +876,9 @@ severity = severity-field
severity-field = "field" -> ( "keyword" | "code" )
----
-Resolves the fields of the `logEvent.getLevel()`.
-
-====== Examples
-
+.See examples
+[%collapsible]
+====
Resolve the level name:
[source,json]
@@ -860,8 +889,7 @@ Resolve the level name:
}
----
-Resolve the https://en.wikipedia.org/wiki/Syslog#Severity_levels[Syslog severity]
-keyword:
+Resolve the https://en.wikipedia.org/wiki/Syslog#Severity_levels[Syslog severity] keyword:
[source,json]
----
@@ -874,8 +902,7 @@ keyword:
}
----
-Resolve the https://en.wikipedia.org/wiki/Syslog#Severity_levels[Syslog severity]
-code:
+Resolve the https://en.wikipedia.org/wiki/Syslog#Severity_levels[Syslog severity] code:
[source,json]
----
@@ -887,19 +914,22 @@ code:
}
}
----
+====
[#event-template-resolver-logger]
===== `logger`
+Resolves `LogEvent#getLoggerFqcn()` and `LogEvent#getLoggerName()`.
+
+.`logger` event template grammar
[source]
----
config = "field" -> ( "name" | "fqcn" )
----
-Resolves `logEvent.getLoggerFqcn()` and `logEvent.getLoggerName()`.
-
-====== Examples
-
+.See examples
+[%collapsible]
+====
Resolve the logger name:
[source,json]
@@ -919,10 +949,14 @@ Resolve the logger's fully qualified class name:
"field": "fqcn"
}
----
+====
[#event-template-resolver-main]
===== `main`
+Performs xref:manual/lookups.adoc#AppMainArgsLookup[Main Argument Lookup] for the given `index` or `key`
+
+.`main` event template resolver grammar
[source]
----
config = ( index | key )
@@ -930,11 +964,9 @@ index = "index" -> number
key = "key" -> string
----
-Performs xref:manual/lookups.adoc#AppMainArgsLookup[Main Argument Lookup] for the
-given `index` or `key`.
-
-====== Examples
-
+.See examples
+[%collapsible]
+====
Resolve the 1st `main()` method argument:
[source,json]
@@ -954,25 +986,28 @@ Resolve the argument coming right after `--userId`:
"key": "--userId"
}
----
+====
[#event-template-resolver-map]
===== `map`
-Resolves ``MapMessage``s. See link:#map-resolver-template[Map Resolver Template]
-for details.
+Resolves ``MapMessage``s.
+See <<map-resolver-template>> for details.
[#event-template-resolver-marker]
===== `marker`
+Resolves the xref:manual/markers.adoc[marker] of the event
+
+.`marker` event template resolver grammar
[source]
----
config = "field" -> ( "name" | "parents" )
----
-Resolves `logEvent.getMarker()`.
-
-====== Examples
-
+.See examples
+[%collapsible]
+====
Resolve the marker name:
[source,json]
@@ -992,22 +1027,25 @@ Resolve the names of the marker's parents:
"field": "parents"
}
----
+====
[#event-template-resolver-mdc]
===== `mdc`
-Resolves Mapped Diagnostic Context (MDC), aka. Thread Context Data. See
-link:#map-resolver-template[Map Resolver Template] for details.
+Resolves the xref:manual/thread-context.adoc[thread context] map, aka. Mapped Diagnostic Context (MDC).
+See <<map-resolver-template>> for details.
[WARNING]
====
-`log4j2.garbagefreeThreadContextMap` flag needs to be turned on to iterate
-the map without allocations.
+`log4j2.garbagefreeThreadContextMap` flag needs to be turned on to iterate the map without allocations.
====
[#event-template-resolver-message]
===== `message`
+Resolves the xref:manual/messages.adoc[message] of the event
+
+.`message` event template resolver grammar
[source]
----
config = [ stringified ] , [ fallbackKey ]
@@ -1015,16 +1053,15 @@ stringified = "stringified" -> boolean
fallbackKey = "fallbackKey" -> string
----
-Resolves `logEvent.getMessage()`.
-
[WARNING]
====
For simple string messages, the resolution is performed without allocations.
For ``ObjectMessage``s and ``MultiformatMessage``s, it depends.
====
-====== Examples
-
+.See examples
+[%collapsible]
+====
Resolve the message into a string:
[source,json]
@@ -1035,9 +1072,7 @@ Resolve the message into a string:
}
----
-Resolve the message such that if it is an `ObjectMessage` or a
-`MultiformatMessage` with JSON support, its type (string, list, object, etc.)
-will be retained:
+Resolve the message such that if it is an `ObjectMessage` or a `MultiformatMessage` with JSON support, its type (string, list, object, etc.) will be retained:
[source,json]
----
@@ -1046,12 +1081,9 @@ will be retained:
}
----
-Given the above configuration, a `SimpleMessage` will generate a `"sample log
-message"`, whereas a `MapMessage` will generate a `{"action": "login",
-"sessionId": "87asd97a"}`. Certain indexed log storage systems (e.g.,
-https://www.elastic.co/elasticsearch/[Elasticsearch]) will not allow both values
-to coexist due to type mismatch: one is a `string` while the other is an `object`.
-Here one can use a `fallbackKey` to work around the problem:
+Given the above configuration, a `SimpleMessage` will generate a `"sample log message"`, whereas a `MapMessage` will generate a `{"action": "login", "sessionId": "87asd97a"}`.
+Certain indexed log storage systems (e.g., https://www.elastic.co/elasticsearch/[Elasticsearch]) will not allow both values to coexist due to type mismatch: one is a `string` while the other is an `object`.
+Here one can use a `fallbackKey` to work around this problem:
[source,json]
----
@@ -1061,14 +1093,16 @@ Here one can use a `fallbackKey` to work around the problem:
}
----
-Using this configuration, a `SimpleMessage` will generate a
-`{"formattedMessage": "sample log message"}` and a `MapMessage` will generate a
-`{"action": "login", "sessionId": "87asd97a"}`. Note that both emitted JSONs are
-of type `object` and have no type-conflicting fields.
+Using this configuration, a `SimpleMessage` will generate a `{"formattedMessage": "sample log message"}`, and a `MapMessage` will generate a `{"action": "login", "sessionId": "87asd97a"}`.
+Note that both emitted JSONs are of type `object` and have no type-conflicting fields.
+====
[#event-template-resolver-messageParameter]
===== `messageParameter`
+Resolves `LogEvent#getMessage().getParameters()`
+
+.`messageParameter` event template resolver grammar
[source]
----
config = [ stringified ] , [ index ]
@@ -1076,18 +1110,15 @@ stringified = "stringified" -> boolean
index = "index" -> number
----
-Resolves `logEvent.getMessage().getParameters()`.
-
[WARNING]
====
-Regarding garbage footprint, `stringified` flag translates to
-`String.valueOf(value)`, hence mind not-`String`-typed values. Further,
-`logEvent.getMessage()` is expected to implement `ParameterVisitable` interface,
-which is the case if `log4j2.enableThreadlocals` property set to true.
+Regarding garbage footprint, `stringified` flag translates to `String.valueOf(value)`, hence mind values that are not `String`-typed.
+Further, `LogEvent#getMessage()` is expected to implement `ParameterVisitable` interface, which is the case if `log4j2.enableThreadlocals` property set to `true`.
====
-====== Examples
-
+.See examples
+[%collapsible]
+====
Resolve the message parameters into an array:
[source,json]
@@ -1127,21 +1158,23 @@ Resolve the string representation of the first message parameter:
"stringified": true
}
----
+====
[#event-template-resolver-ndc]
===== `ndc`
+Resolves the xref:manual/thread-context.adoc[thread context] stack – aka. Nested Diagnostic Context (NDC), aka – `String[]` returned by `LogEvent#getContextStack()`
+
+.`ndc` event template resolver grammar
[source]
----
config = [ pattern ]
pattern = "pattern" -> string
----
-Resolves the Nested Diagnostic Context (NDC), aka. Thread Context Stack,
-`String[]` returned by `logEvent.getContextStack()`.
-
-====== Examples
-
+.See examples
+[%collapsible]
+====
Resolve all NDC values into a list:
[source,json]
@@ -1160,10 +1193,14 @@ Resolve all NDC values matching with the `pattern` regex:
"pattern": "user(Role|Rank):\\w+"
}
----
+====
[#event-template-resolver-pattern]
===== `pattern`
+Resolver delegating to xref:manual/pattern-layout.adoc[]
+
+.`pattern` event template resolver grammar
[source]
----
config = pattern , [ stackTraceEnabled ]
@@ -1171,13 +1208,18 @@ pattern = "pattern" -> string
stackTraceEnabled = "stackTraceEnabled" -> boolean
----
-Resolver delegating to xref:manual/layouts.adoc#pattern-layout[`PatternLayout`].
+The default value of `stackTraceEnabled` is inherited from the parent JSON Template Layout.
-The default value of `stackTraceEnabled` is inherited from the parent
-`JsonTemplateLayout`.
-
-====== Examples
+[NOTE]
+====
+This resolver is mostly intended as an emergency lever when all other JSON Template Layout resolvers fall short of addressing your need.
+If you find yourself using this, it is highly likely you are either doing something wrong, or JSON Template Layout needs some improvement.
+In either case, you are advised to share your use case with maintainers in one of {logging-services-url}/support.html[our support channels].
+====
+.See examples
+[%collapsible]
+====
Resolve the string produced by `%p %c{1.} [%t] %X\{userId} %X %m%ex` pattern:
[source,json]
@@ -1187,10 +1229,14 @@ Resolve the string produced by `%p %c{1.} [%t] %X\{userId} %X %m%ex` pattern:
"pattern": "%p %c{1.} [%t] %X{userId} %X %m%ex"
}
----
+====
[#event-template-resolver-source]
===== `source`
+Resolves the fields of the `StackTraceElement` returned by `LogEvent#getSource()`
+
+.`source` event template resolver grammar
[source]
----
config = "field" -> (
@@ -1200,21 +1246,18 @@ config = "field" -> (
"lineNumber" )
----
-Resolves the fields of the `StackTraceElement` returned by
-`logEvent.getSource()`.
-
-Note that this resolver is toggled by
-`log4j.layout.jsonTemplate.locationInfoEnabled` property.
+Note that this resolver is toggled by the xref:#plugin-attr-locationInfoEnabled[] layout configuration attribute.
[WARNING]
====
-Mind that capturing the source location information is an expensive operation, and is not garbage-free.
-Note that xref:#event-template-resolver-logger[the `logger` resolver] can generally be used as a zero-cost substitute for `className`.
+Capturing the source location information is an expensive operation, and is not garbage-free.
+xref:#event-template-resolver-logger[The `logger` resolver] can generally be used as a zero-cost substitute for `className`.
See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
====
-====== Examples
-
+.See examples
+[%collapsible]
+====
Resolve the line number:
[source,json]
@@ -1224,20 +1267,22 @@ Resolve the line number:
"field": "lineNumber"
}
----
+====
[#event-template-resolver-thread]
===== `thread`
+Resolves `LogEvent#getThreadId()`, `LogEvent#getThreadName()`, `LogEvent#getThreadPriority()`
+
+.`thread` event template resolver grammar
[source]
----
config = "field" -> ( "name" | "id" | "priority" )
----
-Resolves `logEvent.getThreadId()`, `logEvent.getThreadName()`,
-`logEvent.getThreadPriority()`.
-
-====== Examples
-
+.See examples
+[%collapsible]
+====
Resolve the thread name:
[source,json]
@@ -1247,10 +1292,14 @@ Resolve the thread name:
"field": "name"
}
----
+====
[#event-template-resolver-timestamp]
===== `timestamp`
+Resolves `LogEvent#getInstant()`
+
+.`timestamp` event template resolver grammar
[source]
----
config = [ patternConfig | epochConfig ]
@@ -1275,12 +1324,11 @@ unit = "unit" -> (
rounded = "rounded" -> boolean
----
-Resolves `logEvent.getInstant()` in various forms.
-
-====== Examples
-
+.See examples
+[%collapsible]
+====
.`timestamp` template resolver examples
-[cols="5,2m"]
+[cols="3,2m"]
|===
| Configuration
| Output
@@ -1394,18 +1442,17 @@ a|
----
| 1581082727982123456
|===
+====
[#map-resolver-template]
-==== Map Resolver Template
+==== Map resolver
-`ReadOnlyStringMap` is Log4j's `Map<String, Object>` equivalent with
-garbage-free accessors and heavily employed throughout the code base. It is the
-data structure backing both Mapped Diagnostic Context (MDC), aka. Thread Context
-Data and `MapMessage` implementations. Hence template resolvers for both of
-these are provided by a single backend: `ReadOnlyStringMapResolver`. Put another
-way, both `mdc` and `map` resolvers support identical configuration, behaviour,
-and garbage footprint, which are detailed below.
+link:../javadoc/log4j-api/org/apache/logging/log4j/util/ReadOnlyStringMap.html[`ReadOnlyStringMap`] is Log4j's `Map<String, Object>` equivalent with garbage-free accessors, and is heavily employed throughout the code base.
+It is the data structure backing both xref:manual/thread-context.adoc[thread context] map (aka., Mapped Diagnostic Context (MDC)) and link:../javadoc/log4j-api/org/apache/logging/log4j/message/MapMessage.html[`MapMessage`] implementations.
+Hence template resolvers for both of these are provided by a single backend: `ReadOnlyStringMapResolver`.
+Put another way, both xref:#event-template-resolver-mdc[] and xref:#event-template-resolver-map[] resolvers support identical configuration, behaviour, and garbage footprint, which are detailed below.
+.Map resolver grammar
[source]
----
config = singleAccess | multiAccess
@@ -1422,31 +1469,28 @@ flattenConfig = [ flattenPrefix ]
flattenPrefix = "prefix" -> string
----
-`singleAccess` resolves a single field, whilst `multiAccess` resolves a
-multitude of fields. If `flatten` is provided, `multiAccess` merges the fields
-with the parent, otherwise creates a new JSON object containing the values.
+`singleAccess` resolves a single field, whilst `multiAccess` resolves a multitude of fields.
+If `flatten` is provided, `multiAccess` merges the fields with the parent, otherwise creates a new JSON object containing the values.
Enabling `stringified` flag converts each value to its string representation.
-Regex provided in the `pattern` is used to match against the keys. If provided,
-`replacement` will be used to replace the matched keys. These two are
-effectively equivalent to `Pattern.compile(pattern).matcher(key).matches()` and
-`Pattern.compile(pattern).matcher(key).replaceAll(replacement)` calls.
+Regex provided in the `pattern` is used to match against the keys.
+If provided, `replacement` will be used to replace the matched keys.
+These two are analogous to `Pattern.compile(pattern).matcher(key).matches()` and `Pattern.compile(pattern).matcher(key).replaceAll(replacement)` calls.
[WARNING]
====
-Regarding garbage footprint, `stringified` flag translates to
-`String.valueOf(value)`, hence mind not-`String`-typed values.
+Regarding garbage footprint, `stringified` flag translates to `String.valueOf(value)`, hence mind values that are not `String`-typed.
`pattern` and `replacement` incur pattern matcher allocation costs.
-Writing certain non-primitive values (e.g., `BigDecimal`, `Set`, etc.) to JSON
-generates garbage, though most (e.g., `int`, `long`, `String`, `List`,
-`boolean[]`, etc.) don't.
+Writing certain non-primitive values (e.g., `BigDecimal`, `Set`, etc.) to JSON generates garbage, though most (e.g., `int`, `long`, `String`, `List`, `boolean[]`, etc.) don't.
====
-`"$resolver"` is left out in the following examples, since it is to be
-defined by the actual resolver, e.g., `map`, `mdc`.
+.See examples
+[%collapsible]
+====
+`"$resolver"` is left out in the following examples, since it is to be defined by the actual resolver, e.g., `map`, `mdc`.
Resolve the value of the field keyed with `user:role`:
@@ -1488,8 +1532,7 @@ Resolve all fields into an object such that values are converted to string:
}
----
-Resolve all fields whose keys match with the `user:(role|rank)` regex into an
-object:
+Resolve all fields whose keys match with the `user:(role|rank)` regex into an object:
[source,json]
----
@@ -1499,8 +1542,7 @@ object:
}
----
-Resolve all fields whose keys match with the `user:(role|rank)` regex into an
-object after removing the `user:` prefix in the key:
+Resolve all fields whose keys match with the `user:(role|rank)` regex into an object after removing the `user:` prefix in the key:
[source,json]
----
@@ -1511,8 +1553,7 @@ object after removing the `user:` prefix in the key:
}
----
-Merge all fields whose keys are matching with the `user:(role|rank)` regex into
-the parent:
+Merge all fields whose keys are matching with the `user:(role|rank)` regex into the parent:
[source,json]
----
@@ -1523,8 +1564,7 @@ the parent:
}
----
-After converting the corresponding field values to string, merge all fields to
-parent such that keys are prefixed with `_`:
+After converting the corresponding field values to string, merge all fields to parent such that keys are prefixed with `_`:
[source,json]
----
@@ -1536,22 +1576,26 @@ parent such that keys are prefixed with `_`:
}
}
----
+====
[#stack-trace-element-templates]
-=== Stack Trace Element Templates
+=== Stack trace element templates
-xref:#event-template-resolver-exception[] and
-xref:#event-template-resolver-exceptionRootCause[] event template resolvers can
-serialize an exception stack trace (i.e., `StackTraceElement[]` returned by
-`Throwable#getStackTrace()`) into a JSON array. While doing so, JSON templating
-infrastructure is used again.
+xref:#event-template-resolver-exception[] and xref:#event-template-resolver-exceptionRootCause[] event template resolvers can encode an exception stack trace (i.e., `StackTraceElement[]` returned by `Throwable#getStackTrace()`) into a JSON array.
+While doing so, they employ the underlying JSON templating infrastructure again.
+The stack trace template used by these event template resolvers to encode ``StackTraceElement``s can be configured in following ways:
-`stackTraceElement[Uri]` describes the JSON structure `JsonTemplateLayout` uses
-to format ``StackTraceElement``s. The default configuration (accessible by
-`log4j.layout.jsonTemplate.stackTraceElementTemplate[Uri]` property) is set to
-`classpath:StackTraceElementLayout.json` provided by the
-`log4j-layout-template-json` artifact:
+. `elementTemplate` provided in the resolver configuration
+. xref:#plugin-attr-stackTraceElementTemplate[] layout configuration attribute
+(The default is populated from the `log4j.layout.jsonTemplate.stackTraceElementTemplate` system property.)
+
+. xref:#plugin-attr-stackTraceElementTemplateUri[] layout configuration attribute
+(The default is populated from the `log4j.layout.jsonTemplate.stackTraceElementTemplateUri` system property.)
+
+By default, xref:#plugin-attr-stackTraceElementTemplateUri[] is set to `classpath:StackTraceElementLayout.json`, which references to a classpath resource bundled with JSON Template Layout:
+
+.`StackTraceElementLayout.json` bundled as a classpath resource
[source,json]
----
{
@@ -1574,8 +1618,19 @@ to format ``StackTraceElement``s. The default configuration (accessible by
}
----
-The allowed template configuration syntax is as follows:
+[#stack-trace-element-template-resolvers]
+==== Stack trace element template resolvers
+
+Similar to xref:#event-template-resolvers[] consuming a `LogEvent` and rendering a certain property of it at the point of the JSON where they are declared, stack trace element template resolvers consume a `StackTraceElement`.
+The complete list of available event template resolvers are provided below in detail.
+
+[#stack-trace-element-template-resolver-stackTraceElement]
+===== `stackTraceElement`
+
+Resolves certain fields of a `StackTraceElement`
+
+.Stack trace template resolver grammar
[source]
----
config = "field" -> (
@@ -1587,49 +1642,82 @@ config = "field" -> (
All above accesses to `StackTraceElement` is garbage-free.
+[#recycling-strategy]
+== Recycling strategy
+
+Encoding a `LogEvent` without a load on the garbage-collector can yield significant performance benefits.
+JSON Template Layout contains the `Recycler` interface to implement xref:manual/garbagefree.adoc[].
+A `Recycler` is created using a `RecyclerFactory`, which implements a particular recycling strategy.
+JSON Template Layout contains the following predefined recycler factories:
+
+`dummy`::
+It performs no recycling, hence each recycling attempt will result in a new instance.
+This will obviously create a load on the garbage-collector.
+It is a good choice for applications with low and medium log rate.
+
+`threadLocal`::
+It performs the best, since every instance is stored in ``ThreadLocal``s and accessed without any synchronization cost.
+Though this might not be a desirable option for applications running with a considerable number of threads, e.g., a web servlet.
+
+`queue`::
+It is the best of both worlds.
+It allows recycling of objects up to a certain number (`capacity`).
+When this limit is exceeded due to excessive concurrent load (e.g., `capacity` is 50 but there are 51 threads concurrently trying to encode), it starts allocating.
+`queue` is a good strategy where `threadLocal` is not desirable.
++
+`queue` accepts following optional parameters:
++
+`supplier`::: of type `java.util.Queue`, defaults to `org.jctools.queues.MpmcArrayQueue.new` if JCTools is in the classpath; otherwise `java.util.concurrent.ArrayBlockingQueue.new`
+`capacity`::: of type `int`, defaults to `max(8,2*cpuCount+1)`
+
++
+Some example configurations of `queue` recycling strategy are as follows:
+
+* `queue:supplier=org.jctools.queues.MpmcArrayQueue.new` (use `MpmcArrayQueue` from JCTools)
+* `queue:capacity=10` (set the queue capacity to 10)
+* `queue:supplier=java.util.concurrent.ArrayBlockingQueue.new,capacity=50` (use `ArrayBlockingQueue` with a capacity of 50)
+
+The default `RecyclerFactory` is `threadLocal`, if `log4j2.enable.threadlocals=true`; otherwise, `queue`.
+The effective recycler factory can be configured using the xref:#plugin-attr-recyclerFactory[] plugin attribute.
+
+Next to predefined ones, you can introduce custom `RecyclerFactory` implementations too.
+See <<extending-recycler>> for details.
+
[#extending]
== Extending
-`JsonTemplateLayout` relies on Log4j xref:manual/plugins.adoc[plugin system] to build
-up the features it provides. This enables feature customization a breeze for
-users. As of this moment, following features are implemented by means of
-plugins:
+JSON Template Layout relies on xref:manual/plugins.adoc[the Log4j plugin system] to compose the features it provides.
+This makes it possible for users to extend the plugin-based feature set as they see fit.
+As of this moment, following features are implemented by means of plugins:
* Event template resolvers (e.g., `exception`, `message`, `level` event template resolvers)
* Event template interceptors (e.g., injection of `eventTemplateAdditionalField`)
* Recycler factories
-Following sections cover these in detail.
+Following sections cover how to extend these in detail.
-[#extending-plugins]
-=== Plugin Preliminaries
+[NOTE]
+====
+While existing features should address most common use cases, you might find yourself needing to implement a custom one.
+If this is the case, we really appreciate it if you can *share your use case in a {logging-services-url}/support.html[user support channel]*.
+====
-Log4j plugin system is the de facto extension mechanism embraced by various
-Log4j components, including `JsonTemplateLayout`. Plugins make it possible
-for extensible components _receive_ feature implementations without any explicit
-links in between. It is analogous to a
-https://en.wikipedia.org/wiki/Dependency_injection[dependency injection]
-framework, but curated for Log4j-specific needs.
+[#extending-plugins]
+=== Plugin preliminaries
-In a nutshell, you annotate your classes with `@Plugin` and their (`static`)
-creator methods with `@PluginFactory`. Last, you inform the Log4j plugin system
-to discover these custom classes. This can be done either using `packages`
-declared in your Log4j configuration or by various other ways described in
-xref:manual/plugins.adoc[plugin system documentation].
+include::partial$manual/plugin-preliminaries.adoc[]
[#extending-event-resolvers]
-=== Extending Event Resolvers
+=== Extending event template resolvers
-All available xref:#event-template-resolvers[event template resolvers] are simple
-plugins employed by `JsonTemplateLayout`. To add new ones, one just needs to
-create their own `EventResolver` and instruct its injection via a
-`@Plugin`-annotated `EventResolverFactory` class.
+All available xref:#event-template-resolvers[event template resolvers] are simple plugins employed by JSON Template Layout.
+To add new ones, one just needs to create their own `EventResolver` and instruct its injection via a `@Plugin`-annotated `EventResolverFactory` class.
-For demonstration purposes, below we will create a `randomNumber` event resolver.
+For demonstration purposes, below we will create a `randomNumber` event template resolver.
Let's start with the actual resolver:
[source,java]
-.Custom random number event resolver
+.Custom random number event template resolver
----
package com.acme.logging.log4j.layout.template.json;
@@ -1676,8 +1764,8 @@ public final class RandomNumberResolver implements EventResolver {
private final double hiExcLimit;
- RandomNumberResolver(final TemplateResolverConfig config) {
- final List<Number> rangeArray = config.getList("range", Number.class);
+ RandomNumberResolver(TemplateResolverConfig config) {
+ List<Number> rangeArray = config.getList("range", Number.class);
if (rangeArray == null) {
this.loIncLimit = 0D;
this.hiExcLimit = 1D;
@@ -1698,22 +1786,18 @@ public final class RandomNumberResolver implements EventResolver {
}
@Override
- public void resolve(
- final LogEvent value,
- final JsonWriter jsonWriter) {
- final double randomNumber =
- loIncLimit + (hiExcLimit - loIncLimit) * Math.random();
+ public void resolve(LogEvent value, JsonWriter jsonWriter) {
+ double randomNumber = loIncLimit + (hiExcLimit - loIncLimit) * Math.random();
jsonWriter.writeNumber(randomNumber);
}
}
----
-Next create a `EventResolverFactory` class to register `RandomNumberResolver`
-into the Log4j plugin system.
+Next, create an `EventResolverFactory` class to admit `RandomNumberResolver` into the event resolver factory plugin registry.
[source,java]
-.Resolver factory class to register `RandomNumberResolver` into the Log4j plugin system
+.Resolver factory class to admit `RandomNumberResolver` into the event resolver factory plugin registry
----
package com.acme.logging.log4j.layout.template.json;
@@ -1731,8 +1815,7 @@ import org.apache.logging.log4j.layout.template.json.resolver.TemplateResolverFa
@Plugin(name = "RandomNumberResolverFactory", category = TemplateResolverFactory.CATEGORY)
public final class RandomNumberResolverFactory implements EventResolverFactory {
- private static final RandomNumberResolverFactory INSTANCE =
- new RandomNumberResolverFactory();
+ private static final RandomNumberResolverFactory INSTANCE = new RandomNumberResolverFactory();
private RandomNumberResolverFactory() {}
@@ -1747,23 +1830,25 @@ public final class RandomNumberResolverFactory implements EventResolverFactory {
}
@Override
- public RandomNumberResolver create(
- final EventResolverContext context,
- final TemplateResolverConfig config) {
+ public RandomNumberResolver create(EventResolverContext context, TemplateResolverConfig config) {
return new RandomNumberResolver(config);
}
}
----
-Almost complete. Last, we need to inform the Log4j plugin system to discover
-these custom classes:
+Done!
+Let's use our custom event resolver:
[source,xml]
-.Log4j configuration employing custom `randomNumber` resolver
+.Log4j configuration employing the custom `randomNumber` event resolver
----
<?xml version="1.0" encoding="UTF-8"?>
-<Configuration>
+<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns="https://logging.apache.org/xml/ns"
+ xsi:schemaLocation="
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd">
<!-- ... -->
<JsonTemplateLayout>
<EventTemplateAdditionalField
@@ -1775,23 +1860,17 @@ these custom classes:
</Configuration>
----
-All available event template resolvers are located in
-`org.apache.logging.log4j.layout.template.json.resolver` package. It is a fairly
-rich resource for inspiration while implementing new resolvers.
+All available event template resolvers are located in `org.apache.logging.log4j.layout.template.json.resolver` package.
+It is a fairly rich resource for inspiration while implementing new resolvers.
[#extending-template-resolver]
-=== Intercepting the Template Resolver Compiler
+=== Intercepting the template resolver compiler
-`JsonTemplateLayout` allows interception of the template resolver compilation,
-which is the process converting a template into a Java function performing the
-JSON serialization. This interception mechanism is internally used to implement
-`eventTemplateRootObjectKey` and `eventTemplateAdditionalField` features. In a
-nutshell, one needs to create a `@Plugin`-annotated class extending from
-`EventResolverInterceptor` interface.
+JSON Template Layout allows interception of the template resolver compilation, which is the process converting a template into a Java function performing the JSON encoding.
+This interception mechanism is internally used to implement xref:#plugin-attr-eventTemplateRootObjectKey[] and xref:#plugin-element-EventTemplateAdditionalField[] features.
+In a nutshell, one needs to create a `@Plugin`-annotated class extending from the `EventResolverInterceptor` interface.
-To see the interception in action, check out the `EventRootObjectKeyInterceptor`
-class which is responsible for implementing the `eventTemplateRootObjectKey`
-feature:
+To see the interception in action, check out the `EventRootObjectKeyInterceptor` class which is responsible for implementing the `eventTemplateRootObjectKey` feature:
[source,java]
.Event interceptor to add `eventTemplateRootObjectKey`, if present
@@ -1817,9 +1896,7 @@ public class EventRootObjectKeyInterceptor implements EventResolverInterceptor {
}
@Override
- public Object processTemplateBeforeResolverInjection(
- final EventResolverContext context,
- final Object node) {
+ public Object processTemplateBeforeResolverInjection(EventResolverContext context, Object node) {
String eventTemplateRootObjectKey = context.getEventTemplateRootObjectKey();
return eventTemplateRootObjectKey != null
? Collections.singletonMap(eventTemplateRootObjectKey, node)
@@ -1829,18 +1906,15 @@ public class EventRootObjectKeyInterceptor implements EventResolverInterceptor {
}
----
-Here, `processTemplateBeforeResolverInjection()` method checks if the user has
-provided an `eventTemplateRootObjectKey`. If so, it wraps the root `node` with a
-new object; otherwise, returns the `node` as is. Note that `node` refers to the
-root Java object of the event template read by `JsonReader`.
+Here, `processTemplateBeforeResolverInjection()` method checks if the user has provided an `eventTemplateRootObjectKey`.
+If so, it wraps the root `node` with a new object; otherwise, returns the `node` as is.
+Note that `node` refers to the root Java object of the event template read by `JsonReader`.
[#extending-recycler]
-=== Extending Recycler Factories
+=== Extending recycler factories
-`recyclerFactory` input `String` read from the layout configuration is converted
-to a `RecyclerFactory` using the default `RecyclerFactoryConverter` extending
-from `TypeConverter<RecyclerFactory>`. If one wants to change this behavior,
-they simply need to add their own `TypeConverter<RecyclerFactory>` implementing
+xref:#plugin-attr-recyclerFactory[] layout configuration attribute is converted from `String` to a `RecyclerFactory` using the default `RecyclerFactoryConverter` extending from `TypeConverter<RecyclerFactory>`.
+If one wants to change this behavior, they simply need to add their own `TypeConverter<RecyclerFactory>` implementing
`Comparable<TypeConverter<?>>` to prioritize their custom converter.
[source,java]
@@ -1852,13 +1926,12 @@ import org.apache.logging.log4j.core.config.plugins.Plugin;
import org.apache.logging.log4j.core.config.plugins.convert.TypeConverter;
import org.apache.logging.log4j.core.config.plugins.convert.TypeConverters;
-@Plugin(name = "AcmeRecyclerFactoryConverter", category = TypeConverters.CATEGORY)
-public final class AcmeRecyclerFactoryConverter
- implements TypeConverter<RecyclerFactory>, Comparable<TypeConverter<?>> {
+@Plugin(name = "ExampleRecyclerFactoryConverter", category = TypeConverters.CATEGORY)
+public final class ExampleRecyclerFactoryConverter implements TypeConverter<RecyclerFactory>, Comparable<TypeConverter<?>> {
@Override
- public RecyclerFactory convert(final String recyclerFactorySpec) {
- return AcmeRecyclerFactory.ofSpec(recyclerFactorySpec);
+ public RecyclerFactory convert(String recyclerFactorySpec) {
+ return ExampleRecyclerFactory.ofSpec(recyclerFactorySpec);
}
@Override
@@ -1869,14 +1942,12 @@ public final class AcmeRecyclerFactoryConverter
}
----
-Here note that `compareTo()` always returns -1 to rank it higher compared to
-other matching converters.
+Here note that `compareTo()` always returns -1 to rank it higher compared to other matching converters.
[#features]
== Features
-Below is a feature comparison matrix between `JsonTemplateLayout` and
-alternatives.
+Below is a feature comparison matrix between JSON Template Layout and alternatives.
.Feature comparison matrix
[cols="3,1,1,1,1"]
@@ -1983,10 +2054,11 @@ To get the most out of it, mind the following checklist:
[#faq-lookups]
=== Are lookups supported in templates?
-Yes, xref:manual/lookups.adoc[lookups] (e.g., `${java:version}`,
-`${env:USER}`, `${date:MM-dd-yyyy}`) are supported in string
-literals of templates. Though note that they are not garbage-free.
+Yes, xref:manual/lookups.adoc[lookups] (e.g., `${java:version}`, `${env:USER}`, `${date:MM-dd-yyyy}`) are supported in string literals of templates.
+
+include::partial$manual/layouts-gcfree-lookup.adoc[]
+[#faq-recursive-collection]
=== Are recursive collections supported?
No. Consider a `Message` containing a recursive value as follows:
@@ -1997,29 +2069,22 @@ Object[] recursiveCollection = new Object[1];
recursiveCollection[0] = recursiveCollection;
----
-While the exact exception might vary, you will most like get a
-`StackOverflowError` for trying to render `recursiveCollection` into a
-`String`. Note that this is also the default behaviour for other Java standard
-library methods, e.g., `Arrays.toString()`. Hence mind self references while
-logging.
+While the exact exception might vary, you will most like get a `StackOverflowError` for trying to render `recursiveCollection` into a `String`.
+Note that this is also the default behaviour for other Java standard library methods, e.g., `Arrays.toString()`.
+Hence mind self references while logging.
[#faq-garbage-free]
-=== Is `JsonTemplateLayout` garbage-free?
+=== Is JSON Template Layout garbage-free?
Yes, if xref:manual/garbagefree.adoc[garbage-free logging] is enabled.
Take into account the following caveats:
-* The configured link:#recycling-strategy[recycling strategy] might not be
- garbage-free.
+* The configured link:#recycling-strategy[recycling strategy] might not be garbage-free.
-* Since `Throwable#getStackTrace()` clones the original `StackTraceElement[]`,
- access to (and hence rendering of) stack traces are not garbage-free.
+* Since `Throwable#getStackTrace()` clones the original `StackTraceElement[]`, access to (and hence rendering of) stack traces are not garbage-free.
-* Serialization of ``MapMessage``s and ``ObjectMessage``s are mostly
- garbage-free except for certain types (e.g., `BigDecimal`, `BigInteger`,
- ``Collection``s, except `List`).
+* Serialization of ``MapMessage``s and ``ObjectMessage``s are mostly garbage-free except for certain types (e.g., `BigDecimal`, `BigInteger`, ``Collection``s, except `List`).
* xref:manual/lookups.adoc[Lookups] (that is, `${...}` variables) are not garbage-free.
-Don't forget to check out xref:#event-template-resolvers[the notes on garbage footprint of resolvers]
-you employ in templates.
+Don't forget to check out xref:#event-template-resolvers[the notes on garbage footprint of resolvers] you employ in templates.
diff --git a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
index 5b514265d6..ec12ec8ee3 100644
--- a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
@@ -14,2120 +14,897 @@
See the License for the specific language governing permissions and
limitations under the License.
////
-= Layouts
-An Appender uses a Layout to format a LogEvent into a form that meets the needs of whatever will be consuming the log event.
-In Log4j 1.x and Logback Layouts were expected to transform an event into a String.
-In Log4j 2 Layouts return a byte array.
-This allows the result of the Layout to be useful in many more types of Appenders.
-However, this means you need to configure most Layouts with a
-https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[`Charset`]
-to ensure the byte array contains correct values.
+= Layouts
-The root class for layouts that use a Charset is
-`org.apache.logging.log4j.core.layout.AbstractStringLayout` where the default is UTF-8. Each layout that extends `AbstractStringLayout` can provide its own default.
-See each layout below.
+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:
-A custom character encoder was added to Log4j 2.4.1 for the ISO-8859-1 and US-ASCII charsets, to bring some of the performance improvements built-in to Java 8 to Log4j for use on Java 7. For applications that log only ISO-8859-1 characters, specifying this charset will improve performance significantly.
+* xref:#concerns[What are some common concerns shared by all predefined layouts?]
+* xref:#collection[Which layouts does Log4j provide?]
+* xref:#extending[How can you create custom layouts?]
-[#common-concerns]
+[#concerns]
== Common concerns
+This section introduces you to some common concerns shared by almost all xref:#collection[predefined layouts] that you need to be aware of while using them.
+
+[#charset]
+=== Character encoding
+
+All xref:#collection[predefined layouts] produce `String` that eventually get converted into a `byte[]` using the https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html[`Charset`] configured.
+While doing so, unless an explicit encoding configuration is stated, they use `UTF-8` by default.
+If you want all your log events to be formatted in a certain character encoding that is different from what the employed layout defaults to, make sure to configure the layout's character encoding as needed.
+
[#LocationInformation]
=== Location information
include::partial$manual/layouts-location-information.adoc[]
-[#CSVLayouts]
-== CSV Layouts
+[#collection]
+== Collection
+
+Log4j bundles predefined layouts to assist in several common deployment use cases.
+Let's start with shortcuts to most used ones:
+
+* Are you looking for a production-grade *JSON layout ready to be deployed to a log ingestion system* such as Elasticsearch or Google Cloud?
+Refer to xref:manual/json-template-layout.adoc[].
-As of Log4j 2.11.0, CSV support has moved from the existing module
-`log4j-core` to the new module `log4j-csv`.
+* Are you looking for a layout that encodes log events in a *human-readable format suitable for tests and local development*?
+Refer to xref:manual/pattern-layout.adoc[].
-This layout creates
-https://en.wikipedia.org/wiki/Comma-separated_values[Comma Separated
-Value (CSV)] records and requires
-https://commons.apache.org/proper/commons-csv/[Apache Commons CSV] 1.4.
+Following sections explain all predefined layouts in detail.
-The CSV layout can be used in two ways: First, using
-`CsvParameterLayout` to log event parameters to create a custom database, usually to a logger and file appender uniquely configured for this purpose.
-Second, using `CsvLogEventLayout` to log events to create a database, as an alternative to using a full DBMS or using a JDBC driver that supports the CSV format.
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-Layout[📖 Plugin reference for all `Layout` implementations]
-The `CsvParameterLayout` converts an event's parameters into a CSV record, ignoring the message.
-To log CSV records, you can use the usual Logger methods `info()`, `debug()`, and so on:
+[#csv-layouts]
+=== [[CSVLayouts]] CSV Layouts
+
+There are two layouts performing https://en.wikipedia.org/wiki/Comma-separated_values[Comma Separated Value (CSV)] encoding:
+
+[#csv-layout-parameter]
+==== CSV Parameter Layout
+
+`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`]
+
+.Click here for examples
+[%collapsible]
+====
+Given the following statement
[source,java]
----
-logger.info("Ignored", value1, value2, value3);
+LOGGER.info("Record1 {} {}", "arg1", "arg2");
+LOGGER.error("Record2 {} {} {}", "arg3", "arg4", "arg5", throwable);
----
-Which will create the CSV record:
+`CsvParameterLayout` will output
-....
-value1, value2, value3
-....
+[source,text]
+----
+arg1,arg2
+arg3,arg4,arg5
+----
-Alternatively, you can use an `ObjectArrayMessage`, which only carries parameters:
+The same can be achieved using link:../javadoc/log4j-api/org/apache/logging/log4j/message/ObjectArrayMessage.html[`ObjectArrayMessage`] as follows:
[source,java]
----
-logger.info(new ObjectArrayMessage(value1, value2, value3));
+LOGGER.info(new ObjectArrayMessage("arg1", "arg2"));
+LOGGER.info(new ObjectArrayMessage("arg3", "arg4", "arg5"));
----
+====
-The layouts `CsvParameterLayout` and `CsvLogEventLayout` are configured with the following parameters:
+[#csv-layout-log-event]
+==== CSV Log Event Layout
+
+`CsvLogEventLayout` encodes the complete log event, including the formatted message.
+Generated CSV records will be composed of following fields in the given order:
+
+. Time (in nanoseconds)
+. Time (in milliseconds)
+. Level
+. Thread ID
+. Thread name
+. Thread priority
+. Message (formatted, hence including parameters)
+. Logger FQCN
+. Logger name
+. Marker
+. Throwable
+. Source
+. 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`]
+
+.Click here for examples
+[%collapsible]
+====
+Given the following statement
-.CsvParameterLayout and CsvLogEventLayout
-[cols="1m,1,4"]
+[source,java]
+----
+LOGGER.debug("one={}, two={}, three={}", 1, 2, 3);
+----
+
+`CsvLogEventLayout` will output
+
+[source,text]
+----
+0,1441617184044,DEBUG,main,"one=1, two=2, three=3",org.apache.logging.log4j.spi.AbstractLogger,,,,org.apache.logging.log4j.core.layout.CsvLogEventLayoutTest.testLayout(CsvLogEventLayoutTest.java:98),{},[]
+----
+====
+
+[#csv-layout-config]
+==== Configuration
+
+Both `CsvParameterLayout` and `CsvLogEventLayout` are configured with the following parameters:
+
+[%header,cols="1m,1m,4"]
|===
-|Parameter Name |Type |Description
+|Parameter
+|Type
+|Description
|format
|String
-|One of the predefined formats: `Default`, `Excel`,
-`MySQL`, `RFC4180`, `TDF`. See
-https://commons.apache.org/proper/commons-csv/archives/1.4/apidocs/org/apache/commons/csv/CSVFormat.Predefined.html[CSVFormat.Predefined].
+|A predefined format name (`Default`, `Excel`, `MySQL`, `RFC4180`, `TDF`, etc.) accepted by https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html[`CSVFormat`]
|delimiter
|Character
-|Sets the delimiter of the format to the specified character.
+|The field delimiter character
|escape
|Character
-|Sets the escape character of the format to the specified character.
+|The escape character
|quote
|Character
-|Sets the quoteChar of the format to the specified
-character.
+|The quote character
|quoteMode
|String
-|Sets the output quote policy of the format to the
-specified value. One of: `ALL`, `MINIMAL`, `NON_NUMERIC`, `NONE`.
+|A quote mode name (`ALL`, `ALL_NONE_NULL`, `MINIMAL`, `NON_NUMERIC`, `NONE`, etc.) accepted by https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/QuoteMode.html[`QuoteMode`]
|nullString
|String
-|Writes null as the given nullString when writing records.
+|The string to denote `null` values
|recordSeparator
|String
-|Sets the record separator of the format to the specified String.
+|The record separator string
|charset
|Charset
-|The output Charset.
+|The character encoding
|header
-|Sets the header to include when the stream is opened.
-|Desc.
+|String
+|The header to include when the stream is opened
|footer
-|Sets the footer to include when the stream is closed.
-|Desc.
+|String
+|The footer to include when the stream is closed
|===
-Logging as a CSV event looks like this:
+Additional runtime dependencies are required for using CSV layouts:
-[source,java]
+[tabs]
+====
+Maven::
++
+[source,xml,subs="+attributes"]
----
-logger.debug("one={}, two={}, three={}", 1, 2, 3);
+<dependency>
+ <groupId>org.apache.commons</groupId>
+ <artifactId>commons-csv</artifactId>
+ <version>{commons-csv-version}</version>
+ <scope>runtime</scope>
+</dependency>
----
-Produces a CSV record with the following fields:
-
-1. Time Nanos
-2. Time Millis
-3. Level
-4. Thread ID
-5. Thread Name
-6. Thread Priority
-7. Formatted Message
-8. Logger FQCN
-9. Logger Name
-10. Marker
-11. Thrown Proxy
-12. Source
-13. Context Map
-14. Context Stack
-
-....
-0,1441617184044,DEBUG,main,"one=1, two=2, three=3",org.apache.logging.log4j.spi.AbstractLogger,,,,org.apache.logging.log4j.core.layout.CsvLogEventLayoutTest.testLayout(CsvLogEventLayoutTest.java:98),{},[]
-....
-
-.Additional runtime dependencies are required for using CSV layouts
-[%collapsible,id=log4j-csv-deps]
-=====
-include::partial$manual/dependencies-log4j-csv.adoc[]
-=====
+Gradle::
++
+[source,groovy,subs="+attributes"]
+----
+runtimeOnly 'org.apache.commons:commons-csv:{commons-csv-version}'
+----
+====
[#GELFLayout]
-== GELF Layout
+=== GELF Layout
-Encodes log events in https://go2docs.graylog.org/current/getting_in_log_data/gelf.html#GELFPayloadSpecification[the GELF specification] version `1.1`.
-Compresses JSON to GZIP or ZLIB (`compressionType`) if log event data is larger than 1024 bytes (`compressionThreshold`).
+`GelfLayout` encodes log events in https://go2docs.graylog.org/current/getting_in_log_data/gelf.html#GELFPayloadSpecification[the GELF specification] version `1.1`.
+It can compress the output when it exceeds a certain threshold.
This layout does not implement chunking.
-[TIP]
+[WARNING]
====
-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 a far richer set of features.
+*This layout is planned to be removed in the next major release!*
+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.
====
-Configure as follows to send to a Graylog 2.x server with UDP:
-
-[source,xml]
-----
-<Appenders>
- <Socket name="Graylog" protocol="udp" host="graylog.domain.com" port="12201">
- <GelfLayout host="someserver" compressionType="ZLIB" compressionThreshold="1024"/>
- </Socket>
-</Appenders>
-----
-
-Configure as follows to send to a Graylog 2.x server with TCP:
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-GelfLayout[📖 Plugin reference for `GelfLayout`]
-[source,xml]
-----
-<Appenders>
- <Socket name="Graylog" protocol="tcp" host="graylog.domain.com" port="12201">
- <GelfLayout host="someserver" compressionType="OFF" includeNullDelimiter="true"/>
- </Socket>
-</Appenders>
-----
+GELF Layout is configured with the following parameters:
-[options="header"]
-|===
-| Parameter Name | Type | Description
-| host | String | The value of the `host` property (optional, defaults to local host name).
-| compressionType | `GZIP`, `ZLIB` or `OFF` | Compression to use (optional, defaults to `GZIP`).
-| compressionThreshold | int | Compress if data is larger than this number of bytes (optional, defaults to 1024).
-| includeMapMessage | boolean | Whether to include fields from MapMessages as additional fields (optional, default to true).
-| includeNullDelimiter | boolean | Whether to include NULL byte as delimiter after each event (optional, default to false). Useful for Graylog GELF TCP input. Cannot be used with compression.
-| includeStacktrace | boolean | Whether to include full stacktrace of logged Throwables (optional, default to true). If set to false, only the class name and message of the Throwable will be included.
-| includeThreadContext | boolean | Whether to include thread context as additional fields (optional, default to true).
-| mapMessageExcludes | String | A comma separated list of attributes from the MapMessage to exclude when formatting the event. This attribute only applies when includeMapMessage="true" is specified. If mapMessageIncludes are also specified this attribute will be ignored.
-| mapMessageIncludes | String | A comma separated list of attributes from the MapMessage to include when formatting the event. This attribute only applies when includeMapMessage="true" is specified. If mapMessageExcludes are also specified this attribute will override them. MapMessage fields specified here that have no value will be omitted.
-| mapPrefix | String | A String to prepend to all elements of the MapMessage when rendered as a field. Defaults to an empty String.
-| messagePattern | String | The pattern to use to format the String. A messagePattern and patternSelector cannot both be specified. If both are present the message pattern will be ignored and an error will be logged. If not supplied only the text derived from the logging message will be used. See PatternLayout for information on the pattern strings.
-| omitEmptyFields | boolean | If true fields which are null or are zero-length strings will not be included as a field in the Gelf JSON. This setting will not affect whether those fields appear in the message fields. The default value is false.
-| patternSelector | PatternSelector | The PatternSelector to use to format the String. A messagePattern and patternSelector cannot both be specified. If both are present the message pattern will be ignored and an error will be logged. If not supplied only the text derived from the logging message will be used. See PatternSelectors for information on how to specify a PatternSelector. See PatternLayout for information on the pattern strings.
-| threadContextExcludes | String | A comma separated list of ThreadContext attributes to exclude when formatting the event. This attribute only applies when includeThreadContext="true" is specified. If threadContextIncludes are also specified this attribute will be ignored.
-| threadContextIncludes | String | A comma separated list of ThreadContext attributes to include when formatting the event. This attribute only applies when includeThreadContext="true" is specified. If threadContextExcludes are also specified this attribute will override them. ThreadContext fields specified here that have no value will be omitted.
-| ThreadContextPrefix | String | A String to prepend to all elements of the ThreadContextMap when rendered as a field. Defaults to an empty String.
+[%header,cols="1m,1m,4"]
|===
+|Parameter
+|Type
+|Description
-To include any custom field in the output, use following syntax:
+|additionalFields
+|link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/KeyValuePair.html[KeyValuePair[\]]
+|link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/KeyValuePair.html[`KeyValuePair`] elements denoting additional entries.
+Entry values can contain xref:manual/lookups.adoc[] using `${` syntax.
-[source,xml]
-----
-<GelfLayout includeThreadContext="true" threadContextIncludes="loginId,requestId">
- <MessagePattern>%d %5p [%t] %c{1} %X{loginId, requestId} - %m%n</MessagePattern>
- <KeyValuePair key="additionalField1" value="constant value"/>
- <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
-</GelfLayout>
-----
-
-Custom fields are included in the order they are declared.
-The values support xref:manual/lookups.adoc[lookups].
-
-GELF Layout is garbage-free when used with `compressionType="OFF"` and as long as no additional field contains `${` (variable substitution).
-
-[#HTMLLayout]
-== HTML Layout
-
-The HtmlLayout generates an HTML page and adds each LogEvent to a row in a table.
+|compressionThreshold
+|int
+|Triggers compression if the output is larger than this number of bytes (optional, defaults to 1024)
-.HtmlLayout Parameters
-[cols="1m,1,4"]
-|===
-|Parameter Name |Type |Description
-
-|charset
+|compressionType
|String
-|The character set to use when converting the HTML
-String to a byte array. The value must be a valid
-http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
-If not specified, this layout uses UTF-8.
+|The compression to use.
+It is optional, and defaults to `GZIP`.
+Accepted values are `GZIP`, `ZLIB`, or `OFF`.
-|contentType
+|host
|String
-|The value to assign to the Content-Type header.
-The default is "text/html".
+|The value of the `host` property (optional, defaults to the local host name)
-|locationInfo
+|includeMapMessage
|boolean
-a|[[HtmlLocationInfo]]
-
-If true, the filename and line number will be included in the HTML
-output. The default value is false.
-
-Generating link:#LocationInformation[location information] is an
-expensive operation and may impact performance. Use with caution.
-
-|title
-|String
-|A String that will appear as the HTML title.
-
-|fontName
-|String
-|The `font-family` to use. The default is "arial,sans-serif".
-
-|fontSize
-|String
-|The `font size` to use. The default is "small".
-
-|datePattern
-|String
-|The date format of the logging event. The default is "JVM_ELAPSE_TIME", which outputs the milliseconds since JVM started. For other valid values, refer to the link:#PatternDate[date pattern] of PatternLayout.
-
-|timezone
-|String
-|The timezone id of the logging event. If not specified, this layout uses the https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getDefault()[java.util.TimeZone.getDefault] as the default timezone. Like link:#PatternDate[date pattern] of PatternLayout, you can use the timezone id from
-https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[java.util.TimeZone.getTimeZone].
-
-|===
-
-Configure as follows to use `dataPattern` and timezone in `HtmlLayout`:
-
-[source,xml]
-----
-<Appenders>
- <Console name="console">
- <HtmlLayout datePattern="ISO8601" timezone="GMT+0"/>
- </Console>
-</Appenders>
-----
-
-[[JSONLayout]]
-== JSON Layout
-
-[WARNING]
-====
-JSON Layout is considered deprecated.
-xref:#JSONTemplateLayout[] provides more capabilities and should be used instead.
-====
-
-Appends a series of JSON events as strings serialized as bytes.
-
-=== Complete well-formed JSON vs. fragment JSON
-
-If you configure `complete="true"`, the appender outputs a well-formed JSON document.
-By default, with `complete="false"`, you should include the output as an _external file_ in a separate file to form a well-formed JSON document.
-
-If `complete="false"`, the appender does not write the JSON open array character "[" at the start of the document, "]" at the end, nor comma "," between records.
-
-Log event follows this pattern:
-
-[source,json]
-----
-{
- "instant": {
- "epochSecond": 1493121664,
- "nanoOfSecond": 118000000
- },
- "thread": "main",
- "level": "INFO",
- "loggerName": "HelloWorld",
- "marker": {
- "name": "child",
- "parents": [
- {
- "name": "parent",
- "parents": [
- {
- "name": "grandparent"
- }
- ]
- }
- ]
- },
- "message": "Hello, world!",
- "thrown": {
- "commonElementCount": 0,
- "message": "error message",
- "name": "java.lang.RuntimeException",
- "extendedStackTrace": [
- {
- "class": "logtest.Main",
- "method": "main",
- "file": "Main.java",
- "line": 29,
- "exact": true,
- "location": "classes/",
- "version": "?"
- }
- ]
- },
- "contextStack": ["one", "two"],
- "endOfBatch": false,
- "loggerFqcn": "org.apache.logging.log4j.spi.AbstractLogger",
- "contextMap": {
- "bar": "BAR",
- "foo": "FOO"
- },
- "threadId": 1,
- "threadPriority": 5,
- "source": {
- "class": "logtest.Main",
- "method": "main",
- "file": "Main.java",
- "line": 29
- }
-}
-----
-
-=== Pretty vs. compact JSON
-
-The compact attribute determines whether the output will be "pretty" or not.
-The default value is "false", which means the appender uses end-of-line characters and indent lines to format the text.
-If `compact="true"`, then no end-of-line or indentation is used, which will cause the output to take less space.
-Of course, the message content may contain, escaped end-of-lines.
-
-[options="header"]
-|===
-| Parameter Name | Type | Description
-| charset | String | The character set to use when converting to a byte array. The value must be a valid `Charset`. If not specified, UTF-8 will be used.
-| compact | boolean | If true, the appender does not use end-of-lines and indentation. Defaults to false.
-| eventEol | boolean | If true, the appender appends an end-of-line after each record. Defaults to false. Use with eventEol=true and compact=true to get one record per line.
-| endOfLine | String | If set, overrides the default end-of-line string. E.g., set it to "\n" and use with eventEol=true and compact=true to have one record per line separated by "\n" instead of "\r\n". Defaults to null (i.e., not set).
-| complete | boolean | If true, the appender includes the JSON header and footer, and comma between records. Defaults to false.
-| properties | boolean | If true, the appender includes the thread context map in the generated JSON. Defaults to false.
-| propertiesAsList | boolean | If true, the thread context map is included as a list of map entry objects, where each entry has a "key" attribute (whose value is the key) and a "value" attribute (whose value is the value). Defaults to false, in which case the thread context map is included as a simple map of key-value pairs.
-| locationInfo | boolean | If true, the appender includes the location information in the generated JSON. Defaults to false. Generating location information is an expensive operation and may impact performance. Use with caution.
-| includeStacktrace | boolean | If true, include full stacktrace of any logged Throwable (optional, default to true).
-| includeTimeMillis | boolean | If true, the timeMillis attribute is included in the Json payload instead of the instant. timeMillis will contain the number of milliseconds since midnight, January 1, 1970 UTC.
-| stacktraceAsString | boolean | Whether to format the stacktrace as a string, and not a nested object (optional, defaults to false).
-| includeNullDelimiter | boolean | Whether to include NULL byte as delimiter after each event (optional, default to false).
-| objectMessageAsJsonObject | boolean | If true, ObjectMessage is serialized as JSON object to the "message" field of the output log. Defaults to false.
-|===
-
-To include any custom field in the output, use the following syntax:
-
-[source,xml]
-----
-<JsonLayout>
- <KeyValuePair key="additionalField1" value="constant value"/>
- <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
-</JsonLayout>
-----
-
-Custom fields are always last, in the order they are declared.
-The values support xref:manual/lookups.adoc[lookups].
-
-.Additional runtime dependencies are required for using `JsonLayout`
-[%collapsible,id=log4j-layout-json-deps]
-=====
-include::partial$manual/dependencies-log4j-layout-json.adoc[]
-=====
-
-[#JSONTemplateLayout]
-== JSON Template Layout
-
-`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON-emitting layout.
-It encodes ``LogEvent``s according to the structure described by the JSON template provided.
-For instance, given the following JSON template modelling https://github.com/logstash/log4j-jsonevent-layout[the official
-Logstash `JSONEventLayoutV1`]
-
-[source,json]
-----
-{
- "mdc": {
- "$resolver": "mdc"
- },
- "exception": {
- "exception_class": {
- "$resolver": "exception",
- "field": "className"
- },
- "exception_message": {
- "$resolver": "exception",
- "field": "message"
- },
- "stacktrace": {
- "$resolver": "exception",
- "field": "stackTrace",
- "stackTrace": {
- "stringified": true
- }
- }
- },
- "line_number": {
- "$resolver": "source",
- "field": "lineNumber"
- },
- "class": {
- "$resolver": "source",
- "field": "className"
- },
- "@version": 1,
- "source_host": "${hostName}",
- "message": {
- "$resolver": "message",
- "stringified": true
- },
- "thread_name": {
- "$resolver": "thread",
- "field": "name"
- },
- "@timestamp": {
- "$resolver": "timestamp"
- },
- "level": {
- "$resolver": "level",
- "field": "name"
- },
- "file": {
- "$resolver": "source",
- "field": "fileName"
- },
- "method": {
- "$resolver": "source",
- "field": "methodName"
- },
- "logger_name": {
- "$resolver": "logger",
- "field": "name"
- }
-}
-----
-
-in combination with the below Log4j configuration:
-
-[source,xml]
-----
-<JsonTemplateLayout eventTemplateUri="classpath:LogstashJsonEventLayoutV1.json"/>
-----
+|Whether to include fields from xref:manual/messages.adoc#MapMessage[`MapMessage`]s as additional fields (optional, defaults to `true`)
-JSON Template Layout will render JSON documents as follows:
-
-[source,json]
-----
-{
- "exception": {
- "exception_class": "java.lang.RuntimeException",
- "exception_message": "test",
- "stacktrace": "java.lang.RuntimeException: test\n\tat org.apache.logging.log4j.JsonTemplateLayoutDemo.main(JsonTemplateLayoutDemo.java:11)\n"
- },
- "line_number": 12,
- "class": "org.apache.logging.log4j.JsonTemplateLayoutDemo",
- "@version": 1,
- "source_host": "varlik",
- "message": "Hello, error!",
- "thread_name": "main",
- "@timestamp": "2017-05-25T19:56:23.370+02:00",
- "level": "ERROR",
- "file": "JsonTemplateLayoutDemo.java",
- "method": "main",
- "logger_name": "org.apache.logging.log4j.JsonTemplateLayoutDemo"
-}
-----
-
-.Additional runtime dependencies are required for using JSON Template Layout
-[%collapsible,id=log4j-layout-template-json-deps]
-=====
-include::partial$manual/dependencies-log4j-layout-template-json.adoc[]
-=====
-
-See xref:manual/json-template-layout.adoc[JSON Template Layout] page for the complete documentation.
-
-[id=pattern-layout]
-== [[PatternLayout]] Pattern Layout
-
-A flexible layout is configurable with a pattern string.
-The goal of this class is to format a LogEvent and return the results.
-The format of the result depends on the _conversion pattern_.
-
-The conversion pattern is closely related to the conversion pattern of the `printf()` function in C. A conversion pattern is composed of literal text and format control expressions called _conversion specifiers_.
-
-_Note that any literal text, including *Special Characters*, may be included in the conversion pattern._ Special Characters include *\t*,
-*\n*, *\r*, *\f*.
-Use *\\* to insert a single backslash into the output.
-
-Each conversion specifier starts with a percent sign (%) and is followed by optional _format modifiers_ and a _conversion character_.
-The conversion character specifies the type of data, e.g. category, priority, date, thread name.
-The format modifiers control such things as field width, padding, and left and right justification.
-The following is a simple example.
-
-Let the conversion pattern be *"%-5p [%t]: %m%n"* and assume that the Log4j environment was set to use a PatternLayout.
-Then the statements
-
-....
-Logger logger = LogManager.getLogger("MyLogger");
-logger.debug("Message 1");
-logger.warn("Message 2");
-....
-
-would yield the output
-
-....
-DEBUG [main]: Message 1
-WARN [main]: Message 2
-....
-
-Note that there is no explicit separator between text and conversion specifiers.
-The pattern parser knows when it has reached the end of a conversion specifier when it reads a conversion character.
-In the example above the conversion specifier `%-5p` means the priority of the logging event should be left justified to a width of five characters.
+|includeNullDelimiter
+|boolean
+|Whether to include `NULL` byte as delimiter after each event.
+Optional and defaults to `false`.
+Useful for Graylog GELF TCP input.
+Cannot be used with compression.
-If the pattern string does not contain a specifier to handle a Throwable being logged, parsing of the pattern will act as if the `%xEx` specifier had been added to the end of the string.
-To suppress the formatting of the Throwable completely simply add `%ex\{0}` as a specifier in the pattern string.
+|includeStacktrace
+|boolean
+|Whether to include full stacktrace of logged ``Throwable``s.
+Optional and defaults to `true`.
+If set to `false`, only the class name and message of the `Throwable` will be included.
-.PatternLayout Parameters
-[cols="1m,1,4"]
-|===
-|Parameter Name |Type |Description
+|includeThreadContext
+|boolean
+|Whether to include thread context as additional fields (optional, defaults to `true`)
-|charset
+|mapMessageExcludes
|String
-|The character set to use when converting the syslog
-String to a byte array. The String must be a valid
-http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
-If not specified, this layout uses the platform default character set.
+|A comma separated list of attributes from the xref:manual/messages.adoc#MapMessage[`MapMessage`] to exclude when formatting the event.
+This attribute only applies when `includeMapMessage` is `true`.
+If `mapMessageIncludes` are also specified, this attribute will be ignored.
-|pattern
+|mapMessageIncludes
|String
-|A composite pattern string of one or more conversion
-patterns from the table below. Cannot be specified with a
-PatternSelector.
-
-|patternSelector
-|PatternSelector
-|A component that analyzes information
-in the LogEvent and determines which pattern should be used to format
-the event. The pattern and patternSelector parameters are mutually
-exclusive.
-
-|replace
-|RegexReplacement
-|Allows portions of the resulting String to
-be replaced. If configured, the replace element must specify the regular
-expression to match and the substitution. This performs a function
-similar to the RegexReplacement converter but applies to the whole
-message while the converter only applies to the String its pattern
-generates.
-
-|alwaysWriteExceptions
-|boolean
-|If `true` (it is by default) exceptions
-are always written even if the pattern contains no exception
-conversions. This means that if you do not include a way to output
-exceptions in your pattern, the default exception formatter will be
-added to the end of the pattern. Setting this to `false` disables this
-behavior and allows you to exclude exceptions from your pattern output.
+|A comma separated list of attributes from the xref:manual/messages.adoc#MapMessage[`MapMessage`] to include when formatting the event.
+This attribute only applies when `includeMapMessage` is `true`.
+If `mapMessageExcludes` are also specified, this attribute will override them.
+`MapMessage` fields specified here that have no value will be omitted.
-|header
+|mapPrefix
|String
-|The optional header string to include at the top of
-each log file.
+|A string to prepend to all elements of the xref:manual/messages.adoc#MapMessage[`MapMessage`] when rendered as a field (optional, defaults to an empty string)
-|footer
+|[[GELFLayout-messagePattern]] messagePattern
|String
-|The optional footer string to include at the bottom of
-each log file.
+|The pattern to use to format the `String`.
+A `messagePattern` and xref:#GELFLayout-patternSelector[`patternSelector`] cannot both be specified.
+If both are present, the message pattern will be ignored and an error will be logged.
+If not supplied, only the text derived from the log message will be used.
+See xref:manual/pattern-layout.adoc[] for information on the pattern strings.
-|disableAnsi
+|omitEmptyFields
|boolean
-|If `true` (default is false), do not output ANSI
-escape codes.
-
-|noConsoleNoAnsi
-|boolean
-|If `true` (default is false) and
-`System.console()` is null, do not output ANSI escape codes.
-|===
-
-.RegexReplacement Parameters
-|===
-|Parameter Name |Type |Description
-
-|regex
+|If `true`, fields which are null or are zero-length strings will not be included as a field in the produced JSON.
+This setting will not affect if those fields appear in the message fields.
+The default value is `false`.
+
+|[[GELFLayout-patternSelector]] patternSelector
+|xref:manual/pattern-layout.adoc#plugin-element-PatternSelector[PatternSelector]
+|The `PatternSelector` to use to format the `String`.
+A xref:#GELFLayout-messagePattern[`messagePattern`] and `patternSelector` cannot both be specified.
+If both are present, the message pattern will be ignored and an error will be logged.
+If not supplied, only the text derived from the logging message will be used.
+See xref:manual/pattern-layout.adoc#plugin-element-PatternSelector[`PatternSelector`] for information on how to specify a `PatternSelector`.
+See xref:manual/pattern-layout.adoc[] for information on the pattern strings.
+
+|threadContextExcludes
|String
-|A Java-compliant regular expression to match the resulting string. See
-https://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[Pattern].
+|A comma separated list of xref:manual/thread-context.adoc[] map keys to exclude when formatting the event.
+This attribute only applies when `includeThreadContext` is `true`.
+If `threadContextIncludes` are also specified, this attribute will be ignored.
-|replacement
+|threadContextIncludes
|String
-|The string to replace any matched sub-strings with.
-|===
-
-[#Patterns]
-=== Patterns
-
-The conversions that are provided with Log4j are:
-
-[cols="1m,3a"]
-|===
-|Conversion Pattern |Description
-
-|*c*\{precision} +
-*logger*\{precision}
-|Outputs the name of the logger that published the logging event. The
-logger conversion specifier can be optionally followed by _precision
-specifier_, which consists of a decimal integer, or a pattern starting
-with a decimal integer.
-
-When the precision specifier is an integer value, it reduces the size of
-the logger name. If the number is positive, the layout prints the
-corresponding number of the rightmost logger name components. If negative,
-the layout removes the corresponding number of leftmost logger name
-components. If the precision contains periods then the number before the first period
-identifies the length to be printed from items that precede tokens in the rest of the pattern.
-If the number after the first period is followed by an asterisk it indicates how many of the
-rightmost tokens will be printed in full. See the table below for abbreviation examples.
-
-If the precision contains any non-integer characters, then the layout
-abbreviates the name based on the pattern. If the precision integer is
-less than one, the layout still prints the right-most token in full. By
-default, the layout prints the logger name in full.
-
-!===
-!Conversion Pattern !Logger Name !Result
-
-!%c\{1}
-!org.apache.commons.Foo
-!Foo
-
-!%c\{2}
-!org.apache.commons.Foo
-!commons.Foo
-
-!%c\{10}
-!org.apache.commons.Foo
-!org.apache.commons.Foo
-
-!%c{-1}
-!org.apache.commons.Foo
-!apache.commons.Foo
-
-!%c{-2}
-!org.apache.commons.Foo
-!commons.Foo
-
-!%c{-10}
-!org.apache.commons.Foo
-!org.apache.commons.Foo
-
-!%c{1.}
-!org.apache.commons.Foo
-!o.a.c.Foo
-
-!%c{1.1.\~.~}
-!org.apache.commons.test.Foo
-!o.a.~.~.Foo
-
-!%c{.}
-!org.apache.commons.test.Foo
-!....Foo
-
-!%c{1.1.1.*}
-!org.apache.commons.test.Foo
-!o.a.c.test.Foo
-
-!%c{1.2.*}
-!org.apache.commons.test.Foo
-!o.a.c.test.Foo
-
-!%c{1.3.*}
-!org.apache.commons.test.Foo
-!o.a.commons.test.Foo
-
-!%c{1.8.*}
-!org.apache.commons.test.Foo
-!org.apache.commons.test.Foo
-
-!===
-
-|[[PatternClass]] *C*\{precision} +
-*class*\{precision}
-|Outputs the fully qualified class name of the caller issuing the logging
-request. This conversion specifier can be optionally followed by
-_precision specifier_, that follows the same rules as the logger name
-converter.
-
-Generating the class name of the caller
-(link:#LocationInformation[location information]) is an expensive
-operation and may impact performance. Use with caution.
-
-|[[PatternDate]] *d*\{pattern} +
-*date*\{pattern}
-|Outputs the date of the logging event. The date conversion specifier may
-be followed by a set of braces containing a date and time pattern string per
-https://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
-
-The predefined _named_ formats are:
-
-[cols=",",options="header",]
-!===
-!Pattern !Example
-
-!%d\{DEFAULT}
-!2012-11-02 14:34:02,123
-
-!%d\{DEFAULT_MICROS}
-!2012-11-02 14:34:02,123456
-
-!%d\{DEFAULT_NANOS}
-!2012-11-02 14:34:02,123456789
-
-!%d\{ISO8601}
-!2012-11-02T14:34:02,781
-
-!%d\{ISO8601_BASIC}
-!20121102T143402,781
-
-!%d\{ISO8601_OFFSET_DATE_TIME_HH}
-!2012-11-02'T'14:34:02,781-07
-
-!%d\{ISO8601_OFFSET_DATE_TIME_HHMM}
-!2012-11-02'T'14:34:02,781-0700
-
-!%d\{ISO8601_OFFSET_DATE_TIME_HHCMM}
-!2012-11-02'T'14:34:02,781-07:00
-
-!%d\{ABSOLUTE}
-!14:34:02,781
-
-!%d\{ABSOLUTE_MICROS}
-!14:34:02,123456
-
-!%d\{ABSOLUTE_NANOS}
-!14:34:02,123456789
-
-!%d\{DATE}
-!02 Nov 2012 14:34:02,781
-
-!%d\{COMPACT}
-!20121102143402781
-
-!%d\{UNIX}
-!1351866842
-
-!%d\{UNIX_MILLIS}
-!1351866842781
-!===
-
-You can also use a set of braces containing a time zone id per
-https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[java.util.TimeZone.getTimeZone].
-If no date format specifier is given then the DEFAULT format is used.
-
-You can define custom date formats:
-
-[cols=",",options="header",]
-!===
-!Pattern !Example
-
-!%d{HH:mm:ss,SSS}
-!14:34:02,123
-
-!%d{HH:mm:ss,nnnn} to %d{HH:mm:ss,nnnnnnnnn}
-!14:34:02,1234 to 14:34:02,123456789
-
-!%d{dd MMM yyyy HH:mm:ss,SSS}
-!02 Nov 2012 14:34:02,123
-
-!%d{dd MMM yyyy HH:mm:ss,nnnn} to %d{dd MMM yyyy HH:mm:ss,nnnnnnnnn}
-!02 Nov 2012 14:34:02,1234 to 02 Nov 2012 14:34:02,123456789
-
-!%d{HH:mm:ss}{GMT+0}
-!18:34:02
-!===
-
-`%d\{UNIX}` outputs the UNIX time in seconds. `%d\{UNIX_MILLIS}` outputs the
-UNIX time in milliseconds. The UNIX time is the difference, in seconds
-for UNIX and milliseconds for UNIX_MILLIS, between the current time
-and midnight, January 1, 1970 UTC. While the time unit is milliseconds,
-the granularity depends on the operating system
-(http://msdn.microsoft.com/en-us/windows/hardware/gg463266.aspx[Windows]).
-This is an efficient way to output the event time because only a
-conversion from long to String takes place, there is no Date formatting
-involved.
-
-Log4j 2.11 adds limited support for timestamps more precise than
-milliseconds when running on Java 9. Note that not all
-https://docs.oracle.com/javase/9/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter]
-formats are supported. Only timestamps in the formats mentioned in the table
-above may use the "nano-of-second" pattern letter `n` instead of
-the "fraction-of-second" pattern letter `S`.
-
-Users may revert to a millisecond-precision clock when running on
-Java 9 by setting system property `log4j2.Clock` to `SystemMillisClock`.
-
-|*enc*\{pattern}{[HTML\|XML\|JSON\|CRLF]} +
-*encode*\{pattern}{[HTML\|XML\|JSON\|CRLF]}
-|Encodes and escapes special characters suitable for output in specific
-markup languages. By default, this encodes for HTML if only one option
-is specified. The second option is used to specify which encoding format
-should be used. This converter is particularly useful for encoding user-provided
-data so that the output data is not written improperly or insecurely.
-
-A typical usage would encode the message `%enc{%m}` but user input could
-come from other locations as well, such as the MDC `%enc{%mdc\{key}}`
-
-Using the HTML encoding format, the following characters are replaced:
-
-!===
-!Character !Replacement
-
-!'\r', '\n'
-!Converted into string literals "\r" and "\n" respectively
-
-!&, <, >, ", ', /
-!Replaced with the corresponding HTML entity
-!===
-
-Using the XML encoding format, this follows the escaping rules specified
-by https://www.w3.org/TR/xml/[the XML specification]:
-
-!===
-!Character !Replacement
-
-!&, <, >, ", '
-!Replaced with the corresponding XML entity
-!===
-
-Using the JSON encoding format, this follows the escaping rules
-specified by https://www.ietf.org/rfc/rfc4627.txt[RFC 4627 section 2.5]:
-
-!===
-!Character !Replacement
-
-!U+0000 - U+001F
-!\u0000 - \u001F
-
-!Any other control characters
-!Encoded into its `\uABCD` equivalent escaped code point
-
-!"
-!\"
-
-!\
-!\\
-!===
-
-For example, the pattern `{"message": "%enc{%m}\{JSON}"}` could be used
-to output a valid JSON document containing the log message as a string
-value.
-
-Using the CRLF encoding format, the following characters are replaced:
-
-!===
-!Character !Replacement
-
-!'\r', '\n'
-!Converted into literal strings "\r" and "\n" respectively
-!===
-
-|*equals*\{pattern}\{test}\{substitution} +
-*equalsIgnoreCase*\{pattern}\{test}\{substitution}
-|Replaces occurrences of 'test', a string, with its replacement
-'substitution' in the string resulting from the evaluation of the pattern.
-For example, "%equals{[%marker]}{[]}\{}" will replace '[]' strings
-produced by events without markers with an empty string.
-
-The pattern can be arbitrarily complex and in particular can contain
-multiple conversion keywords.
-
-|**ex**\|**exception**\|*throwable* +
-{ +
- [ "none" +
- \| "full" +
- \| depth +
- \| "short" +
- \| "short.className" +
- \| "short.fileName" +
- \| "short.lineNumber" +
- \| "short.methodName" +
- \| "short.message" +
- \| "short.localizedMessage"] +
-} +
- {filters(package,package,...)} +
- {suffix(_pattern_)} +
- {separator(_separator_)}
-|Outputs the Throwable trace bound to the logging event, by default this
-will output the full trace as one would normally find with a call to
-`Throwable.printStackTrace()`.
-
-You can follow the throwable conversion word with an option in the form
-`%throwable\{option}`.
-
-`%throwable\{short}` outputs the first line of the Throwable.
-
-`%throwable{short.className}` outputs the name of the class where the
-exception occurred.
-
-`%throwable{short.methodName}` outputs the method name where the
-exception occurred.
-
-`%throwable{short.fileName}` outputs the name of the class where the
-exception occurred.
-
-`%throwable{short.lineNumber}` outputs the line number where the
-exception occurred.
-
-`%throwable{short.message}` outputs the message.
-
-`%throwable{short.localizedMessage}` outputs the localized message.
-
-`%throwable\{n}` outputs the first n lines of the stack trace.
-
-Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of
-the exception.
-
-Use `{filters(packages)}` where _packages_ is a list of package names to
-suppress matching stack frames from stack traces.
-
-Use `{suffix(pattern)}` to add the output of _pattern_ at the end of
-each stack frame.
-
-Use a `{separator(...)}` as the end-of-line string. For example:
-`separator(\|)`. The default value is the `line.separator` system
-property, which is operating system dependent.
-
-|[[PatternFile]] *F* +
-*file*
-|Outputs the file name where the logging request was issued.
-
-Generating the file information (link:#LocationInformation[location
-information]) is an expensive operation and may impact performance. Use
-with caution.
-
-|*highlight*\{pattern}\{style}
-|Adds ANSI colors to the result of the enclosed pattern based on the
-current event's logging level. (See Jansi link:#enable-jansi[configuration].)
-
-The default colors for each level are:
-
-!===
-!Level !ANSI color
-
-!FATAL
-!Bright red
-
-!ERROR
-!Bright red
-
-!WARN
-!Yellow
-
-!INFO
-!Green
-
-!DEBUG
-!Cyan
-
-!TRACE
-!Black (looks dark grey)
-!===
-
-The color names are ANSI names defined in the
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`]
-class.
-
-The color and attribute names are standard, but the exact shade, hue, or value.
-
-.Color table
-!===
-!Intensity Code !0 !1 !2 !3 !4 !5 !6 !7
-
-!Normal !Black !Red !Green !Yellow !Blue !Magenta !Cyan !White
-
-!Bright !Black !Red !Green !Yellow !Blue !Magenta !Cyan !White
-!===
-
-You can use the default colors with:
-
-....
-%highlight{%d [%t] %-5level: %msg%n%throwable}
-....
-
-You can override the default colors in the optional `\{style}` option. For
-example:
-
-....
-%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
-....
-
-You can highlight only the portion of the log event:
-
-....
-%d [%t] %highlight{%-5level: %msg%n%throwable}
-....
-
-You can style one part of the message and highlight the rest of the log event:
-
-....
-%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
-....
-
-You can also use the STYLE key to use a predefined group of colors:
-
-....
-%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
-....
-
-The STYLE value can be one of:
-
-* Default: see above
-* Logback:
-!===
-!Level !ANSI color
-
-!FATAL !Blinking bright red
-
-!ERROR !Bright red
-
-!WARN !Red
-
-!INFO !Blue
-
-!DEBUG !Normal
-
-!TRACE !Normal
-!===
-
-|[[PatternMap]] *K*\{key} +
-*map*\{key} +
-*MAP*\{key}
-|Outputs the entries in a
-link:../javadoc/log4j-api/org/apache/logging/log4j/message/MapMessage.html[MapMessage],
-if one is present in the event. The `K` conversion character can be
-followed by the key for the map placed between braces, as in
-`%K\{clientNumber}` where `clientNumber` is the key. The value of the Map
-corresponding to the key will be output. If no additional sub-option
-is specified, then the entire contents of the Map key-value pair set is
-output using a format {{key1,val1},{key2,val2}}
-
-|[[PatternLocation]] *l* +
-*location*
-|Outputs location information of the caller which generates the logging event.
-
-The location information depends on the JVM implementation but it usually
-consists of the fully qualified name of the calling method followed by
-the callers source the file name and line number between parentheses.
-
-Generating link:#LocationInformation[location information] is an
-expensive operation and may impact performance. Use with caution.
-
-|[[PatternLine]] *L* +
-*line*
-|Outputs the line number from where the logging request was issued.
-
-Generating line number information (link:#LocationInformation[location
-information]) is an expensive operation and may impact performance. Use
-with caution.
-
-|[[PatternMessage]] *m*\{lookups}\{ansi} +
-*msg*\{lookups}\{ansi} +
-*message\{lookups}\{ansi}
-|Outputs the application-supplied message associated with the logging
-event.
-
-Add `\{ansi}` to render messages with ANSI escape codes (requires JAnsi,
-see link:#enable-jansi[configuration].)
-
-The default syntax for embedded ANSI codes is:
-
-....
-@\|code(,code)* text\|@
-....
-
-For example, to render the message `"Hello"` in green, use:
-
-....
-@\|green Hello\|@
-....
-
-To render the message `"Hello"` in bold and red, use:
-
-....
-@\|bold,red Warning!\|@
-....
-
-You can also define custom style names in the configuration with the
-syntax:
-
-....
-%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
-....
-
-For example:
-
-....
-%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
-....
-
-The call site can look like this:
-
-....
-logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
-....
-
-Use `\{lookups}` to log messages like `"${date:YYYY-MM-dd}"` using lookups.
-using any lookups. This will replace the date template `{date:YYYY-MM-dd}`
-with an actual date. This can be confusing in many cases, and it's often both easier and
-more obvious to handle the lookup in code.
-This feature is disabled by default and the message string is logged untouched.
-
-*Note:* Users are *STRONGLY* discouraged from using the lookups option. Doing so may allow uncontrolled user input
-containing lookups to take unintended actions. In almost all cases the software developer can accomplish the same tasks
-lookups perform directly in the application code.
-
-|[[PatternMethod]] *M* +
-*method*
-|Outputs the method name where the logging request was issued.
-
-Generating the method name of the caller
-(link:#LocationInformation[location information]) is an expensive
-operation and may impact performance. Use with caution.
-
-|[[PatternMarker]] *marker*
-|The full name of the marker, including parents, if one is present.
-
-|[[PatternMarkerSimpleName]] *markerSimpleName*
-|The simple name of the marker (not including parents), if one is present.
-
-|[[PatternMaxLength]] *maxLen* +
-*maxLength*
-|Outputs the result of evaluating the pattern and truncating the result.
-If the length is greater than 20, then the output will contain a
-trailing ellipsis. If the provided length is invalid, a default value of
-100 is used.
-
-Example syntax: `%maxLen{%p: %c\{1} - %m%notEmpty{ =>%ex\{short}}}\{160}`
-will be limited to 160 characters with a trailing ellipsis. Another
-example: `%maxLen{%m}\{20}` will be limited to 20 characters and no
-trailing ellipsis.
-
-|[[PatternNewLine]] *n*
-|Outputs the platform-dependent line separator character or characters.
-
-This conversion character offers practically the same performance as
-using non-portable line separator strings such as "\n", or "\r\n". Thus,
-it is the preferred way of specifying a line separator.
-
-|[[NanoTime]] *N* +
-*nano*
-|Outputs the result of `System.nanoTime()` at the time the log event was created.
-
-|[[Process_ID]] *pid*{[defaultValue]} +
-*processId*{[defaultValue]}
-|Outputs the process ID if supported by the
-underlying platform. An optional default value may be specified to be
-shown if the platform does not support process IDs.
-
-|[[VariablesNotEmpty]] *variablesNotEmpty*\{pattern} +
-*varsNotEmpty*\{pattern} +
-*notEmpty*\{pattern}
-|Outputs the result of evaluating the pattern if and only if all
-variables in the pattern are not empty.
-
-For example:
-
-....
-%notEmpty{[%marker]}
-....
-
-|[[PatternLevel]] **p**\|*level*{__level__=_label_, __level__=_label_,
-...} **p**\|*level*{length=_n_}
-**p**\|*level*{lowerCase=__true__\|_false_}
-|Outputs the level of the logging event. You provide a level name map in
-the form "level=value, level=value" where the level is the name of the Level
-and value is the value that should be displayed instead of the name of
-the Level.
-
-For example:
-
-....
-%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
-....
-
-Alternatively, for the compact-minded:
-
-....
-%level{WARN=W, DEBUG=D, ERROR=E, TRACE=T, INFO=I}
-....
-
-More succinctly, for the same result as above, you can define the length
-of the level label:
-
-....
-%level{length=1}
-....
-
-If the length is greater than a level name length, the layout uses the
-normal level name.
-
-You can combine the two kinds of options:
-
-....
-%level{ERROR=Error, length=2}
-....
-
-This gives you the `Error` level name and all other level names of length
-2.
-
-Finally, you can output lower-case level names (the default is upper-case):
-
-....
-%level{lowerCase=true}
-....
-
-|[[PatternRelative]] *r* +
-*relative*
-|Outputs the number of milliseconds elapsed since the JVM was
-started until the creation of the logging event.
-
-|[[PatternRepeat]] *R*\{string}\{count} +
-*repeat*\{string}\{count}
-|Produces a string containing the requested number of instances of the specified string.
-For example, "%repeat{\*}\{2}" will result in the string "**".
-
-|[[PatternReplace]] *replace*\{pattern}\{regex}\{substitution}
-|Replaces occurrences of 'regex', a regular expression, with its
-replacement 'substitution' in the string resulting from the evaluation of
-the pattern. For example, "%replace{%msg}{\s}\{}" will remove all
-spaces contained in the event message.
-
-The pattern can be arbitrarily complex and in particular, can contain
-multiple conversion keywords. For instance, "%replace{%logger
-%msg}{\.}{/}" will replace all dots in the logger or the message of
-the event with a forward slash.
-
-|[[PatternException]] **rEx**\|**rException**\|*rThrowable* +
- { +
- ["none" \| "short" \| "full" \| depth] +
- [,filters(package,package,...)] +
- [,separator(_separator_)] +
- } +
- {ansi( +
- Key=Value,Value,... +
- Key=Value,Value,... +
- ...) +
- } +
- {suffix(_pattern_)} +
-|The same as the %throwable conversion word but the stack trace is
-printed starting with the first exception that was thrown followed by
-each subsequent wrapping exception.
-
-The throwable conversion word can be followed by an option in the form
-`%rEx\{short}` which will only output the first line of the Throwable or
-`%rEx\{n}` where the first n lines of the stack trace will be printed.
-
-Specifying `%rEx\{none}` or `%rEx\{0}` will suppress printing of the
-exception.
+|A comma separated list of xref:manual/thread-context.adoc[] map keys to include when formatting the event.
+This attribute only applies when `includeThreadContext` is `true`.
+If `threadContextExcludes` are also, specified this attribute will override them.
+Thread context fields specified here that have no value will be omitted.
-Use `filters(packages)` where _packages_ is a list of package names to
-suppress matching stack frames from stack traces.
+|threadContextPrefix
+|String
+|A string to prepend to all elements of the xref:manual/thread-context.adoc[] map when rendered as a field (defaults to an empty string)
+|===
-Use a `separator` string to separate the lines of a stack trace. For
-example: `separator(\|)`. The default value is the `line.separator`
-system property, which is operating system dependent.
+GELF Layout is garbage-free if `compressionType` is `OFF` and there are no additional fields containing `${`.
-Use `rEx{suffix(pattern)` to add the output of _pattern_ to the output
-only when there is a throwable to print.
+.Example configurations
+[%collapsible]
+====
+[tabs]
+=====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/gelf-layout/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/gelf-layout/log4j2.xml[lines=26..41,indent=0]
+----
-|[[PatternSequenceNumber]] *sn* +
-*sequenceNumber*
-|Includes a sequence number that will be incremented in
-every event. The counter is a static variable so will only be unique
-within applications that share the same converter Class object.
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/gelf-layout/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/gelf-layout/log4j2.json[lines=5..48,indent=0]
+----
-|[[PatternStyle]] *style*\{pattern}{ANSI style}
-|Uses ANSI escape sequences to style the result of the enclosed pattern.
-The style can consist of a comma-separated list of style names from the
-following table. (See Jansi link:#enable-jansi[configuration].)
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/gelf-layout/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/gelf-layout/log4j2.yaml[lines=21..53,indent=0]
+----
-!===
-!Style Name !Description
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/gelf-layout/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+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
+====
-!Normal
-!Normal display
+[#HTMLLayout]
+=== HTML Layout
-!Bright
-!Bold
+`HtmlLayout` generates an HTML page, and adds each log event to a row in a table.
-!Dim
-!Dimmed or faint characters
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-HtmlLayout[📖 Plugin reference for `HtmlLayout`]
-!Underline
-!Underlined characters
+It is configured with the following parameters:
-!Blink
-!Blinking characters
+[%header,cols="1m,1m,4"]
+|===
+|Parameter
+|Type
+|Description
-!Reverse
-!Reverse video
+|charset
+|String
+|The character encoding
-!Hidden
-!
+|contentType
+|String
+|The `Content-Type` header value (defaults to `text/html`)
-!Black or FG_Black
-!Set the foreground color to black
+|datePattern
+|String
+|The date format of the log event.
+The default is `JVM_ELAPSE_TIME`, which outputs the milliseconds since JVM started.
+For other valid values, refer to xref:manual/pattern-layout.adoc#converter-date[the `date` conversion specifier of Pattern Layout].
-!Red or FG_Red
-!Set the foreground color to red
+|fontName
+|String
+|The `font-family` (defaults to `arial,sans-serif`)
-!Green or FG_Green
-!Set the foreground color to green
+|fontSize
+|String
+|The `font size` (defaults to `small`)
-!Yellow or FG_Yellow
-!Set the foreground color to yellow
+|locationInfo
+|boolean
+|If `true`, the xref:#LocationInformation[source location information] be included (defaults to `false`)
-!Blue or FG_Blue
-!Set the foreground color to blue
+|timezone
+|String
+|The time zone ID of the log event.
+If not specified, this layout uses the https://docs.oracle.com/javase/8/docs/api/java/util/TimeZone.html#getDefault()[`TimeZone.getDefault()`] as the default.
+You can use time zone IDs supported by https://docs.oracle.com/javase/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`TimeZone.getTimeZone(String)`].
-!Magenta or FG_Magenta
-!Set the foreground color to magenta
+|title
+|String
+|The HTML page title
+|===
-!Cyan or FG_Cyan
-!Set the foreground color to cyan
+[[JSONLayout]]
+=== JSON Layout
-!White or FG_White
-!Set the foreground color to white
+`JsonLayout` encodes a log event into JSON.
-!Default or FG_Default
-!Set the foreground color to default (white)
+[WARNING]
+====
+JSON Layout is considered deprecated.
+It is succeeded by xref:#JSONTemplateLayout[] providing more capabilities and efficiency.
+====
-!BG_Black
-!Set the background color to black
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-JsonLayout[📖 Plugin reference for `JsonLayout`]
-!BG_Red
-!Set the background color to red
+.Click for an example output
+[%collapsible]
+====
+[source,json]
+----
+{
+ "instant": {
+ "epochSecond": 1493121664,
+ "nanoOfSecond": 118000000
+ },
+ "thread": "main",
+ "level": "INFO",
+ "loggerName": "HelloWorld",
+ "marker": {
+ "name": "child",
+ "parents": [
+ {
+ "name": "parent",
+ "parents": [
+ {
+ "name": "grandparent"
+ }
+ ]
+ }
+ ]
+ },
+ "message": "Hello, world!",
+ "thrown": {
+ "commonElementCount": 0,
+ "message": "error message",
+ "name": "java.lang.RuntimeException",
+ "extendedStackTrace": [
+ {
+ "class": "logtest.Main",
+ "method": "main",
+ "file": "Main.java",
+ "line": 29,
+ "exact": true,
+ "location": "classes/",
+ "version": "?"
+ }
+ ]
+ },
+ "contextStack": ["one", "two"],
+ "endOfBatch": false,
+ "loggerFqcn": "org.apache.logging.log4j.spi.AbstractLogger",
+ "contextMap": {
+ "bar": "BAR",
+ "foo": "FOO"
+ },
+ "threadId": 1,
+ "threadPriority": 5,
+ "source": {
+ "class": "logtest.Main",
+ "method": "main",
+ "file": "Main.java",
+ "line": 29
+ }
+}
+----
+====
-!BG_Green
-!Set the background color to green
+JSON Layout is configured with the following parameters:
-!BG_Yellow
-!Set the background color to yellow
+[%header,cols="1m,1m,4"]
+|===
+|Parameter Name
+|Type
+|Description
-!BG_Blue
-!Set the background color to blue
+|additionalFields
+|link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/KeyValuePair.html[KeyValuePair[\]]
+|link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/KeyValuePair.html[`KeyValuePair`] elements denoting additional entries.
+Entry values can contain xref:manual/lookups.adoc[] using `${` syntax.
-!BG_Magenta
-!Set the background color to magenta
+|charset
+|String
+|The character encoding (defaults to `UTF-8`)
-!BG_Cyan
-!Set the background color to cyan
+|compact
+|boolean
+|If `true`, does not use `endOfLine` and indentation.
+This feature is also referred to as _pretty-printing_ too.
+It defaults to `false`.
-!BG_White
-!Set the background color to white
-!===
+|complete
+|boolean
+|
+If `true`, uses `header` and `footer`, and places comma between records – this leads to a well-formed JSON document given `header` and `footer` defaults to `[` and `]`, respectively.
+It defaults to `false`.
-For example:
-
-....
-%style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green}
-....
-
-You can also combine styles:
-
-....
-%d %highlight{%p} %style{%logger}{bright,cyan} %C{1.} %msg%n
-....
-
-You can also use `%` with a color like `%black`, `%blue`, `%cyan`, and
-so on. For example:
-
-....
-%black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable}
-....
-
-|[[PatternThreadId]] *T* +
-*tid* +
-*threadId*
-|Outputs the ID of the thread that generated the logging event.
-
-|[[PatternThreadName]] *t* +
-*tn* +
-*thread* +
-*threadName*
-|Outputs the name of the thread that generated the logging event.
-
-|[[PatternThreadPriority]] *tp* +
-*threadPriority*
-|Outputs the priority of the thread that generated the logging event.
-
-|[[PatternLoggerFqcn]] *fqcn*
-|Outputs the fully qualified class name of the logger.
-
-|[[EndOfBatch]] *endOfBatch*
-|Outputs the EndOfBatch status of the logging event, as "true" or "false".
-
-|[[PatternNDC]] *x* +
-*NDC*
-|Outputs the Thread Context Stack (also known as the Nested
-Diagnostic Context or NDC) associated with the thread that generated the
-logging event.
-
-|[[PatternMDC]] *X*{key[,key2...]} +
-*mdc*{key[,key2...]} +
-*MDC*{key[,key2...]}
-|Outputs the Thread Context Map (also known as the Mapped Diagnostic
-Context or MDC) associated with the thread that generated the logging
-event. The *X* conversion character can be followed by one or more keys
-for the map placed between braces, as in *%X\{clientNumber}* where
-`clientNumber` is the key. The value in the MDC corresponding to the key
-will be output.
-
-If a list of keys is provided, such as *%X{name, number}*, then each
-key that is present in the ThreadContext will be output using the format
-{name=val1, number=val2}. The key/value pairs will be printed in the
-order they appear in the list.
-
-If no sub-options are specified then the entire contents of the MDC key-value pair
-set is output using a format {key1=val1, key2=val2}.
-The key/value pairs will be printed in sorted order.
-
-See the
-link:../javadoc/log4j-api/org/apache/logging/log4j/ThreadContext.html[ThreadContext]
-class for more details.
-
-|[[PatternUUID]] *u*{"RANDOM" \| "TIME"} +
-*uuid*
-|Includes either a random or a time-based UUID. The time-based
-UUID is a Type 1 UUID that can generate up to 10,000 unique IDs per
-millisecond will use the MAC address of each host, and to try to insure
-uniqueness across multiple JVMs and/or ClassLoaders on the same host
-a random number between 0 and 16,384 will be associated with each instance
-of the UUID generator Class and included in each time-based UUID
-generated. Because time-based UUIDs contain the MAC address and
-timestamp they should be used with care as they can cause a security
-vulnerability.
-
-|[[PatternExtendedException]] **xEx**\|**xException**\|*xThrowable* +
- { +
- ["none" \| "short" \| "full" \| depth] +
- [,filters(package,package,...)] +
- [,separator(_separator_)] +
- } +
- {ansi( +
- Key=Value,Value,... +
- Key=Value,Value,... +
- ...) +
- } +
- {suffix(_pattern_)} +
-|The same as the %throwable conversion word but also includes class
-packaging information.
-
-At the end of each stack element of the exception, a string containing
-the name of the jar file that contains the class or the directory the
-class is located in and the "Implementation-Version" as found in that
-jar's manifest will be added. If the information is uncertain, then the
-class packaging data will be preceded by a tilde, i.e. the '~'
-character.
-
-The throwable conversion word can be followed by an option in the form
-`%xEx\{short}` which will only output the first line of the Throwable or
-`%xEx\{n}` where the first n lines of the stack trace will be printed.
-Specifying `%xEx\{none}` or `%xEx\{0}` will suppress printing of the
-exception.
-
-Use `filters(packages)` where _packages_ is a list of package names to
-suppress matching stack frames from stack traces.
-
-Use a `separator` string to separate the lines of a stack trace. For
-example: `separator(\|)`. The default value is the `line.separator`
-system property, which is operating system dependent.
-
-The `ansi` option renders stack traces with ANSI escape code using the
-JAnsi library. (See link:#enable-jansi[configuration].) Use `\{ansi}` to
-use the default color mapping. You can specify your mappings with
-`key=value` pairs. The keys are:
-
-* Prefix
-* Name
-* NameMessageSeparator
-* Message
-* At
-* CauseLabel
-* Text
-* More
-* Suppressed
-* StackTraceElement.ClassName
-* StackTraceElement.ClassMethodSeparator
-* StackTraceElement.MethodName
-* StackTraceElement.NativeMethod
-* StackTraceElement.FileName
-* StackTraceElement.LineNumber
-* StackTraceElement.Container
-* StackTraceElement.ContainerSeparator
-* StackTraceElement.UnknownSource
-* ExtraClassInfo.Inexact
-* ExtraClassInfo.Container
-* ExtraClassInfo.ContainerSeparator
-* ExtraClassInfo.Location
-* ExtraClassInfo.Version
-
-The values are names from JAnsi's
-https://fusesource.github.io/jansi/documentation/api/org/fusesource/jansi/AnsiRenderer.Code.html[Code]
-class like `blue`, `bg_red`, and so on (Log4j ignores case.)
-
-The special key `StyleMapName` can be set to one of the following
-predefined maps: `Spock`, `Kirk`.
-
-As with %throwable, the *%xEx{suffix(_pattern_)* conversion will add
-the output of _pattern_ to the output only if there is a throwable to
-print.
-
-|[[PatternPercentLiteral]] *%*
-|The sequence %% outputs a single percent sign.
-|===
+|endOfLine
+|String
+|If set, overrides the default end-of-line string.
+For instance, set it to `\n` and use with `eventEol=true` and `compact=true` to have one record per line separated by `\n` instead of `\r\n`.
+It is not set by default.
-By default, the relevant information is output as is.
-However, with the aid of format modifiers it is possible to change the minimum field width, the maximum field width and justification.
+|eventEol
+|boolean
+|If `true`, appends an `endOfLine` after each log event, even if `compact=true`.
+It defaults to `false`.
+Use with `eventEol=true` and `compact=true` to get one record per line.
-The optional format modifier is placed between the percent sign and the conversion character.
+|footer
+|String
+|The footer to include when the stream is closed and `complete=true` (defaults to `]`)
-The first optional format modifier is the _left justification flag_
-which is just the minus (-) character.
-Then comes the optional _minimum field width_ modifier.
-This is a decimal constant that represents the minimum number of characters to output.
-If the data item requires fewer characters, it is padded on either the left or the right until the minimum width is reached.
-The default is to pad on the left (right justify) but you can specify right padding with the left justification flag.
-The padding character is space.
-If the data item is larger than the minimum field width, the field is expanded to accommodate the data.
-The value is never truncated.
-To use zeros as the padding character prepend the _minimum field width_ with a zero.
+|header
+|String
+|The header to include when the stream is opened and `complete=true` (defaults to `[`)
-This behavior can be changed using the _maximum field width_ modifier which is designated by a period followed by a decimal constant.
-If the data item is longer than the maximum field, then the extra characters are removed from the _beginning_ of the data item and not from the end.
-For example, if the maximum field width is eight and the data item is ten characters long, then the first two characters of the data item are dropped.
-This behavior deviates from the `printf()` function in C where truncation is done from the end.
+|includeNullDelimiter
+|boolean
+|If `true`, a NULL byte will suffix each encoded log event (defaults to `false`)
-Truncation from the end is possible by appending a minus character right after the period.
-In that case, if the maximum field width is eight and the data item is ten characters long, then the last two characters of the data item are dropped.
+|includeStacktrace
+|boolean
+|If `true`, include full stacktrace of any logged `Throwable` (defaults to `true`)
-Below are various format modifier examples for the category conversion specifier.
+|includeTimeMillis
+|boolean
+|If `true`, a `timeMillis` attribute is included in the JSON payload instead of the `instant`.
+`timeMillis` will contain the number of milliseconds since 1970-01-01T00:00:00Z.
-.Pattern Converters
-|===
-|Format modifier |left justify |minimum width |maximum width |comment
-
-|%20c
-|false
-|20
-|none
-|Left pad with spaces if the category name is
-less than 20 characters long.
-
-|%-20c
-|true
-|20
-|none
-|Right pad with spaces if the category name is
-less than 20 characters long.
-
-|%.30c
-|NA
-|none
-|30
-|Truncate from the beginning if the category name is longer than 30 characters.
-
-|%20.30c
-|false
-|20
-|30
-|Left pad with spaces if the category name is
-shorter than 20 characters. However, if the category name is longer than 30
-characters, then truncate from the beginning.
-
-|%-20.30c
-|true
-|20
-|30
-|Right pad with spaces if the category name is
-shorter than 20 characters. However, if the category name is longer than 30
-characters, then truncate from the beginning.
-
-|%-20.-30c
-|true
-|20
-|30
-|Right pad with spaces if the category name is
-shorter than 20 characters. However, if the category name is longer than 30
-characters, then truncate from the end.
-|===
+|locationInfo
+|boolean
+|If `true`, the appender includes the xref:#LocationInformation[source location information] in the generated JSON (defaults to `false`)
-[#enable-jansi]
-=== ANSI Styling on Windows
+|objectMessageAsJsonObject
+|boolean
+|If `true`, xref:manual/messages.adoc#ObjectMessage[`ObjectMessage`] is serialized as JSON object to the `message` field of the output log (defaults to `false`)
-ANSI escape sequences are supported natively on many platforms but are not by default on Windows.
-To enable ANSI support add the
-http://jansi.fusesource.org/[Jansi] jar to your application and set property `log4j.skipJansi` to `false`.
-This allows Log4j to use Jansi to add ANSI escape codes when writing to the console.
+|properties
+|boolean
+|If `true`, the appender includes the xref:manual/thread-context.adoc[] map in the generated JSON (defaults to `false`)
-NOTE: Before Log4j 2.10, Jansi was enabled by default.
-The fact that Jansi requires native code means that Jansi can only be loaded by a single class loader.
-For web applications, this means the Jansi jar has to be in the web container's classpath.
-To avoid causing problems for web applications, Log4j will no longer automatically try to load Jansi without explicit configuration from Log4j 2.10 onward.
+|propertiesAsList
+|boolean
+|If `true`, the xref:manual/thread-context.adoc[] map is included as a list of map entry objects, where each entry is denoted as a JSON object containg `key` and `value` fields.
+It defaults to `false`, in which case the thread context map is included as a simple map of key-value pairs.
-=== Example Patterns
+|stacktraceAsString
+|boolean
+|If `true`, the stacktrace will be formatted as `String`, and not a nested object (optional, defaults to `false`)
+|===
-==== Filtered Throwables
+Additional runtime dependencies are required for using JSON Layout:
-This example shows how to filter out classes from unimportant packages in stack traces.
+[tabs]
+====
+Maven::
++
+[source,xml,subs="+attributes"]
+----
+<dependency>
+ <groupId>com.fasterxml.jackson.core</groupId>
+ <artifactId>jackson-databind</artifactId>
+ <version>{jackson-version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
-[source,xml]
+Gradle::
++
+[source,groovy,subs="+attributes"]
----
-<Configuration>
- <properties>
- <property name="filters">org.junit,org.apache.maven,sun.reflect,java.lang.reflect</property>
- </properties>
- <!-- ... -->
- <PatternLayout pattern="%m%xEx{filters(${filters})}%n"/>
-</Configuration>
+runtimeOnly 'com.fasterxml.jackson.core:jackson-databind:{jackson-version}'
----
+====
-The result printed to the console will appear similar to:
+[#JSONTemplateLayout]
+=== JSON Template Layout
-....
-Exception java.lang.IllegalArgumentException: IllegalArgument
-at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(ExtendedThrowableTest.java:72) [test-classes/:?]
-... suppressed 26 lines
-at $Proxy0.invoke(Unknown Source)} [?:?]
-... suppressed 3 lines
-Caused by: java.lang.NullPointerException: null pointer
-at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(ExtendedThrowableTest.java:71) ~[test-classes/:?]
-... 30 more
-....
+`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON generating layout.
+It encodes ``LogEvent``s according to the structure described by the JSON template provided.
-==== ANSI Styled
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-JsonTemplateLayout[📖 Plugin reference for `JsonTemplateLayout`]
-The log level will be highlighted according to the event's log level.
-All the content that follows the level will be bright green.
+For instance, given the following event template stored in `MyLayout.json` in your classpath:
-[source,xml]
+[source,json]
----
-<PatternLayout>
- <pattern>%d %highlight{%p} %style{%C{1.} [%t] %m}{bold,green}%n</pattern>
-</PatternLayout>
+{
+ "instant": { // <1>
+ "$resolver": "timestamp",
+ "pattern": {
+ "format": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
+ "timeZone": "UTC"
+ }
+ },
+ "someConstant": 1, // <2>
+ "message": { // <3>
+ "$resolver": "message",
+ "stringified": true
+ }
+}
----
+<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
-[#PatternSelectors]
-=== Pattern Selectors
-
-The PatternLayout can be configured with a PatternSelector to allow it to choose a pattern to use based on attributes of the log event or other factors.
-A PatternSelector will normally be configured with a defaultPattern attribute, which is used when other criteria don't match, and a set of PatternMatch elements that identify the various patterns that can be selected.
-
-[#LevelPatternSelector]
-==== LevelPatternSelector
-
-The LevelPatternSelector selects patterns based on the log level of the log event.
-If the Level in the log event is equal to (ignoring case) the name specified on the PatternMatch key attribute, then the pattern specified on that PatternMatch element will be used.
+in combination with the below layout configuration:
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.xml[`log4j2.xml`]
[source,xml]
----
-<PatternLayout>
- <MarkerPatternSelector defaultPattern="[%-5level] %c{1.} %msg%n">
- <PatternMatch key="FLOW" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
- </MarkerPatternSelector>
-</PatternLayout>
+include::example$manual/json-template-layout/usage/log4j2.xml[lines=26..26,indent=0]
----
-[#MarkerPatternSelector]
-==== MarkerPatternSelector
-
-The MarkerPatternSelector selects patterns based on the Marker included in the log event.
-If the Marker in the log event is equal to or is an ancestor of the name specified on the PatternMatch key attribute, then the pattern specified on that PatternMatch element will be used.
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/json-template-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.yaml[`log4j2.yaml`]
[source,xml]
----
-<PatternLayout>
- <MarkerPatternSelector defaultPattern="[%-5level] %c{1.} %msg%n">
- <PatternMatch key="FLOW" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
- </MarkerPatternSelector>
-</PatternLayout>
+include::example$manual/json-template-layout/usage/log4j2.yaml[lines=22..23,indent=0]
----
-[#ScriptPatternSelector]
-==== ScriptPatternSelector
-
-The ScriptPatternSelector executes a script as described in the
-xref:manual/scripts.adoc[Scripts] section of the Configuration chapter.
-The script is passed all the properties configured in the Properties section of the configuration, the StrSubstitutor used by the Configuration in the "substitutor" variables, and the log event in the "logEvent" variable, and is expected to return the value of the PatternMatch key that should be used, or null if the default pattern should be used.
-
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.properties[`log4j2.properties`]
[source,xml]
----
-<PatternLayout>
- <ScriptPatternSelector defaultPattern="[%-5level] %c{1.} %C{1.}.%M.%L %msg%n">
- <Script name="BeanShellSelector" language="bsh"><![CDATA[
- if (logEvent.getLoggerName().equals("NoLocation")) {
- return "NoLocation";
- } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
- return "Flow";
- } else {
- return null;
- }]]>
- </Script>
- <PatternMatch key="NoLocation" pattern="[%-5level] %c{1.} %msg%n"/>
- <PatternMatch key="Flow" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
- </ScriptPatternSelector>
-</PatternLayout>
+include::example$manual/json-template-layout/usage/log4j2.properties[lines=19..20,indent=0]
----
+====
-[#PatternLayout-gcfree]
-=== Garbage-free configuration
-
-PatternLayout with the following limited set of conversion patterns is
-garbage-free. Format modifiers to control such things as field width,
-padding, left and right justification will not generate garbage.
-
-[cols="1m,2"]
-|===
-|Conversion Pattern |Description
-
-|%c\{precision}, %logger\{precision}
-|Logger name
-
-|%d, %date
-a|
-Note: Only the predefined date formats are garbage-free: (millisecond
-separator may be either a comma ',' or a period '.')
-
-[cols="1m,1"]
-!===
-!Pattern !Example
-
-!%d\{DEFAULT}
-!2012-11-02 14:34:02,781
-
-!%d\{ISO8601}
-!2012-11-02T14:34:02,781
-
-!%d\{ISO8601_BASIC}
-!20121102T143402,781
-
-!%d\{ABSOLUTE}
-!14:34:02,781
-
-!%d\{DATE}
-!02 Nov 2012 14:34:02,781
-
-!%d\{COMPACT}
-!20121102143402781
-
-!%d{HH:mm:ss,SSS}
-!14:34:02,781
-
-!%d{dd MMM yyyy HH:mm:ss,SSS}
-!02 Nov 2012 14:34:02,781
-
-!%d{HH:mm:ss}{GMT+0}
-!18:34:02
-
-!%d\{UNIX}
-!1351866842
-
-!%d\{UNIX_MILLIS}
-!1351866842781
-!===
-
-|%enc\{pattern}, %encode\{pattern}
-|Encodes special characters such as
-'\n' and HTML characters to help prevent log forging and some XSS
-attacks that could occur when displaying logs in a web browser -
-garbage-free since 2.8
-
-|%equals\{pattern}\{test}\{substitution},
-%equalsIgnoreCase\{pattern}\{test}\{substitution}
-|Replaces occurrences
-of 'test', a string, with its replacement 'substitution' in the string
-resulting from evaluation of the pattern - garbage-free since 2.8
-
-|%highlight\{pattern}\{style}
-|Adds ANSI colors - garbage-free since 2.7
-(unless nested pattern is not garbage free)
-
-|%K\{key}, %map\{key}, %MAP\{key}
-|Outputs the entries in a
-link:../javadoc/log4j-api/org/apache/logging/log4j/message/MapMessage.html[MapMessage],
-if one is present in the event - garbage-free since 2.8.
-
-|%m, %msg, %message
-|Log message (garbage-free unless message text
-contains '${')
-
-|%marker
-|The full name of the marker (including parents) - garbage-free
-since 2.8
-
-|%markerSimpleName
-|The simple name of the marker (not including
-parents)
-
-|%maxLen, %maxLength
-|Truncates another pattern to some max number of
-characters - garbage-free since 2.8
+JSON Template Layout generates JSON as follows:
-|%n
-|The platform dependent line separator
+[source,json]
+----
+{"instant":"2017-05-25T19:56:23.370Z","someConstant":1,"message":"Hello, error!"} //<1>
+----
+<1> JSON pretty-printing is not supported for performance reasons.
-|%N, %nano
-|System.nanoTime() when the event was logged
+Good news is JSON Template Layout is perfectly production-ready without any configuration!
+It bundles several predefined event templates modeling popular JSON-based log formats.
-|%notEmpty\{pattern}, %varsNotEmpty\{pattern},
-%variablesNotEmpty\{pattern}
-|Outputs the result of evaluating the
-pattern if and only if all variables in the pattern are not empty -
-garbage-free since 2.8
+Read more on xref:manual/json-template-layout.adoc[]...
-|%p, %level
-|The level of the logging event
+[id=pattern-layout]
+=== [[PatternLayout]] Pattern Layout
-|%r, %relative
-|The number of milliseconds elapsed since the JVM was
-started until the creation of the logging event - garbage-free since 2.8
+`PatternLayout` is a customizable, efficient, garbage-free, and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
-|%sn, %sequenceNumber
-|A sequence number that will be incremented in
-every event - garbage-free since 2.8
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
-|%style\{pattern}{ANSI style}
-|Style the message - garbage-free since
-2.7 (unless nested pattern is not garbage free)
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-PatternLayout[📖 Plugin reference for `PatternLayout`]
-|%T, %tid, %threadId
-|The ID of the thread that generated the logging
-event
+A conversion pattern is composed of literal text and format control expressions.
+For instance, given the `%-5p [%t]: %m%n` pattern, following statements
-|%t, %tn, %thread, %threadName
-|The name of the thread that generated
-the logging event
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
-|%tp
-|The priority of the thread that generated the logging event
+will yield the output
-|%X{key[,key2...]}, %mdc{key[,key2...]}, %MDC{key[,key2...]}
-|Outputs
-the Thread Context Map (also known as the Mapped Diagnostic Context or
-MDC) associated with the thread that generated the logging event -
-garbage-free since 2.8
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
-|literal text
-|Garbage-free unless literal contains '${' (variable
-substitution)
-|===
+Read more on xref:manual/pattern-layout.adoc[]...
-Other PatternLayout conversion patterns, and other Layouts may be
-updated to avoid creating temporary objects in future releases. (Patches
-welcome!)
+[#RFC5424Layout]
+=== RFC 5424 Layout
-NOTE: Logging exceptions and stack traces will create temporary
-objects with any layout. (However, Layouts will only create these
-temporary objects when an exception actually occurs.) We haven't figured
-out a way to log exceptions and stack traces without creating temporary
-objects. That is unfortunate, but you probably still want to log them
-when they happen.
+`Rfc5424` Layout encodes log events according to https://datatracker.ietf.org/doc/html/rfc5424#section-6[the Syslog message format described in RFC 5424].
[NOTE]
====
-patterns containing regular expressions and lookups for property
-substitution will result in temporary objects being created during
-steady-state logging.
-
-Including location information is done by walking the stacktrace of an
-exception, which creates temporary objects, so the following patterns
-are not garbage-free:
-
-* %C, %class - Class Name
-* %F, %file - File Location
-* %l, %location - Location
-* %L, %line - Line Location
-* %M, %method - Method Location
-
-Also, the pattern converters for formatting Throwables are not
-garbage-free:
-
-* %ex, %exception, %throwable - The Throwable trace bound to the
-LoggingEvent
-* %rEx, %rException %rThrowable - Same as %ex but with wrapping
-exceptions
-* %xEx, %xException, %xThrowable - Same as %ex but with class packaging
-information
-* %u, %uuid - Creates a new random or time-based UUID while formatting
+RFC 5424 obsoletes RFC 3164, implemented by xref:#SyslogLayout[].
====
-[#PatternLayout-performance]
-=== Performance
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-Rfc5424Layout[📖 Plugin reference for `Rfc5424Layout`]
-Great effort has been put into the efficiency of Pattern Layout.
-To get the most out of it, mind the following checklist:
+RFC 5424 Layout is configured with the following parameters:
-* Enable xref:manual/garbagefree.adoc[garbage-free logging]
-* Mind xref:#PatternLayout-gcfree[the garbage footprint of features you use]
-* Don't give too much slack to xref:manual/systemproperties.adoc#log4j2.layoutStringBuilderMaxSize[`log4j2
-.layoutStringBuilderMaxSize`] and try to keep it relatively tight
-
-[#RFC5424Layout]
-== RFC5424 Layout
-
-As the name implies, the Rfc5424Layout formats LogEvents by http://tools.ietf.org/html/rfc5424[RFC 5424], the enhanced Syslog specification.
-Although the specification is primarily directed at sending messages via Syslog, this format is quite useful for other purposes since items are passed in the message as self-describing key/value pairs.
-
-.Rfc5424Layout Parameters
-[cols="1m,1,4"]
+[%header,cols="1m,1m,4"]
|===
-|Parameter Name |Type |Description
+|Parameter
+|Type
+|Description
|appName
|String
-|The value to use as the APP-NAME in the RFC 5424
-syslog record.
+|The `APP-NAME` field as described in RFC 5424
|charset
|String
-|The character set to use when converting the syslog
-String to a byte array. The String must be valid
-http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
-If not specified, the default system Charset will be used.
+|The character encoding (defaults to `UTF-8`)
|enterpriseNumber
|integer
-|The IANA enterprise number as described in
-http://tools.ietf.org/html/rfc5424#section-7.2.2[RFC 5424]
+|
+The `enterpriseId` parameter as described in RFC 5424.
+If missing, `32473` will be used, which is https://www.rfc-editor.org/rfc/rfc5612.html#section-2[reserved for documentation use].
|exceptionPattern
|String
-|One of the conversion specifiers from
-PatternLayout that defines which ThrowablePatternConverter to use to
-format exceptions. Any of the options that are valid for those
-specifiers may be included. The default is to not include the Throwable
-from the event, if any, in the output.
+|An xref:manual/pattern-layout.adoc#converter-exception[`exception` conversion specifier of Pattern Layout].
+The default is to not include the `Throwable` from the event, if any, in the output.
|facility
|String
-|The facility is used to try to classify the message.
-The facility option must be set to one of "KERN", "USER", "MAIL",
-"DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV",
-"FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2",
-"LOCAL3", "LOCAL4", "LOCAL5", "LOCAL6", or "LOCAL7". These values may be
-specified as upper or lowercase characters.
-
-|format
-|String
-|If set to "RFC5424" the data will be formatted by RFC 5424.
-Otherwise, it will be formatted as a BSD
-Syslog record. Note that although BSD Syslog records are required to be
-1024 bytes or shorter the SyslogLayout does not truncate them. The
-RFC5424Layout also does not truncate records since the receiver must
-accept records of up to 2048 bytes and may accept longer records.
+|The name of link:../javadoc/log4j-core/org/apache/logging/log4j/core/net/Facility.html[`Facility`] as described in RFC 5424.
+The matching is case-insensitive.
+It defaults to `LOCAL0`.
|id
|String
-|The default structured data-id to use when formatting
-according to RFC 5424. If the LogEvent contains a StructuredDataMessage
-the id from the Message will be used instead of this value.
+|The default _Structured Data ID_ to use when formatting according to RFC 5424.
+If the log event contains a xref:manual/messages.adoc#StructuredDataMessage[`StructuredDataMessage`], the ID from that message will be used instead.
|includeMDC
|boolean
-|Indicates whether data from the ThreadContextMap
-will be included in the RFC 5424 Syslog record. Defaults to true.
+|Indicates whether data from the xref:manual/thread-context.adoc[] map will be included in the RFC 5424 Syslog record (defaults to `true`)
|loggerFields
-|List of KeyValuePairs
-|Allows arbitrary PatternLayout
-patterns to be included as specified ThreadContext fields; no default
-specified. To use, include a <LoggerFields> nested element, containing
-one or more <KeyValuePair> elements. Each <KeyValuePair> must have a key
-attribute, which specifies the key name which will be used to identify
-the field within the MDC Structured Data element, and a value attribute,
-which specifies the PatternLayout pattern to use as the value.
+|link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/KeyValuePair.html[KeyValuePair[\]]
+|Allows arbitrary xref:manual/thread-context.adoc[] map entries.
+To use, include a `LoggerFields` nested element, containing one or more `KeyValuePair` elements.
+Each `KeyValuePair` must have `key` and `value` attributes associating them with a thread context map entry.
+The `value` attribute can be an arbitrary xref:manual/pattern-layout.adoc[] pattern.
|mdcExcludes
|String
-|A comma-separated list of mdc keys that should be
-excluded from the LogEvent. This is mutually exclusive with the
-mdcIncludes attribute. This attribute only applies to RFC 5424 syslog
-records.
+|A comma-separated list of xref:manual/thread-context.adoc[] map (aka, MDC) keys that should be excluded.
+This is mutually exclusive with `mdcIncludes`.
+This attribute only applies to RFC 5424 Syslog records.
|mdcIncludes
|String
-|A comma-separated list of mdc keys that should be
-included in the FlumeEvent. Any keys in the MDC not found in the list
-will be excluded. This option is mutually exclusive with the mdcExcludes
-attribute. This attribute only applies to RFC 5424 syslog records.
+|A comma-separated list of xref:manual/thread-context.adoc[] map (aka, MDC) keys that should be included.
+Any keys in the thread context map not found in the list will be excluded.
+This option is mutually exclusive with `mdcExcludes`.
+This attribute only applies to RFC 5424 Syslog records.
-|mdcRequired
+|mdcId
|String
-|A comma-separated list of mdc keys that must be
-present in the MDC. If a key is not present a LoggingException will be
-thrown. This attribute only applies to RFC 5424 syslog records.
+|The ID to use for the xref:manual/thread-context.adoc[] map (aka, MDC) Structured Data Element.
+It defaults to `mdc`.
+This attribute only applies to RFC 5424 Syslog records.
|mdcPrefix
|String
-|A string that should be prepended to each MDC key to distinguish it from event attributes.
-The default string is "mdc:". This attribute only applies to RFC 5424 syslog records.
+|A string to be prepended to each xref:manual/thread-context.adoc[] map (aka, MDC) key to distinguish it from event attributes.
+It defaults to `mdc:`.
+This attribute only applies to RFC 5424 Syslog records.
-|mdcId
+|mdcRequired
|String
-|A required MDC ID. This attribute only applies to RFC 5424 syslog records.
+|A comma-separated list of xref:manual/thread-context.adoc[] map (aka, MDC) keys that must be present.
+If a key is not present, a link:../javadoc/log4j-core/org/apache/logging/log4j/LoggingException.html[`LoggingException`] will be thrown.
+This attribute only applies to RFC 5424 Syslog records.
|messageId
|String
-|The default value to be used in the MSGID field of RFC 5424 syslog records.
+|The default value to be used in the `MSGID` field of RFC 5424 Syslog records
|newLine
|boolean
-|If true, a newline will be appended to the end of the syslog record. The default is false.
+|If `true`, a `\n` character will be appended to the end of the Syslog record (defaults to `false`)
|newLineEscape
|String
-|String that should be used to replace newlines within the message text.
+|The string that should be used to replace newlines within the message text
|===
[#SerializedLayout]
-== Serialized Layout
+=== Serialized Layout
+
+`SerializedLayout` encodes a log event using https://docs.oracle.com/javase/8/docs/platform/serialization/spec/protocol.html[Java Serialization].
+It accepts no configuration parameters.
-The SerializedLayout simply serializes the LogEvent into a byte array using Java Serialization.
-The SerializedLayout accepts no parameters.
+[WARNING]
+====
+This layout has been deprecated since version `2.9`.
+Java Serialization has inherent security weaknesses.
+*Serialized Layout users are strongly advised to migrate to another layout!*
+====
-This layout has been deprecated since version 2.9. Java Serialization has inherent security weaknesses, using this layout is no longer recommended.
+ xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-SerializedLayout[📖 Plugin reference for `SerializedLayout`]
[#SyslogLayout]
-== Syslog Layout
+=== Syslog Layout
+
+`SyslogLayout` encodes log events according to https://datatracker.ietf.org/doc/html/rfc3164#section-4.1[the syslog message format described in RFC 3164].
+This matches the same format used by {logging-services-url}/log4j/1.x[Log4j 1].
-The SyslogLayout formats the LogEvent as BSD Syslog records matching the the same format used by Log4j 1.2.
+[IMPORTANT]
+====
+RFC 3164, implemented by Syslog Layout, is obsoleted by RFC 5424, implemented by xref:#RFC5424Layout[].
+====
+
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-SyslogLayout[📖 Plugin reference for `SyslogLayout`]
+
+Syslog Layout is configured with the following parameters:
-.SyslogLayout Parameters
-[cols="1m,1,4"]
+[%header,cols="1m,1m,4"]
|===
-|Parameter Name |Type |Description
+|Parameter
+|Type
+|Description
|charset
|String
-|The character set to use when converting the syslog
-String to a byte array. The String must be a valid
-http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
-If not specified, this layout uses UTF-8.
+|The character encoding (defaults to `UTF-8`)
|facility
|String
-|The facility is used to try to classify the message.
-The facility option must be set to one of "KERN", "USER", "MAIL",
-"DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV",
-"FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2",
-"LOCAL3", "LOCAL4", "LOCAL5", "LOCAL6", or "LOCAL7". These values may be
-specified as upper or lowercase characters.
+|The name of link:../javadoc/log4j-core/org/apache/logging/log4j/core/net/Facility.html[`Facility`] as described in RFC 5424.
+The matching is case-insensitive.
+It defaults to `LOCAL0`.
|newLine
|boolean
-|If true, a newline will be appended to the end of the
-syslog record. The default is false.
+|If `true`, a `\n` character will be appended to the end of the Syslog record (defaults to `false`)
|newLineEscape
|String
-|String that should be used to replace newlines
-within the message text.
+|The string that should be used to replace newlines within the message text
|===
[[XMLLayout]]
-== XML Layout
+=== XML Layout
-=== Complete well-formed XML vs. fragment XML
+`XmlLayout` encodes a log event into XML.
-If you configure `complete="true"`, the appender outputs a well-formed XML document where the default namespace is the Log4j namespace `https://logging.apache.org/log4j/2.0/events`.
-By default, with `complete="false"`, you should include the output as an _external entity_ in a separate file to form a well-formed XML document, in which case the appender uses `namespacePrefix` with a default of `log4j`.
+[WARNING]
+====
+*This layout is planned to be removed in the next major release!*
+XML Layout users are strongly advised to migrate to another layout!
+====
-A well-formed XML document follows this pattern:
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-XmlLayout[📖 Plugin reference for `XmlLayout`]
+.Click for an example output
+[%collapsible]
+====
[source,xml]
----
<Event xmlns="https://logging.apache.org/log4j/2.0/events"
@@ -2176,60 +953,57 @@ A well-formed XML document follows this pattern:
</Thrown>
</Event>
----
+====
-If `complete="false"`, the appender does not write the XML processing instruction and the root element.
-
-=== Marker
-
-Markers are represented by a `Marker` element within the `Event` element.
-The `Marker` element appears only when a marker is used in the log message.
-The name of the marker's parent will be provided in the `parent` attribute of the `Marker` element.
-
-=== Pretty vs. compact XML
+XML Layout configuration is identical to the one of xref:#JSONLayout[], with following exceptions:
-By default, the XML layout is not compact (a.k.a. not "pretty") with `compact="false"`, which means the appender uses end-of-line characters and indent lines to format the XML.
-If `compact="true"`, then no end-of-line or indentation is used.
-Message content may contain, of course, end-of-lines.
+* The `header` and `footer` parameters are discarded
+* If `complete=true`, each log event will be encoded into a well-formed XML document, such that:
+** `<?xml version...` preamble will be added
+** The root `<event` element will be enriched with `namespace="http://logging.apache.org/log4j/2.0/events"` attribute
-[options="header"]
-|===
-| Parameter Name | Type | Description
-| charset | String | The character set to use when converting to a byte array. The value must be a valid `Charset`. If not specified, UTF-8 will be used.
-| compact | boolean | If true, the appender does not use end-of-lines and indentation. Defaults to false.
-| complete | boolean | If true, the appender includes the XML header and footer. Defaults to false.
-| properties | boolean | If true, the appender includes the thread context map in the generated XML. Defaults to false.
-| locationInfo | boolean | If true, the appender includes the location information in the generated XML. Defaults to false. Generating location information is an expensive operation and may impact performance. Use with caution.
-| includeStacktrace | boolean | If true, include full stacktrace of any logged Throwable (optional, default to true).
-| stacktraceAsString | boolean | Whether to format the stacktrace as a string, and not a nested object (optional, defaults to false).
-| includeNullDelimiter | boolean | Whether to include NULL byte as delimiter after each event (optional, default to false).
-|===
+Additional runtime dependencies are required for using XML Layout:
-To include any custom field in the output, use the following syntax:
+[tabs]
+====
+Maven::
++
+[source,xml,subs="+attributes"]
+----
+<dependency>
+ <groupId>com.fasterxml.jackson.dataformat</groupId>
+ <artifactId>jackson-dataformat-xml</artifactId>
+ <version>{jackson-version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
-[source,xml]
+Gradle::
++
+[source,groovy,subs="+attributes"]
----
-<XmlLayout>
- <KeyValuePair key="additionalField1" value="constant value"/>
- <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
-</XmlLayout>
+runtimeOnly 'com.fasterxml.jackson.dataformat:jackson-dataformat-xml:{jackson-version}'
----
+====
-Custom fields are always last, in the order they are declared.
-The values support xref:manual/lookups.adoc[lookups].
+[[YamlLayout]]
+=== YAML Layout
-.Additional runtime dependencies are required for using `XmlLayout`
-[%collapsible,id=log4j-layout-xml-deps]
-=====
-include::partial$manual/dependencies-log4j-layout-xml.adoc[]
-=====
+`YamlLayout` encodes a log event into YAML.
-[[YamlLayout]]
-== YAML Layout
+[WARNING]
+====
+This layout is planned to be removed in the next major release!
-Appends a series of YAML events as strings serialized as bytes.
+YAML is a superset of JSON.
+*We strongly advise existing YAML Layout users to migrate to xref:#JSONTemplateLayout[]* providing more capabilities and efficiency.
+====
-A YAML log event follows this pattern:
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-YamlLayout[📖 Plugin reference for `YamlLayout`]
+.Click for an example output
+[%collapsible]
+====
[source,yaml]
----
instant:
@@ -2273,33 +1047,60 @@ source:
file: "Main.java"
line: 29
----
+====
-[options="header"]
-|===
-| Parameter Name | Type | Description
-| charset | String | The character set to use when converting to a byte array. The value must be a valid `Charset`. If not specified, UTF-8 will be used.
-| properties | boolean | If true, the appender includes the thread context map in the generated YAML. Defaults to false.
-| locationInfo | boolean | If true, the appender includes the location information in the generated YAML. Defaults to false. Generating location information is an expensive operation and may impact performance. Use with caution.
-| includeStacktrace | boolean | If true, include full stacktrace of any logged Throwable (optional, default to true).
-| stacktraceAsString | boolean | Whether to format the stacktrace as a string, and not a nested object (optional, defaults to false).
-| includeNullDelimiter | boolean | Whether to include NULL byte as delimiter after each event (optional, default to false).
-|===
+YAML Layout configuration is identical to the one of xref:#JSONLayout[], with following exceptions:
-To include any custom field in the output, use the following syntax:
+* The `header` defaults to an empty string
+* The `footer` defaults to an empty string
-[source,xml]
+Additional runtime dependencies are required for using XML Layout:
+
+[tabs]
+====
+Maven::
++
+[source,xml,subs="+attributes"]
+----
+<dependency>
+ <groupId>com.fasterxml.jackson.dataformat</groupId>
+ <artifactId>jackson-dataformat-yaml</artifactId>
+ <version>{jackson-version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
----
-<YamlLayout>
- <KeyValuePair key="additionalField1" value="constant value"/>
- <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
-</YamlLayout>
+runtimeOnly 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:{jackson-version}'
----
+====
-Custom fields are always last, in the order they are declared.
-The values support xref:manual/lookups.adoc[lookups].
+[#extending]
+== Extending
-.Additional runtime dependencies are required for using `YamlLayout`
-[%collapsible,id=log4j-layout-yaml-deps]
-=====
-include::partial$manual/dependencies-log4j-layout-yaml.adoc[]
-=====
+Layouts are xref:manual/plugins.adoc[plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/Layout.html[the `Layout` interface].
+This section will guide you on how to create custom ones.
+
+[NOTE]
+====
+While xref:#collection[the predefined layout collection] should address most common use cases, you might find yourself needing to implement a custom one.
+If this is the case, we really appreciate it if you can *share your use case in a {logging-services-url}/support.html[user support channel]*.
+====
+
+[#extending-plugins]
+=== Plugin preliminaries
+
+include::partial$manual/plugin-preliminaries.adoc[]
+
+[#extending-layouts]
+=== Extending layouts
+
+Layouts are xref:manual/plugins.adoc[plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/Layout.html[the `Layout` interface].
+If your layout is a `String`-based one, we recommend you to extend your plugin class from link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/AbstractStringLayout.html[`AbstractStringLayout`], which contains convenience for some of the boilerplate code shared by `String`-based layouts.
+You can check out following files for examples:
+
+* {project-github-url}/log4j-core/src/main/java/org/apache/logging/log4j/core/layout/SyslogLayout.java[`SyslogLayout.java`] – simple, single-file, extending from `AbstractStringLayout`
+* {project-github-url}/log4j-layout-template-json/src/main/java/org/apache/logging/log4j/layout/template/json/JsonTemplateLayout.java[`JsonTemplateLayout.java`] – advanced, using plugins for composing several of its features, contains _recycler_ concept for xref:manual/garbagefree.adoc[garbage-free] operation, extends from link:../javadoc/log4j-core/org/apache/logging/log4j/core/StringLayout.html[`StringLayout`]
diff --git a/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc b/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc
new file mode 100644
index 0000000000..97c7433800
--- /dev/null
+++ b/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc
@@ -0,0 +1,1739 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+`PatternLayout` is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, and is followed by optional *format modifiers* and a *conversion character*.
+The conversion character specifies the type of data, e.g., category, priority, date, thread name.
+The format modifiers control such things as field width, padding, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+There is no explicit separator between text and conversion specifiers.
+The pattern parser knows when it has reached the end of a conversion specifier when it reads a conversion character.
+In the example above the conversion specifier `%-5p` means the priority of the log event should be left justified to a width of five characters.
+
+If the pattern string does not contain a specifier to handle a `Throwable` being logged, parsing of the pattern will act as if the `%xEx` specifier had been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-PatternLayout[📖 Plugin reference for `PatternLayout`]
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[WARNING]
+====
+If the provided pattern does not contain an exception converter and <<plugin-attr-alwaysWriteExceptions>> is not disabled, an implicit xref:#converter-exception-extended[`%xEX`] is appended to the pattern.
+====
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`RegexReplacement`]
+|===
+
+Allows portions of the resulting `String` to be replaced.
+If configured, the `replace` element must specify the regular expression to match and the substitution.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true` and the user-provided pattern does not contain an exception converter, an implicit xref:#converter-exception-extended[`%xEX`] pattern is appended.
+This means that if you do not include a way to output exceptions in your pattern, the default exception formatter will be added to the end of the pattern.
+Setting this to `false` disables this behavior and allows you to exclude exceptions from your pattern output.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-replace[the `replace` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`PatternSelector`] to allow it to choose a pattern to use based on attributes of the log event or other factors.
+A `PatternSelector` will normally be configured with a `defaultPattern` attribute, which is used when other criteria don't match, and a set of link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[marker] included in the log event.
+If the marker in the log event is equal to or is an ancestor of the name specified on the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+
+The predefined set of pattern converters will be shared in the following sections.
+While doing so, their syntax will be documented in a certain notation.
+Consider the following example for the syntax of xref:#converter-date[] pattern converter:
+
+[source,text]
+----
+%d{dateSpecifier}[{timezone}]
+----
+
+This means that
+
+* `%d` identifies the associated pattern converter
+* `\{dateSpecifier}` indicates that the converter accepts a *required* `dateSpecifier` parameter
+* `[\{timezone}]` indicates that the converter accepts an *optional* `timezone` parameter
+
+If you want to have `%d\{something}` literal in your pattern without matching for the actual `%d` pattern converter, you can escape the `%` as follows: `%%d\{something}`.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+The date conversion specifier may be followed by a set of braces containing a date and time pattern string per https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%d\{DEFAULT}
+|2012-11-02 14:34:02,123
+
+|%d\{DEFAULT_MICROS}
+|2012-11-02 14:34:02,123456
+
+|%d\{DEFAULT_NANOS}
+|2012-11-02 14:34:02,123456789
+
+|%d\{ISO8601}
+|2012-11-02T14:34:02,781
+
+|%d\{ISO8601_BASIC}
+|20121102T143402,781
+
+|%d\{ISO8601_OFFSET_DATE_TIME_HH}
+|2012-11-02'T'14:34:02,781-07
+
+|%d\{ISO8601_OFFSET_DATE_TIME_HHMM}
+|2012-11-02'T'14:34:02,781-0700
+
+|%d\{ISO8601_OFFSET_DATE_TIME_HHCMM}
+|2012-11-02'T'14:34:02,781-07:00
+
+|%d\{ABSOLUTE}
+|14:34:02,781
+
+|%d\{ABSOLUTE_MICROS}
+|14:34:02,123456
+
+|%d\{ABSOLUTE_NANOS}
+|14:34:02,123456789
+
+|%d\{DATE}
+|02 Nov 2012 14:34:02,781
+
+|%d\{COMPACT}
+|20121102143402781
+
+|%d\{UNIX}
+|1351866842
+
+|%d\{UNIX_MILLIS}
+|1351866842781
+|===
+
+You can also use a set of braces containing a time zone id per https://docs.oracle.com/javase/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%d{HH:mm:ss,SSS}
+|14:34:02,123
+
+|%d{HH:mm:ss,nnnn} to %d{HH:mm:ss,nnnnnnnnn}
+|14:34:02,1234 to 14:34:02,123456789
+
+|%d{dd MMM yyyy HH:mm:ss,SSS}
+|02 Nov 2012 14:34:02,123
+
+|%d{dd MMM yyyy HH:mm:ss,nnnn} to %d{dd MMM yyyy HH:mm:ss,nnnnnnnnn}
+|02 Nov 2012 14:34:02,1234 to 02 Nov 2012 14:34:02,123456789
+
+|%d{HH:mm:ss}{GMT+0}
+|18:34:02
+|===
+
+`%d\{UNIX}` outputs the UNIX time in seconds.
+`%d\{UNIX_MILLIS}` outputs the UNIX time in milliseconds.
+The `UNIX` time is the difference – in seconds for `UNIX` and in milliseconds for `UNIX_MILLIS` – between the current time and 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all https://docs.oracle.com/javase/9/docs/api/java/time/format/DateTimeFormatter.html[`DateTimeFormatter`] formats are supported.
+Only timestamps in the formats mentioned in the table above may use the _nano-of-second_ pattern letter `n` instead of the _fraction-of-second_ pattern letter `S`.
+
+Users may revert to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\r` and `\n`, respectively
+
+|`&<>"'/`
+|Replaced with the corresponding HTML entity
+|===
+
+Using the XML encoding format, this follows the escaping rules specified by https://www.w3.org/TR/xml/[the XML specification]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|The corresponding XML entity
+|===
+
+Using the JSON encoding format, this follows the escaping rules specified by https://www.ietf.org/rfc/rfc4627.txt[RFC 4627 section 2.5]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution}
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+ex|exception|throwable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The `style` parameter is a comma-separated list of the following directives:
+
+.Style parameter syntax
+[cols="1m,2"]
+|===
+| Directive | Description
+
+| <level>=<style_expression>
+| Formats all messages matching level `<level>` using the style provided by `<style_expression>`.
+See <<ansi-modifiers>> for the syntax of `<style_expression>`.
+
+| STYLE=default
+| Sets the default style, which is equivalent to the following sequence of directives:
+`FATAL=bold red, ERROR=bold red, WARN=yellow, INFO=green, DEBUG=cyan, TRACE=black`.
+
+| STYLE=logback
+| Applies the style used by
+https://logback.qos.ch/manual/layouts.html#coloring[Logback's `%highlight` converter],
+which is equivalent to the following sequence of directives:
+`FATAL=blink bold red, ERROR=bold red, WARN=red, INFO=blue, DEBUG=normal, TRACE=normal`.
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=magenta}
+----
+
+You can highlight only a portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=logback}
+----
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%level{WARN=W, DEBUG=D, ERROR=E, TRACE=T, INFO=I}
+----
+
+More succinctly, for the same result as above, you can define the length of the level label:
+
+[source,text]
+----
+%level{length=1}
+----
+
+If the length is greater than a level name length, the layout uses the normal level name.
+
+You can combine the two kinds of options:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* When the precision specifier is an integer value, it reduces the size of the logger name.
+If the number is positive, the layout prints the corresponding number of the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* If the precision contains any non-integer characters, then the layout abbreviates the name based on the pattern.
+If the precision integer is less than one, the layout still prints the right-most token in full.
+
+See the table below for abbreviation examples:
+
+[%header,cols="1m,3m,3m"]
+|===
+|Pattern
+|Logger name
+|Output
+
+|%c\{1}
+|org.apache.commons.Foo
+|Foo
+
+|%c\{2}
+|org.apache.commons.Foo
+|commons.Foo
+
+|%c\{10}
+|org.apache.commons.Foo
+|org.apache.commons.Foo
+
+|%c{-1}
+|org.apache.commons.Foo
+|apache.commons.Foo
+
+|%c{-2}
+|org.apache.commons.Foo
+|commons.Foo
+
+|%c{-10}
+|org.apache.commons.Foo
+|org.apache.commons.Foo
+
+|%c{1.}
+|org.apache.commons.Foo
+|o.a.c.Foo
+
+|%c{1.1.\~.~}
+|org.apache.commons.test.Foo
+|o.a.~.~.Foo
+
+|%c{.}
+|org.apache.commons.test.Foo
+|....Foo
+
+|%c{1.1.1.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.2.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.3.*}
+|org.apache.commons.test.Foo
+|o.a.commons.test.Foo
+
+|%c{1.8.*}
+|org.apache.commons.test.Foo
+|org.apache.commons.test.Foo
+|===
+
+[#converter-marker]
+==== Marker
+
+Outputs the marker, if one is present
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerPatternConverter.html[`MarkerPatternConverter`] and .link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerSimpleNamePatternConverter.html[`MarkerSimpleNamePatternConverter`] specifiers' grammar
+[source,text]
+----
+marker
+markerSimpleName
+----
+
+`marker` outputs the full name of the marker, including its parents.
+Whereas, `markerSimpleName` outputs the simple name of the marker without its parents.
+
+[#converter-map]
+==== Map
+
+Outputs the entries in a xref:manual/messages.adoc#MapMessage[`MapMessage`], if one is present in the event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MapPatternConverter.html[`MapPatternConverter`] specifier grammar
+[source,text]
+----
+K{key}
+map{key}
+MAP{key}
+----
+
+The `K` conversion character can be followed by the key for the map placed between braces, as in `%K\{clientNumber}`, where `clientNumber` is the key.
+The value of the map corresponding to the key will be output.
+If no additional sub-option is specified, then all map entries are output using a `{{key1,val1},{key2,val2}}` format.
+
+[#converter-max-len]
+==== Max. length
+
+Outputs the result of evaluating the given pattern and truncating the result
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MaxLegthConverter.html[`MaxLengthConverter`] specifier grammar
+[source,text]
+----
+maxLen{pattern}{length}
+maxLength{pattern}{length}
+----
+
+If the length is greater than 20, then the output will contain a trailing ellipsis.
+If the provided length is invalid, a default value of 100 is used.
+
+For instance, `%maxLen{%p: %c\{1} - %m%notEmpty{ =>%ex\{short}}}\{160}` will be limited to 160 characters with a trailing ellipsis.
+`%maxLen{%m}\{20}` will be limited to 20 characters and no trailing ellipsis.
+
+[#converter-message]
+==== Message
+
+Outputs the message associated with the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MessagePatternConverter.html[`MessagePatternConverter`] specifier grammar
+[source,text]
+----
+m{lookups}{ansi}
+msg{lookups}{ansi}
+message{lookups}{ansi}
+----
+
+Add `\{ansi}` to render messages with ANSI escape codes.
+Windows users should refer to xref:#jansi[].
+
+The default syntax for embedded ANSI codes is:
+
+[source,text]
+----
+@\|code(,code)* text\|@
+----
+
+For example, to render the message `Hello` in green, use:
+
+[source,text]
+----
+@\|green Hello\|@
+----
+
+To render the message `Hello` in bold and red, use:
+
+[source,text]
+----
+@\|bold,red Warning!\|@
+----
+
+You can also define custom style names in the configuration with the syntax:
+
+[source,text]
+----
+%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
+----
+
+For example:
+
+[source,text]
+----
+%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
+----
+
+The call site can look like this:
+
+[source,text]
+----
+logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
+----
+
+[#converter-method]
+==== Method
+
+Outputs the method name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MethodLocationPatternConverter.html[`MethodLocationPatternConverter`] specifier grammar
+[source,text]
+----
+M
+method
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the method name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-nano]
+==== Nanoseconds
+
+Outputs the result of `System.nanoTime()` at the time the log event was created
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NanoTimePatternConverter.html[`NanoTimePatternConverter`] specifier grammar
+[source,text]
+----
+N
+nano
+----
+
+[#converter-not-empty]
+==== Not empty
+
+Outputs the result of evaluating the pattern, if and only if all variables in the pattern are not empty
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/VariablesNotEmptyReplacementConverter.html[`VariablesNotEmptyReplacementConverter`] specifier grammar
+[source,text]
+----
+variablesNotEmpty{pattern}
+varsNotEmpty{pattern}
+notEmpty{pattern}
+----
+
+For example:
+
+[source,text]
+----
+%notEmpty{[%marker]}
+----
+
+[#converter-pid]
+==== Process ID
+
+Outputs the process ID, if supported by the underlying platform
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ProcessIdPatternConverter.html[`ProcessIdPatternConverter`] specifier grammar
+[source,text]
+----
+pid{defaultValue}
+processId{defaultValue}
+----
+
+An optional `defaultValue` may be specified to be shown, if the platform does not support process IDs.
+
+[#converter-relative]
+==== Relative
+
+Outputs the number of milliseconds elapsed since the JVM was started until the creation of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RelativeTimePatternConverter.html[`RelativeTimePatternConverter`] specifier grammar
+[source,text]
+----
+r
+relative
+----
+
+[#converter-repeat]
+==== Repeat
+
+Produces a string containing the requested number of instances of the specified string
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RepeatPatternConverter.html[`RepeatPatternConverter`] specifier grammar
+[source,text]
+----
+R{string}{count}
+repeat{string}{count}
+----
+
+For example, `%repeat{\*}\{2}` will result in the string `**`.
+
+[#converter-replace]
+==== Replace
+
+Replaces occurrences of a regular expression (`regex`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RegexReplacementConverter.html[`RegexReplacementConverter`] specifier grammar
+[source,text]
+----
+replace{pattern}{regex}{substitution}
+----
+
+For example, `%replace{%msg}{\s}{}` will remove all spaces contained in the event message.
+
+The pattern can be arbitrarily complex and in particular, can contain multiple conversion keywords.
+For instance, `%replace{%logger %msg}{\.}{/}` will replace all dots in the logger or the message of the event with a forward slash.
+
+[#converter-rootException]
+==== Root exception
+
+The same as xref:#converter-exception[the `exception` converter], but the stack trace is printed starting with the first exception in the causal chain that was thrown followed by each subsequent wrapping exception
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.html[`RootThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+rEx|rException|rThrowable
+ {
+ ["none" | "short" | "full" | depth]
+ [,filters(package,package,...)]
+ [,separator(separator)]
+ }
+ {ansi(
+ Key=Value,Value,...
+ Key=Value,Value,...
+ ...)
+ }
+ {suffix(pattern)}
+----
+
+The throwable conversion specifier can be followed by an option in the form `%rEx\{short}`, which will only output the first line of the `Throwable`, or `%rEx\{n}`, where the first `n` lines of the stack trace will be printed.
+
+Specifying `%rEx\{none}` or `%rEx\{0}` will suppress printing of the exception.
+
+Use `filters(packages)`, where `packages` is a list of package names to suppress matching stack frames from stack traces.
+
+Use a `separator` string to separate the lines of a stack trace, e.g., `separator(|)`.
+The default value is the `line.separator` system property, which is platform dependent.
+
+Use `rEx{suffix(pattern)}` to add the output of `pattern` to the output only when there is a `Throwable` to print.
+
+[#converter-seq]
+==== Sequence number
+
+Includes a sequence number that will be incremented in every event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/SequenceNumberPatternConverter.html[`SequenceNumberPatternConverter`] specifier grammar
+[source,text]
+----
+sn
+sequenceNumber
+----
+
+The counter is a static variable, so will only be unique within applications that share the same converter class object.
+
+[#converter-style]
+==== Style
+
+Use ANSI escape sequences to style the result of the enclosed pattern.
+The syntax of the `style_expression` parameter is described in <<ansi-modifiers>>.
+Windows users should also refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/StyleConverter.html[`StyleConverter`] specifier grammar
+[source,text]
+----
+style{pattern}{style_expression}
+----
+
+For example:
+
+[source,text]
+----
+%style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green}
+----
+
+You can also combine styles:
+
+[source,text]
+----
+%d %highlight{%p} %style{%logger}{bold cyan} %C{1.} %msg%n
+----
+
+You can also use `%` with a color like `%black`, `%blue`, `%cyan`, and so on.
+For example:
+
+[source,text]
+----
+%black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable}
+----
+
+[#converter-thread-context-stack]
+==== Thread context stack
+
+Outputs the xref:manual/thread-context.adoc[] stack (aka. Nested Diagnostic Context or NDC) associated with the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NdcPatternConverter.html[`NdcPatternConverter`] specifiers grammar
+[source,text]
+----
+x
+NDC
+----
+
+[#converter-thread-context-map]
+==== Thread context map
+
+Outputs the xref:manual/thread-context.adoc[] map (aka. Mapped Diagnostic Context or MDC) associated with the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MdcPatternConverter.html[`MdcPatternConverter`] specifiers grammar
+[source,text]
+----
+X{key[,key2...]}
+mdc{key[,key2...]}
+MDC{key[,key2...]}
+----
+
+The *X* conversion character can be followed by one or more keys for the map placed between braces, as in `%X\{clientNumber}`, where `clientNumber` is the key.
+The value in the MDC corresponding to the key will be output.
+
+If a list of keys is provided, such as `%X{name, number}`, then each key that is present in the thread context will be output using the format `{name=val1, number=val2}`.
+The key/value pairs will be printed in the order they appear in the list.
+
+If no sub-options are specified then the entire contents of the MDC key-value pair set is output using a format `{key1=val1, key2=val2}`.
+The key/value pairs will be printed in sorted order.
+
+[#converter-thread-id]
+==== Thread ID
+
+Outputs the ID of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadIdPatternConverter.html[`ThreadIdPatternConverter`] specifiers grammar
+[source,text]
+----
+T
+tid
+threadId
+----
+
+[#converter-thread-name]
+==== Thread name
+
+Outputs the name of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadNamePatternConverter.html[`ThreadNamePatternConverter`] specifier grammar
+[source,text]
+----
+t
+tn
+thread
+threadName
+----
+
+[#converter-thread-priority]
+==== Thread priority
+
+Outputs the priority of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadPriorityPatternConverter.html[`ThreadPriorityPatternConverter`] specifier grammar
+[source,text]
+----
+tp
+threadPriority
+----
+
+[#converter-uuid]
+==== UUID
+
+Includes either a random or a time-based UUID
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/UuidConverter.html[`UuidConverter`] specifier grammar
+[source,text]
+----
+u{RANDOM|TIME}
+uuid{RANDOM|TIME}
+----
+
+The time-based UUID is a Type 1 UUID generated using the MAC address of each host
+To ensure uniqueness across multiple JVMs and/or class loaders on the same host, a random number between 0 and 16,384 will be associated with each instance of the UUID generator class, and included in each time-based UUID generated.
+See also xref:manual/systemproperties.adoc#log4j2.uuidSequence[`log4j2.uuidSequence`].
+Because time-based UUIDs contain the MAC address and timestamp, they should be used with care.
+
+[#format-modifiers]
+=== Format modifiers
+
+By default, the relevant information is output as is.
+However, with the aid of format modifiers it is possible to change the minimum field width, the maximum field width, and justification.
+
+The optional format modifier is placed between the percent sign and the conversion character.
+
+The first optional format modifier is the _left justification flag_ which is just the `-` (minus) character.
+Then comes the optional _minimum field width_ modifier.
+This is a decimal constant that represents the minimum number of characters to output.
+If the data item requires fewer characters, it is padded on either the left or the right until the minimum width is reached.
+The default is to pad on the left (right justify), but you can specify right padding with the left justification flag.
+The padding character is space.
+If the data item is larger than the minimum field width, the field is expanded to accommodate the data.
+The value is never truncated.
+To use zeros as the padding character prepend the _minimum field width_ with a zero.
+
+This behavior can be changed using the _maximum field width_ modifier which is designated by a period followed by a decimal constant.
+If the data item is longer than the maximum field, then the extra characters are removed from the _beginning_ of the data item and not from the end.
+For example, if the maximum field width is eight and the data item is ten characters long, then the first two characters of the data item are dropped.
+This behavior deviates from the `String#format()`, where truncation is done from the end.
+
+Truncation from the end is possible by appending a minus character right after the period.
+In that case, if the maximum field width is eight and the data item is ten characters long, then the last two characters of the data item are dropped.
+
+Below are various format modifier examples for the category conversion specifier.
+
+[%header,cols="1m,1m,1m,1m,5"]
+|===
+|Pattern
+|Left justify
+|Min. width
+|Max. width
+|Comment
+
+|%20c
+|false
+|20
+|none
+|Left pad with spaces if the category name is
+less than 20 characters long.
+
+|%-20c
+|true
+|20
+|none
+|Right pad with spaces if the category name is
+less than 20 characters long.
+
+|%.30c
+|N/A
+|none
+|30
+|Truncate from the beginning if the category name is longer than 30 characters.
+
+|%20.30c
+|false
+|20
+|30
+|Left pad with spaces if the category name is
+shorter than 20 characters. However, if the category name is longer than 30
+characters, then truncate from the beginning.
+
+|%-20.30c
+|true
+|20
+|30
+|Right pad with spaces if the category name is
+shorter than 20 characters. However, if the category name is longer than 30
+characters, then truncate from the beginning.
+
+|%-20.-30c
+|true
+|20
+|30
+|Right pad with spaces if the category name is
+shorter than 20 characters. However, if the category name is longer than 30
+characters, then truncate from the end.
+|===
+
+[#ansi-modifiers]
+=== Style modifiers
+
+Pattern Layout supports styling your text using a variety of ANSI escape sequence, which can be used through the xref:#converter-highlight[`%highlight`] and xref:#converter-style[`%style`] pattern converters.
+
+The generic syntax of a style expression is a space-separated list of:
+
+* constants from the
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`] class
+* or expressions of the form `#rrggbb` or `BG_#rrggbb`, were `r`, `g` and `b` are hexadecimal digits
+
+In EBNF form the syntax of a style expression is:
+
+[source,bnf]
+----
+<style_expression> ::= <style_expression> ( " " <style_expression> )*
+<style_modifier> ::= "#" <hex> <hex> <hex> <hex> <hex> <hex>
+ | "bg_#" <hex> <hex> <hex> <hex> <hex> <hex>
+ | <keyword>
+<hex> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7"
+ | "8" | "9" | "a" | "b" | "c" | "d" | "e" | "f"
+<keyword> ::= "normal" | "bold" | "dim" | "underline"
+ | "blink" | "reverse" | "hidden"
+ | "black" | "bg_black" | "bright_black" | "bg_bright_black"
+ | "red" | "bg_red" | "bright_red" | "bg_bright_red"
+ | "green" | "bg_green" | "bright_green" | "bg_bright_green"
+ | "yellow" | "bg_yellow" | "bright_yellow" | "bg_bright_yellow"
+ | "blue" | "bg_blue" | "bright_blue" | "bg_bright_blue"
+ | "magenta" | "bg_magenta" | "bright_magenta" | "bg_bright_magenta"
+ | "cyan" | "bg_cyan" | "bright_cyan" | "bg_bright_cyan"
+ | "white" | "bg_white" | "bright_white" | "bg_bright_white"
+----
+
+For example, you can use `underline blue bg_bright_yellow` to specify a blue underlined text on a bright yellow background.
+
+The style specifiers have the following effects (see https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters[Select Graphic Rendition] for details):
+
+`normal`:: Reverts all parameters to their default value
+`bold`:: Increases the font weight or the color intensity
+`dim`:: Decreases the fond weight or the color intensity
+`underline`:: Underlines the text on some terminals
+`blink`:: Causes the text to blink
+`reverse`:: Swaps foreground and background colors
+`hidden`:: Hides the text
+
+[#text-colors]
+==== Colors
+
+The color of the text or the background can be specified with the following style modifiers:
+
+.Color table (8 or 16 color terminals)
+[%header,cols="1m,1m,1"]
+|===
+| Text color
+| Background color
+| Visual
+
+3+h| {set:cellbgcolor:white}
+8 color terminals
+
+|
+black
+| bg_black
+| {set:cellbgcolor:black}
+
+| {set:cellbgcolor:white}
+red
+| bg_red
+| {set:cellbgcolor:maroon}
+
+| {set:cellbgcolor:white}
+green
+| bg_green
+| {set:cellbgcolor:green}
+
+| {set:cellbgcolor:white}
+yellow
+| bg_yellow
+| {set:cellbgcolor:olive}
+
+| {set:cellbgcolor:white}
+blue
+| bg_blue
+| {set:cellbgcolor:navy}
+
+| {set:cellbgcolor:white}
+magenta
+| bg_magenta
+| {set:cellbgcolor:purple}
+
+| {set:cellbgcolor:white}
+cyan
+| bg_cyan
+| {set:cellbgcolor:teal}
+
+| {set:cellbgcolor:white}
+white
+| bg_white
+| {set:cellbgcolor:silver}
+
+3+h| {set:cellbgcolor:white}
+16 color terminals
+
+|
+bright_black
+| bg_bright_black
+| {set:cellbgcolor:gray}
+
+| {set:cellbgcolor:white}
+bright_red
+| bg_bright_red
+| {set:cellbgcolor:red}
+
+| {set:cellbgcolor:white}
+bright_green
+| bg_bright_green
+|{set:cellbgcolor:lime}
+
+| {set:cellbgcolor:white}
+bright_yellow
+| bg_bright_yellow
+|{set:cellbgcolor:yellow}
+
+| {set:cellbgcolor:white}
+bright_blue
+| bg_bright_blue
+|{set:cellbgcolor:blue}
+
+| {set:cellbgcolor:white}
+bright_magenta
+| bg_bright_magenta
+|{set:cellbgcolor:fuchsia}
+
+| {set:cellbgcolor:white}
+bright_cyan
+| bg_bright_cyan
+|{set:cellbgcolor:cyan}
+
+| {set:cellbgcolor:white}
+bright_white
+| bg_bright_white
+|{set:cellbgcolor:white}
+|===
+
+If your terminal supports 24-bit colors, you can specify:
+
+* the text color using the `#rrggbb` syntax, e.g. `#dc143c` will color your text crimson,
+* the background color using the `bg_#rrggbb` syntax, e.g. `bg_#87ceeb` will use a sky blue background.
+
+[#jansi]
+==== ANSI styling on Windows
+
+ANSI escape sequences are supported natively on many platforms, but not by default on Windows.
+To enable ANSI support add the http://jansi.fusesource.org/[Jansi] dependency to your application, and set xref:manual/systemproperties.adoc#log4j2.skipJansi[the `log4j2.skipJansi` system property] to `false`.
+This allows Log4j to use Jansi to add ANSI escape codes when writing to the console.
+
+[NOTE]
+====
+Before Log4j 2.10, Jansi was enabled by default.
+The fact that Jansi requires native code means that Jansi can only be loaded by a single class loader.
+For web applications, this means the Jansi jar has to be in the web container's classpath.
+To avoid causing problems for web applications, Log4j no longer automatically tries to load Jansi without explicit configuration from Log4j 2.10 onward.
+====
+
+[#garbage-free]
+=== Garbage-free configuration
+
+Pattern Layout with the following limited set of conversion patterns is garbage-free.
+Format modifiers to control such things as field width, padding, left, and right justification will not generate garbage.
+
+[%header,cols="2m,2"]
+|===
+|Pattern
+|Comment
+
+|xref:#converter-logger[%c\{precision} +
+%logger\{precision}]
+|
+
+|xref:#converter-date[%d +
+%date]
+|Only the predefined date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free
+
+|xref:#converter-encode[%enc\{pattern} +
+%encode\{pattern}]
+|
+
+|xref:#converter-equals[%equals\{pattern}\{test}\{substitution} +
+%equalsIgnoreCase\{pattern}\{test}\{substitution}]
+|
+
+|xref:#converter-highlight[%highlight\{pattern}\{style}]
+|Granted nested pattern is garbage-free
+
+|xref:#converter-map[%K\{key} +
+%map\{key} +
+%MAP\{key}]
+|
+
+|xref:#converter-message[%m +
+%msg +
+%message]
+|
+
+|xref:#converter-marker[%marker]
+|
+
+|xref:#converter-marker[%markerSimpleName]
+|
+
+|xref:#converter-max-len[%maxLen +
+%maxLength]
+|
+
+|%n
+|
+
+|xref:#converter-nano[%N +
+%nano]
+|
+
+|xref:#converter-not-empty[%notEmpty\{pattern} +
+%varsNotEmpty\{pattern} +
+%variablesNotEmpty\{pattern}]
+|
+
+|xref:#converter-level[%p +
+%level]
+|
+
+|xref:#converter-relative[%r +
+%relative]
+|
+
+|xref:#converter-seq[%sn +
+%sequenceNumber]
+|
+
+|xref:#converter-style[%style\{pattern}{ANSI style}]
+|
+
+|xref:#converter-thread-id[%T +
+%tid +
+%threadId]
+|
+
+|xref:#converter-thread-name[%t +
+%tn +
+%thread +
+%threadName]
+|
+
+|xref:#converter-thread-priority[%tp]
+|
+
+|xref:#converter-thread-context-map[%X{key[,key2...\]} +
+%mdc{key[,key2...\]} +
+%MDC{key[,key2...\]}]
+|
+
+|literal text
+a|Garbage-free, but care is needed for xref:manual/lookups.adoc[].
+include::partial$manual/layouts-gcfree-lookup.adoc[]
+|===
+
+Patterns containing regular expressions and xref:manual/layouts.adoc#LocationInformation[location information] are not garbage-free.
+
+[#extending]
+== Extending
+
+Pattern Layout relies on xref:manual/plugins.adoc[the Log4j plugin system] to compose the features it provides.
+This makes it possible for users to extend the plugin-based feature set as they see fit.
+As of this moment, only xref:#extending-converters[extending pattern converters] is supported.
+Following sections cover how to extend these in detail.
+
+[NOTE]
+====
+While existing features should address most common use cases, you might find yourself needing to implement a custom one.
+If this is the case, we really appreciate it if you can *share your use case in a {logging-services-url}/support.html[user support channel]*.
+====
+
+[#extending-plugins]
+=== Plugin preliminaries
+
+include::partial$manual/plugin-preliminaries.adoc[]
+
+[#extending-converters]
+=== Pattern converters
+
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+You can leverage this mechanism to introduce your custom pattern converters next to xref:#converters[the predefined ones].
+
+A `PatternConverter` must first declare itself as a xref:manual/plugins.adoc[plugin] using the standard `@Plugin` annotation, and the `@Namespace` annotation with the value `Converter`.
+Furthermore, the converter must also specify the `@ConverterKeys` annotation to define the conversion specifiers, which will preceded by a `%` character when used in a pattern.
+
+[IMPORTANT]
+====
+Unlike most other plugins, **pattern converters do not use a `@PluginFactory`**.
+Instead, each converter is required to provide a static `newInstance(String[])` factory method.
+The `String[]` argument denots the the values that are specified within the curly braces that following the conversion specifier.
+====
+
+Refer to following sources for simple examples:
+
+* {project-github-url}/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.java[`EndOfBatchPatternConverter.java`]
+* {project-github-url}/log4j-core/src/main/java/org/apache/logging/log4j/core/pattern/UuidPatternConverter.java[`UuidPatternConverter.java`]
+
+[#performance]
+== Performance
+
+Great effort has been put into the efficiency of Pattern Layout.
+To get the most out of it, mind the following checklist:
+
+* Enable xref:manual/garbagefree.adoc[garbage-free logging]
+* Mind xref:#garbage-free[the garbage footprint of features you use]
+* Don't give too much slack to xref:manual/systemproperties.adoc#log4j2.layoutStringBuilderMaxSize[`log4j2.layoutStringBuilderMaxSize`] and try to keep it relatively tight
diff --git a/src/site/antora/modules/ROOT/pages/manual/performance.adoc b/src/site/antora/modules/ROOT/pages/manual/performance.adoc
index c9234574d5..e3777fc56f 100644
--- a/src/site/antora/modules/ROOT/pages/manual/performance.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/performance.adoc
@@ -134,7 +134,7 @@ xref:manual/json-template-layout.adoc#performance[JSON Template Layout]::
It encodes log events into JSON according to the structure described by the template provided.
Its output can safely be ingested into several log storage solutions: Elasticsearch, Google Cloud Logging, Graylog, Logstash, etc.
-xref:manual/layouts.adoc#PatternLayout-performance[Pattern Layout]::
+xref:manual/pattern-layout.adoc#performance[Pattern Layout]::
It encodes log events into human-readable text according to the pattern provided.
[#async]
diff --git a/src/site/antora/modules/ROOT/pages/manual/plugins.adoc b/src/site/antora/modules/ROOT/pages/manual/plugins.adoc
index 5d9a613673..c793d404c4 100644
--- a/src/site/antora/modules/ROOT/pages/manual/plugins.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/plugins.adoc
@@ -78,15 +78,6 @@ Plugin factory fields and parameters can be automatically validated at runtime u
* ValidHost: This annotation validates that a value corresponds to a valid hostname. This uses the same validation as InetAddress::getByName.
* ValidPort: This annotation validates that a value corresponds to a valid port number between 0 and 65535.
-[#converters]
-== Converters
-
-Converters are used by PatternLayout to render the elements identified by the conversion pattern. Every converter must specify its category as "Converter" on the @Plugin annotation, have a static newInstance method that accepts an array of Strings as its only parameter and returns an instance of the Converter, and must have a @ConverterKeys annotation present that contains the array of converter patterns that will cause the Converter to be selected. Converters that are meant to handle Lo [...]
-
-A second type of Converter is the FileConverter - which must have "FileConverter" specified in the category attribute of the @Plugin annotation. While similar to a LogEventPatternConverter, instead of a single format method these Converters will have two variations; one that takes an Object and one that takes an array of Objects instead of the LogEvent. Both append to the provided StringBuilder in the same fashion as a LogEventPatternConverter. These Converters are typically used by the [...]
-
-If multiple Converters specify the same ConverterKeys, then the load order above determines which one will be used. For example, to override the %date converter which is provided by the built-in DatePatternConverter class, you would need to place your plugin in a JAR file in the CLASSPATH ahead oflog4j-core.jar. This is not recommended; pattern ConverterKeys collisions will cause a warning to be emitted. Try to use unique ConverterKeys for your custom pattern converters.
-
[#key-providers]
== Key providers
diff --git a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-json.adoc b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-json.adoc
deleted file mode 100644
index cbda221184..0000000000
--- a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-json.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-////
- 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.
-////
-
-[tabs]
-====
-Maven::
-+
-[source,xml,subs="+attributes"]
-----
-<dependency>
- <groupId>com.fasterxml.jackson.core</groupId>
- <artifactId>jackson-databind</artifactId>
- <version>{jackson-version}</version>
- <scope>runtime</scope>
-</dependency>
-----
-
-Gradle::
-+
-[source,groovy,subs="+attributes"]
-----
-runtimeOnly 'com.fasterxml.jackson.core:jackson-databind:{jackson-version}'
-----
-====
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-template-json.adoc b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-template-json.adoc
deleted file mode 100644
index 644d2c5115..0000000000
--- a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-template-json.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-////
- 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.
-////
-
-[tabs]
-====
-Maven::
-+
-[source,xml,subs="+attributes"]
-----
-<dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-layout-template-json</artifactId>
- <version>{log4j-layout-template-json-version}</version>
- <scope>runtime</scope>
-</dependency>
-----
-
-Gradle::
-+
-[source,groovy,subs="+attributes"]
-----
-runtimeOnly 'org.apache.logging.log4j:log4j-layout-template-json:{log4j-layout-template-json-version}'
-----
-====
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-xml.adoc b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-xml.adoc
deleted file mode 100644
index 50007bccfb..0000000000
--- a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-xml.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-////
- 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.
-////
-
-[tabs]
-====
-Maven::
-+
-[source,xml,subs="+attributes"]
-----
-<dependency>
- <groupId>com.fasterxml.jackson.dataformat</groupId>
- <artifactId>jackson-dataformat-xml</artifactId>
- <version>{jackson-version}</version>
- <scope>runtime</scope>
-</dependency>
-----
-
-Gradle::
-+
-[source,groovy,subs="+attributes"]
-----
-runtimeOnly 'com.fasterxml.jackson.dataformat:jackson-dataformat-xml:{jackson-version}'
-----
-====
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-yaml.adoc b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-yaml.adoc
deleted file mode 100644
index 1459a1a9b2..0000000000
--- a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-yaml.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-////
- 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.
-////
-
-[tabs]
-====
-Maven::
-+
-[source,xml,subs="+attributes"]
-----
-<dependency>
- <groupId>com.fasterxml.jackson.dataformat</groupId>
- <artifactId>jackson-dataformat-yaml</artifactId>
- <version>{jackson-version}</version>
- <scope>runtime</scope>
-</dependency>
-----
-
-Gradle::
-+
-[source,groovy,subs="+attributes"]
-----
-runtimeOnly 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:{jackson-version}'
-----
-====
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-csv.adoc b/src/site/antora/modules/ROOT/partials/manual/layouts-gcfree-lookup.adoc
similarity index 61%
rename from src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-csv.adoc
rename to src/site/antora/modules/ROOT/partials/manual/layouts-gcfree-lookup.adoc
index 38b130a52d..1fd022a2f5 100644
--- a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-csv.adoc
+++ b/src/site/antora/modules/ROOT/partials/manual/layouts-gcfree-lookup.adoc
@@ -15,24 +15,7 @@
limitations under the License.
////
-[tabs]
-====
-Maven::
-+
-[source,xml,subs="+attributes"]
-----
-<dependency>
- <groupId>org.apache.commons</groupId>
- <artifactId>commons-csv</artifactId>
- <version>{commons-csv-version}</version>
- <scope>runtime</scope>
-</dependency>
-----
-
-Gradle::
-+
-[source,groovy,subs="+attributes"]
-----
-runtimeOnly 'org.apache.commons:commons-csv:{commons-csv-version}'
-----
-====
\ No newline at end of file
+Encoding the output of a lookup is garbage-free, but executing the lookup might not be.
+For instance, even though xref:manual/lookups.adoc#DateLookup[the `date` lookup] allocates a new `String` for each invocation, adding `${date:YYYY-MM-dd}` is garbage-free, because it will be expanded at configuration time, that is, only once.
+Whereas adding `$${date:YYYY-MM-dd}` is not, since it will be expanded for each log event.
+See xref:manual/configuration.adoc#property-substitution[property substitution] for details.
diff --git a/src/site/antora/modules/ROOT/partials/manual/layouts-location-information.adoc b/src/site/antora/modules/ROOT/partials/manual/layouts-location-information.adoc
index da26dff991..4695c80bea 100644
--- a/src/site/antora/modules/ROOT/partials/manual/layouts-location-information.adoc
+++ b/src/site/antora/modules/ROOT/partials/manual/layouts-location-information.adoc
@@ -57,5 +57,5 @@ You can override the default behaviour in your asynchronous logger or asynchrono
[NOTE]
====
Even if a layout is configured not to **request** location information, it might use it if the information is already available.
-This is always the case of information location computed at build time using the link:/log4j/transform/latest/#log4j-transform-maven-plugin[Log4j Transform Maven Plugin].
+This is always the case if the location information is captured at build time using the link:/log4j/transform/latest/#log4j-transform-maven-plugin[Log4j Transform Maven Plugin].
====
diff --git a/src/site/antora/modules/ROOT/partials/manual/plugin-preliminaries.adoc b/src/site/antora/modules/ROOT/partials/manual/plugin-preliminaries.adoc
new file mode 100644
index 0000000000..ce00948b59
--- /dev/null
+++ b/src/site/antora/modules/ROOT/partials/manual/plugin-preliminaries.adoc
@@ -0,0 +1,25 @@
+////
+ 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.
+////
+
+Log4j plugin system is the de facto extension mechanism embraced by various Log4j components.
+Plugins make it possible for extensible components to _receive_ feature implementations without any explicit links in between.
+It is analogous to a https://en.wikipedia.org/wiki/Dependency_injection[dependency injection] framework, but curated for Log4j-specific needs.
+
+In a nutshell, you annotate your classes with link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/Plugin.html[`@Plugin`] and their (`static`) factory methods with link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginFactory.html[`@PluginFactory`].
+Last, you inform the Log4j plugin system to discover these custom classes.
+This is done using running the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/processor/PluginProcessor.html[`PluginProcessor`] annotation processor while building your project.
+Refer to xref:manual/plugins.adoc[] for details.
diff --git a/src/site/resources/.htaccess b/src/site/resources/.htaccess
index 8194fd29b5..708c2c5df7 100644
--- a/src/site/resources/.htaccess
+++ b/src/site/resources/.htaccess
@@ -54,6 +54,47 @@ RewriteRule "^log4j-slf4j-impl\.html$" "manual/installation.html#impl-core-bridg
RewriteRule "^log4j-slf4j2-impl/index\.html$" "manual/installation.html#impl-core-bridge-slf4j" [R=permanent,NE]
RewriteRule "^log4j-slf4j2-impl\.html$" "manual/installation.html#impl-core-bridge-slf4j" [R=permanent,NE]
RewriteRule "^manual/api-separation\.html$" "manual/api.html" [R=permanent]
+RewriteRule "^manual/extending\.html#Layouts$" "manual/layouts.html#extending" [R=permanent]
+RewriteRule "^manual/extending\.html#PatternConverters$" "manual/pattern-layout.html#extending-converters" [R=permanent]
+RewriteRule "^manual/layouts\.html#enable-jansi$" "manual/pattern-layout.html#jansi" [R=permanent]
+RewriteRule "^manual/layouts\.html#EndOfBatch$" "manual/pattern-layout.html#converter-end-of-batch" [R=permanent]
+RewriteRule "^manual/layouts\.html#LevelPatternSelector$" "manual/pattern-layout.html#plugin-element-LevelPatternSelector" [R=permanent]
+RewriteRule "^manual/layouts\.html#MarkerPatternSelector$" "manual/pattern-layout.html#plugin-element-MarkerPatternSelector" [R=permanent]
+RewriteRule "^manual/layouts\.html#(PatternLayout|pattern-layout)$" "manual/pattern-layout.html" [R=permanent]
+RewriteRule "^manual/layouts\.html#Patterns$" "manual/pattern-layout.html#converters" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternClass$" "manual/pattern-layout.html#converter-class" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternDate$" "manual/pattern-layout.html#converter-date" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternException$" "manual/pattern-layout.html#converter-exception" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternExtendedException$" "manual/pattern-layout.html#converter-exception-extended" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternFile$" "manual/pattern-layout.html#converter-file" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternLevel$" "manual/pattern-layout.html#converter-level" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternLine$" "manual/pattern-layout.html#converter-line" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternLocation$" "manual/pattern-layout.html#converter-location" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternLoggerFqcn$" "manual/pattern-layout.html#converter-fqcn" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternMap$" "manual/pattern-layout.html#converter-map" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternMarker(SimpleName)?$" "manual/pattern-layout.html#converter-marker" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternMaxLength$" "manual/pattern-layout.html#converter-max-len" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternMDC$" "manual/pattern-layout.html#converter-thread-context-map" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternMessage$" "manual/pattern-layout.html#converter-message" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternMethod$" "manual/pattern-layout.html#converter-method" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternNDC$" "manual/pattern-layout.html#converter-thread-context-stack" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternPercentLiteral$" "manual/pattern-layout.html#usage" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternRelative$" "manual/pattern-layout.html#converter-relative" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternRepeat$" "manual/pattern-layout.html#converter-repeat" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternReplace$" "manual/pattern-layout.html#converter-replace" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternSelectors$" "manual/pattern-layout.html#plugin-element-PatternSelector" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternSequenceNumber$" "manual/pattern-layout.html#converter-seq" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternStyle$" "manual/pattern-layout.html#converter-style" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternThreadId$" "manual/pattern-layout.html#converter-thread-id" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternThreadName$" "manual/pattern-layout.html#converter-thread-name" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternThreadPriority$" "manual/pattern-layout.html#converter-thread-priority" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternUUID$" "manual/pattern-layout.html#converter-uuid" [R=permanent]
+RewriteRule "^manual/layouts\.html#NanoTime$" "manual/pattern-layout.html#converter-nano" [R=permanent]
+RewriteRule "^manual/layouts\.html#PatternNewLine$" "manual/pattern-layout.html#usage" [R=permanent]
+RewriteRule "^manual/layouts\.html#Process_ID$" "manual/pattern-layout.html#converter-pid" [R=permanent]
+RewriteRule "^manual/layouts\.html#ScriptPatternSelector$" "manual/pattern-layout.html#plugin-element-ScriptPatternSelector" [R=permanent]
+RewriteRule "^manual/layouts\.html#VariablesNotEmpty$" "manual/pattern-layout.html#converter-not-empty" [R=permanent]
+RewriteRule "^manual/plugins\.html#converters$" "manual/pattern-layout.html#extending-converters" [R=permanent]
RewriteRule "^manual/scala-api\.html$" "/log4j/scala/latest/index.html" [R=permanent]
RewriteRule "^manual/usage\.html$" "manual/api.html" [R=permanent]
RewriteRule "^runtime-dependencies\.html$" "manual/installation.html" [R=permanent]