You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by pk...@apache.org on 2024/05/28 12:50:01 UTC
(logging-log4j2) 01/02: Port "Configuration" page changes to `main`
This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch doc/main/configuration
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 202e06975f298549cc340116254a39c463ffec05
Author: Piotr P. Karwasz <pi...@karwasz.org>
AuthorDate: Fri May 17 13:44:32 2024 +0200
Port "Configuration" page changes to `main`
---
.../manual/configuration/arbiters-select.json | 29 +
.../configuration/arbiters-select.properties | 32 +
.../manual/configuration/arbiters-select.xml | 42 +
.../manual/configuration/arbiters-select.yaml | 35 +
.../examples/manual/configuration/arbiters.json | 33 +
.../manual/configuration/arbiters.properties | 32 +
.../examples/manual/configuration/arbiters.xml | 38 +
.../examples/manual/configuration/arbiters.yaml | 34 +
.../manual/configuration/logger-properties.json | 29 +
.../configuration/logger-properties.properties | 32 +
.../manual/configuration/logger-properties.xml | 37 +
.../manual/configuration/logger-properties.yaml | 34 +
.../examples/manual/configuration/loggers.json | 37 +
.../manual/configuration/loggers.properties | 33 +
.../ROOT/examples/manual/configuration/loggers.xml | 40 +
.../examples/manual/configuration/loggers.yaml | 37 +
.../manual/configuration/main-elements.json | 47 +
.../manual/configuration/main-elements.properties | 40 +
.../manual/configuration/main-elements.xml | 43 +
.../manual/configuration/main-elements.yaml | 42 +
.../manual/configuration/properties-example.json | 14 +
.../configuration/properties-example.properties | 18 +
.../manual/configuration/properties-example.xml | 21 +
.../manual/configuration/properties-example.yaml | 22 +
.../manual/configuration/properties-recursion.json | 18 +
.../configuration/properties-recursion.properties | 19 +
.../manual/configuration/properties-recursion.xml | 22 +
.../manual/configuration/properties-recursion.yaml | 24 +
.../examples/manual/configuration/properties.json | 17 +
.../manual/configuration/properties.properties | 19 +
.../examples/manual/configuration/properties.xml | 28 +
.../examples/manual/configuration/properties.yaml | 24 +
.../examples/manual/configuration/routing.json | 34 +
.../manual/configuration/routing.properties | 37 +
.../ROOT/examples/manual/configuration/routing.xml | 45 +
.../examples/manual/configuration/routing.yaml | 36 +
.../examples/manual/configuration/scripts.json | 65 +
.../manual/configuration/scripts.properties | 67 +
.../ROOT/examples/manual/configuration/scripts.xml | 68 +
.../examples/manual/configuration/scripts.yaml | 70 +
.../manual/configuration/xinclude-appenders.xml | 25 +
.../manual/configuration/xinclude-loggers.xml | 25 +
.../manual/configuration/xinclude-main.xml | 29 +
.../ROOT/examples/manual/filters/filters.json | 36 +
.../examples/manual/filters/filters.properties | 38 +
.../ROOT/examples/manual/filters/filters.xml | 42 +
.../ROOT/examples/manual/filters/filters.yaml | 41 +
src/site/antora/modules/ROOT/nav.adoc | 26 +-
.../modules/ROOT/pages/manual/appenders.adoc | 11 +-
.../modules/ROOT/pages/manual/architecture.adoc | 2 +
.../modules/ROOT/pages/manual/configuration.adoc | 2816 ++++++++------------
.../antora/modules/ROOT/pages/manual/filters.adoc | 251 +-
.../modules/ROOT/pages/manual/installation.adoc | 96 +-
.../antora/modules/ROOT/pages/manual/layouts.adoc | 28 +-
.../modules/ROOT/pages/manual/migration.adoc | 4 +-
.../antora/modules/ROOT/pages/manual/scripts.adoc | 127 +
.../modules/ROOT/pages/plugin-reference.adoc | 767 ++++++
.../partials/configuration-file-format-deps.adoc | 64 +-
58 files changed, 3845 insertions(+), 1977 deletions(-)
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters-select.json b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters-select.json
new file mode 100644
index 0000000000..a8a4eb0b9b
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters-select.json
@@ -0,0 +1,29 @@
+{
+ "Configuration": {
+ "Appenders": {
+ "File": {
+ "name": "MAIN",
+ // tag::select[]
+ "Select": {
+ "SystemPropertyArbiter": { // <1>
+ "propertyName": "env",
+ "propertyValue": "dev",
+ "PatternLayout": {}
+ },
+ "DefaultArbiter": { // <2>
+ "JsonTemplateLayout": {}
+ }
+ }
+ // end::select[]
+ }
+ },
+ "Loggers": {
+ "Root": {
+ "level": "INFO",
+ "AppenderRef": {
+ "ref": "MAIN"
+ }
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters-select.properties b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters-select.properties
new file mode 100644
index 0000000000..8fa74a1d8e
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters-select.properties
@@ -0,0 +1,32 @@
+#
+# 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 = File
+appender.0.name = MAIN
+# tag::select[]
+appender.0.select.type = Select
+
+appender.0.select.0.type = SystemPropertyArbiter # <1>
+appender.0.select.0.propertyName = env
+appender.0.select.0.propertyValue = dev
+appender.0.select.0.layout.type = PatternLayout
+
+appender.0.select.1.type = DefaultArbiter # <2>
+appender.0.select.1.layout.type = JsonTemplateLayout
+# end::select[]
+
+rootLogger.level = INFO
+rootLogger.appenderRef.0.ref = MAIN
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters-select.xml b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters-select.xml
new file mode 100644
index 0000000000..a7190f3018
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters-select.xml
@@ -0,0 +1,42 @@
+<?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>
+ <File name="MAIN" fileName="logs/app.log">
+ <!-- tag::select[] -->
+ <Select>
+ <SystemPropertyArbiter propertyName="env" propertyValue="dev"> <!--1-->
+ <PatternLayout/>
+ </SystemPropertyArbiter>
+ <DefaultArbiter> <!--2-->
+ <JsonTemplateLayout/>
+ </DefaultArbiter>
+ </Select>
+ <!-- end::select[] -->
+ </File>
+ </Appenders>
+ <Loggers>
+ <Root level="INFO">
+ <AppenderRef ref="MAIN"/>
+ </Root>
+ </Loggers>
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters-select.yaml b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters-select.yaml
new file mode 100644
index 0000000000..046b09fc08
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters-select.yaml
@@ -0,0 +1,35 @@
+#
+# 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:
+ File:
+ name: "MAIN"
+ fileName: "logs/app.log"
+ # tag::select[]
+ Select:
+ SystemPropertyArbiter: # <1>
+ propertyName: "env"
+ propertyValue: "dev"
+ PatternLayout: {}
+ DefaultArbiter: # <2>
+ JsonTemplateLayout: {}
+ # end::select[]
+ Loggers:
+ Root:
+ level: "INFO"
+ AppenderRef:
+ ref: "MAIN"
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters.json b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters.json
new file mode 100644
index 0000000000..d732aaaa7a
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters.json
@@ -0,0 +1,33 @@
+{
+ "Configuration": {
+ "Appenders": {
+ "File": {
+ "name": "MAIN",
+ "SystemPropertyArbiter": [
+ // <1>
+ {
+ "propertyName": "env",
+ "propertyValue": "dev",
+ "PatternLayout": {
+ "pattern": "%d [%t] %p %c - %m%n"
+ }
+ },
+ // <2>
+ {
+ "propertyName": "env",
+ "propertyValue": "prod",
+ "JsonTemplateLayout": {}
+ }
+ ]
+ }
+ },
+ "Loggers": {
+ "Root": {
+ "level": "INFO",
+ "AppenderRef": {
+ "ref": "MAIN"
+ }
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters.properties b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters.properties
new file mode 100644
index 0000000000..72e81e778c
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters.properties
@@ -0,0 +1,32 @@
+#
+# 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 = File
+appender.0.name = MAIN
+
+appender.0.arbiter[0].type = SystemPropertyArbiter # <1>
+appender.0.arbiter[0].propertyName = env
+appender.0.arbiter[0].propertyValue = dev
+appender.0.arbiter[0].layout.type = PatternLayout
+appender.0.arbiter[0].layout.pattern = %d [%t] %p %c - %m%n
+
+appender.0.arbiter[1].type = SystemPropertyArbiter # <2>
+appender.0.arbiter[1].propertyName = env
+appender.0.arbiter[1].propertyValue = prod
+appender.0.arbiter[1].layout.type = JsonTemplateLayout
+
+rootLogger.level = INFO
+rootLogger.appenderRef.0.ref = MAIN
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters.xml b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters.xml
new file mode 100644
index 0000000000..f030f4733a
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters.xml
@@ -0,0 +1,38 @@
+<?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>
+ <File name="MAIN" fileName="logs/app.log">
+ <SystemPropertyArbiter propertyName="env" propertyValue="dev"> <!--1-->
+ <PatternLayout pattern="%d [%t] %p %c - %m%n"/>
+ </SystemPropertyArbiter>
+ <SystemPropertyArbiter propertyName="env" propertyValue="prod"> <!--2-->
+ <JsonTemplateLayout/>
+ </SystemPropertyArbiter>
+ </File>
+ </Appenders>
+ <Loggers>
+ <Root level="INFO">
+ <AppenderRef ref="MAIN"/>
+ </Root>
+ </Loggers>
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters.yaml b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters.yaml
new file mode 100644
index 0000000000..53cd2477b1
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/arbiters.yaml
@@ -0,0 +1,34 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to you under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+Configuration:
+ Appenders:
+ File:
+ name: "MAIN"
+ fileName: "logs/app.log"
+ SystemPropertyArbiter:
+ - propertyName: "env" # <1>
+ propertyValue: "dev"
+ PatternLayout:
+ pattern: "%d [%t] %p %c - %m%n"
+ - propertyName: "env" # <2>
+ propertyValue: "prod"
+ JsonTemplateLayout: {}
+ Loggers:
+ Root:
+ level: "INFO"
+ AppenderRef:
+ ref: "MAIN"
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/logger-properties.json b/src/site/antora/modules/ROOT/examples/manual/configuration/logger-properties.json
new file mode 100644
index 0000000000..725de4263b
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/logger-properties.json
@@ -0,0 +1,29 @@
+{
+ "Configuration": {
+ "Appenders": {},
+ "Loggers": {
+ // tag::loggers[]
+ "Root": {
+ "Property": {
+ "name": "client.address",
+ "value": "$${web:request.remoteAddress}"
+ }
+ },
+ "Logger": [
+ {
+ "name": "org.hibernate",
+ "Property": {
+ "subsystem": "Database"
+ }
+ },
+ {
+ "name": "io.netty",
+ "Property": {
+ "subsystem": "Networking"
+ }
+ }
+ ]
+ // end::loggers[]
+ }
+ }
+}
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/logger-properties.properties b/src/site/antora/modules/ROOT/examples/manual/configuration/logger-properties.properties
new file mode 100644
index 0000000000..5533e1140c
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/logger-properties.properties
@@ -0,0 +1,32 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to you under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+##
+# tag::loggers[]
+rootLogger.property.type = Property
+rootLogger.name = client.address
+rootLogger.value = $${web:request.remoteAddress}
+
+logger.0.name = org.hibernate
+logger.0.property.type = Property
+logger.0.property.name = subsystem
+logger.0.property.value = Database
+
+logger.1.name = io.netty
+logger.1.property.type = Property
+logger.1.property.name = subsystem
+logger.1.property.value = Networking
+# end::loggers[]
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/logger-properties.xml b/src/site/antora/modules/ROOT/examples/manual/configuration/logger-properties.xml
new file mode 100644
index 0000000000..44ec26a0e6
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/logger-properties.xml
@@ -0,0 +1,37 @@
+<?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/>
+ <Loggers>
+ <!-- tag::loggers[] -->
+ <Root>
+ <Property name="client.address" value="$${web:request.remoteAddress}"/>
+ </Root>
+ <Logger name="org.hibernate">
+ <Property name="subsystem" value="Database"/>
+ </Logger>
+ <Logger name="io.netty">
+ <Property name="subsystem" value="Networking"/>
+ </Logger>
+ <!-- end::loggers[] -->
+ </Loggers>
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/logger-properties.yaml b/src/site/antora/modules/ROOT/examples/manual/configuration/logger-properties.yaml
new file mode 100644
index 0000000000..e746721616
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/logger-properties.yaml
@@ -0,0 +1,34 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to you under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+Configuration:
+ Appenders: {}
+ Loggers:
+ # tag::loggers[]
+ Root:
+ Property:
+ name: "client.address"
+ value: "$${web:request.remoteAddress}"
+ Logger:
+ - name: "org.hibernate"
+ Property:
+ name: "subsystem"
+ value: "Database"
+ - name: "io.netty"
+ Property:
+ name: "subsystem"
+ value: "Networking"
+ # end::loggers[]
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/loggers.json b/src/site/antora/modules/ROOT/examples/manual/configuration/loggers.json
new file mode 100644
index 0000000000..e381ea3642
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/loggers.json
@@ -0,0 +1,37 @@
+{
+ "Configuration": {
+ // tag::loggers[]
+ "Loggers": {
+ "Root": { // <1>
+ "level": "INFO",
+ "AppenderRef": {
+ "ref": "APPENDER1"
+ }
+ },
+ "Logger": [
+ { // <2>
+ "name": "org.example.no_additivity",
+ "additivity": false,
+ "AppenderRef": {
+ "ref": "APPENDER2"
+ }
+ },
+ { // <3>
+ "name": "org.example.no_location",
+ "includeLocation": false,
+ "AppenderRef": {
+ "ref": "APPENDER3"
+ }
+ },
+ { // <4>
+ "name": "org.example.level",
+ "level": "DEBUG",
+ "AppenderRef": {
+ "ref": "APPENDER4"
+ }
+ }
+ ]
+ }
+ // end::loggers[]
+ }
+}
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/loggers.properties b/src/site/antora/modules/ROOT/examples/manual/configuration/loggers.properties
new file mode 100644
index 0000000000..01b945ebac
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/loggers.properties
@@ -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.
+#
+##
+# tag::loggers[]
+rootLogger.level = INFO # <1>
+rootLogger.appenderRef.0.ref = APPENDER1
+
+logger.0.name = org.example.no_additivity # <2>
+logger.0.additivity = false
+logger.0.appenderRef.0.ref = APPENDER2
+
+logger.1.name = org.example.no_location # <3>
+logger.1.includeLocation = false
+logger.1.appenderRef.0.ref = APPENDER3
+
+logger.2.name = org.example.level # <4>
+logger.2.level = DEBUG
+logger.2.appenderRef.0.ref = APPENDER4
+# end::loggers[]
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/loggers.xml b/src/site/antora/modules/ROOT/examples/manual/configuration/loggers.xml
new file mode 100644
index 0000000000..4549b534f2
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/loggers.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/>
+ <!-- tag::loggers[] -->
+ <Loggers>
+ <Root level="INFO"> <!--1-->
+ <AppenderRef ref="APPENDER1"/>
+ </Root>
+ <Logger name="org.example.no_additivity" additivity="false"> <!--2-->
+ <AppenderRef ref="APPENDER2"/>
+ </Logger>
+ <Logger name="org.example.no_location" includeLocation="false"> <!--3-->
+ <AppenderRef ref="APPENDER3"/>
+ </Logger>
+ <Logger name="org.example.level" level="DEBUG"> <!--4-->
+ <AppenderRef ref="APPENDER4"/>
+ </Logger>
+ </Loggers>
+ <!-- end::loggers[] -->
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/loggers.yaml b/src/site/antora/modules/ROOT/examples/manual/configuration/loggers.yaml
new file mode 100644
index 0000000000..eae440e525
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/loggers.yaml
@@ -0,0 +1,37 @@
+#
+# 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:
+ # tag::loggers[]
+ Loggers:
+ Root: # <1>
+ level: "INFO"
+ AppenderRef:
+ ref: "APPENDER1"
+ Logger:
+ - name: "org.example.no_additivity" # <2>
+ additivity: false
+ AppenderRef:
+ ref: "APPENDER2"
+ - name: "org.example.no_location" # <3>
+ includeLocation: false
+ AppenderRef:
+ ref: "APPENDER3"
+ - name: "org.example.level" # <4>
+ level: "DEBUG"
+ AppenderRef:
+ ref: "APPENDER4"
+ # end::loggers[]
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/main-elements.json b/src/site/antora/modules/ROOT/examples/manual/configuration/main-elements.json
new file mode 100644
index 0000000000..0d17c82686
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/main-elements.json
@@ -0,0 +1,47 @@
+{
+ "Configuration": {
+ "Appenders": {
+ "Console": { // <1>
+ "name": "CONSOLE",
+ "PatternLayout": {
+ "pattern": "%p - %m%n"
+ }
+ },
+ "File": [
+ { // <2>
+ "name": "MAIN",
+ "fileName": "logs/main.log",
+ "JsonTemplateLayout": {}
+ },
+ { // <3>
+ "name": "DEBUG_LOG",
+ "fileName": "logs/debug.log",
+ "PatternLayout": {
+ "pattern": "%d [%t] %p %c - %m%n"
+ }
+ }
+ ]
+ },
+ "Loggers": {
+ "Root": { // <4>
+ "level": "INFO",
+ "AppenderRef": [
+ {
+ "ref": "CONSOLE",
+ "level": "WARN"
+ },
+ {
+ "ref": "MAIN"
+ }
+ ]
+ },
+ "Logger": { // <5>
+ "name": "org.example",
+ "level": "DEBUG",
+ "AppenderRef": {
+ "ref": "DEBUG_LOG"
+ }
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/main-elements.properties b/src/site/antora/modules/ROOT/examples/manual/configuration/main-elements.properties
new file mode 100644
index 0000000000..2b98fbe657
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/main-elements.properties
@@ -0,0 +1,40 @@
+#
+# 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 = PatternLayout
+appender.0.layout.pattern = %p - %m%n
+
+appender.1.type = File # <2>
+appender.1.name = MAIN
+appender.1.fileName = logs/main.log
+appender.1.layout.type = JsonTemplateLayout
+
+appender.2.type = File # <3>
+appender.2.name = DEBUG_LOG
+appender.2.fileName = logs/debug.log
+appender.2.layout.type = PatternLayout
+appender.2.layout.pattern = %d [%t] %p %c - %m%n
+
+rootLogger.level = INFO # <4>
+rootLogger.appenderRef.0.ref = CONSOLE
+rootLogger.appenderRef.0.level = WARN
+rootLogger.appenderRef.1.ref = MAIN
+
+logger.0.name = org.example # <5>
+logger.0.level = DEBUG
+logger.0.appenderRef.0.ref = DEBUG_LOG
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/main-elements.xml b/src/site/antora/modules/ROOT/examples/manual/configuration/main-elements.xml
new file mode 100644
index 0000000000..6f3957d614
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/main-elements.xml
@@ -0,0 +1,43 @@
+<?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-->
+ <PatternLayout pattern="%p - %m%n"/>
+ </Console>
+ <File name="MAIN" fileName="logs/main.log"> <!--2-->
+ <JsonTemplateLayout/>
+ </File>
+ <File name="DEBUG_LOG" fileName="logs/debug.log"> <!--3-->
+ <PatternLayout pattern="%d [%t] %p %c - %m%n"/>
+ </File>
+ </Appenders>
+ <Loggers>
+ <Root level="INFO"> <!--4-->
+ <AppenderRef ref="CONSOLE" level="WARN"/>
+ <AppenderRef ref="MAIN"/>
+ </Root>
+ <Logger name="org.example" level="DEBUG"> <!--5-->
+ <AppenderRef ref="DEBUG_LOG"/>
+ </Logger>
+ </Loggers>
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/main-elements.yaml b/src/site/antora/modules/ROOT/examples/manual/configuration/main-elements.yaml
new file mode 100644
index 0000000000..e29280933e
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/main-elements.yaml
@@ -0,0 +1,42 @@
+#
+# 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: # <1>
+ name: "CONSOLE"
+ PatternLayout:
+ pattern: "%p - %m%n"
+ File:
+ - name: "MAIN" # <2>
+ fileName: "logs/main.log"
+ JsonTemplateLayout: {}
+ - name: "DEBUG_LOG" # <3>
+ fileName: "logs/debug.log"
+ PatternLayout:
+ pattern: "%d [%t] %p %c - %m%n"
+ Loggers:
+ Root: # <4>
+ level: "INFO"
+ AppenderRef:
+ - ref: "CONSOLE"
+ level: "WARN"
+ - ref: "MAIN"
+ Logger: # <5>
+ name: "org.example"
+ level: "DEBUG"
+ AppenderRef:
+ ref: "DEBUG_LOG"
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.json b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.json
new file mode 100644
index 0000000000..2928369686
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.json
@@ -0,0 +1,14 @@
+{
+ "Properties": {
+ "Property": [
+ {
+ "name": "FOO",
+ "value": "foo"
+ },
+ {
+ "name": "BAR",
+ "value": "bar"
+ }
+ ]
+ }
+}
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.properties b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.properties
new file mode 100644
index 0000000000..099524cc74
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.properties
@@ -0,0 +1,18 @@
+#
+# 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.
+#
+property.FOO = foo
+property.BAR = bar
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.xml b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.xml
new file mode 100644
index 0000000000..5d13d93732
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.xml
@@ -0,0 +1,21 @@
+<?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.
+ -->
+<Properties>
+ <Property name="FOO" value="foo"/>
+ <Property name="BAR" value="bar"/>
+</Properties>
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.yaml b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.yaml
new file mode 100644
index 0000000000..35ef189004
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-example.yaml
@@ -0,0 +1,22 @@
+#
+# 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.
+#
+Properties:
+ Property:
+ - name: "FOO"
+ value: "foo"
+ - name: "BAR"
+ value: "bar"
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.json b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.json
new file mode 100644
index 0000000000..6cfdc62799
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.json
@@ -0,0 +1,18 @@
+{
+ "Properties": {
+ "Property": [
+ {
+ "name": "logging.file",
+ "value": "${logging.path}/app.log"
+ },
+ {
+ "name": "logging.dir",
+ "value": "${env:APP_BASE}/logs"
+ },
+ {
+ "name": "APP_BASE",
+ "value": "."
+ }
+ ]
+ }
+}
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.properties b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.properties
new file mode 100644
index 0000000000..0c54dd40cb
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.properties
@@ -0,0 +1,19 @@
+#
+# 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.
+#
+property.logging.file = ${logging.dir}/app.log
+property.logging.dir = ${env:APP_BASE}/logs
+property.APP_BASE = .
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.xml b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.xml
new file mode 100644
index 0000000000..98ac38dd07
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.xml
@@ -0,0 +1,22 @@
+<?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.
+ -->
+<Properties>
+ <Property name="logging.file" value="${logging.dir}/app.log"/>
+ <Property name="logging.dir" value="${env:APP_BASE}/logs"/>
+ <Property name="APP_BASE" value="."/>
+</Properties>
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.yaml b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.yaml
new file mode 100644
index 0000000000..2fa6ecc24c
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/properties-recursion.yaml
@@ -0,0 +1,24 @@
+#
+# 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.
+#
+Properties:
+ Property:
+ - name: "logging.file"
+ value: "${logging.dir}/app.log"
+ - name: "logging.dir"
+ value: "${env:APP_BASE}/logs"
+ - name: "APP_BASE"
+ value: "."
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/properties.json b/src/site/antora/modules/ROOT/examples/manual/configuration/properties.json
new file mode 100644
index 0000000000..c3fb1911b2
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/properties.json
@@ -0,0 +1,17 @@
+{
+ "Configuration": {
+ "Properties": {
+ "Property": [
+ {
+ "name": "log.dir",
+ "value": "/var/log"
+ },
+ {
+ "name": "log.file",
+ "value": "${log.dir}/app.log"
+ }
+ ]
+ }
+ // ...
+ }
+}
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/properties.properties b/src/site/antora/modules/ROOT/examples/manual/configuration/properties.properties
new file mode 100644
index 0000000000..77a67b7823
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/properties.properties
@@ -0,0 +1,19 @@
+#
+# 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.
+#
+property.log.dir = /var/log
+property.log.file = ${log.dir}/app.log
+# ...
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/properties.xml b/src/site/antora/modules/ROOT/examples/manual/configuration/properties.xml
new file mode 100644
index 0000000000..8851bfd36c
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/properties.xml
@@ -0,0 +1,28 @@
+<?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">
+ <Properties>
+ <Property name="log.dir" value="/var/log"/>
+ <Property name="log.file" value="${log.dir}/app.log"/>
+ </Properties>
+ <!-- ... -->
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/properties.yaml b/src/site/antora/modules/ROOT/examples/manual/configuration/properties.yaml
new file mode 100644
index 0000000000..4723e42f67
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/properties.yaml
@@ -0,0 +1,24 @@
+#
+# 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:
+ Properties:
+ Property:
+ - name: "log.dir"
+ value: "/var/log"
+ - name: "log.file"
+ value: "${log.dir}/app.log"
+# ...
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/routing.json b/src/site/antora/modules/ROOT/examples/manual/configuration/routing.json
new file mode 100644
index 0000000000..cc6ab3b5e6
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/routing.json
@@ -0,0 +1,34 @@
+{
+ "Configuration": {
+ "Appenders": {
+ // tag::appender[]
+ "Routing": {
+ "name": "ROUTING",
+ "Routes": {
+ "pattern": "$${sd:type}", // <1>
+ "Route": {
+ "File": {
+ "name": "ROUTING-${sd:type}", // <2>
+ "fileName": "logs/${sd:type}.log", // <2>
+ "JsonTemplateLayout": {
+ "EventTemplateAdditionalField": {
+ "name": "type",
+ "value": "${sd:type}" // <2>
+ }
+ }
+ }
+ }
+ }
+ }
+ // end::appender[]
+ },
+ "Loggers": {
+ "Root": {
+ "AppenderRef": {
+ "level": "INFO",
+ "ref": "ROUTING"
+ }
+ }
+ }
+ }
+}
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/routing.properties b/src/site/antora/modules/ROOT/examples/manual/configuration/routing.properties
new file mode 100644
index 0000000000..912e5be0c9
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/routing.properties
@@ -0,0 +1,37 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to you under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+##
+# tag::appender[]
+appender.0.type = Routing
+appender.0.name = ROUTING
+
+appender.0.routes.type = Routes
+appender.0.routes.pattern = $${sd:type} # <1>
+
+appender.0.routes.route.type = Route
+
+appender.0.routes.route.file.type = File
+appender.0.routes.route.file.name = ROUTING-${sd:type} # <2>
+appender.0.routes.route.file.fileName = logs/${sd:type}.log # <2>
+appender.0.routes.route.file.layout.type = JsonTemplateLayout
+appender.0.routes.route.file.layout.field.type = EventTemplateAdditionalField
+appender.0.routes.route.file.layout.field.name = type
+appender.0.routes.route.file.layout.field.value = ${sd:type} # <2>
+# end::appender[]
+
+rootLogger.level = INFO
+rootLogger.appenderRef.0.ref = ROUTING
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/routing.xml b/src/site/antora/modules/ROOT/examples/manual/configuration/routing.xml
new file mode 100644
index 0000000000..ebda4946e5
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/routing.xml
@@ -0,0 +1,45 @@
+<?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>
+ <!-- tag::appender[] -->
+ <Routing name="ROUTING">
+ <Routes pattern="$${sd:type}"> <!--1-->
+ <Route>
+ <File name="ROUTING-${sd:type}"
+ fileName="logs/${sd:type}.log"> <!--2-->
+ <JsonTemplateLayout>
+ <EventTemplateAdditionalField name="type"
+ value="${sd:type}"/> <!--2-->
+ </JsonTemplateLayout>
+ </File>
+ </Route>
+ </Routes>
+ </Routing>
+ <!-- end::appender[] -->
+ </Appenders>
+ <Loggers>
+ <Root level="INFO">
+ <AppenderRef ref="ROUTING"/>
+ </Root>
+ </Loggers>
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/routing.yaml b/src/site/antora/modules/ROOT/examples/manual/configuration/routing.yaml
new file mode 100644
index 0000000000..b71bf5d4ca
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/routing.yaml
@@ -0,0 +1,36 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to you under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+Configuration:
+ Appenders:
+ # tag::appender[]
+ Routing:
+ name: "ROUTING"
+ Routes:
+ pattern: "$${sd:type}" # <1>
+ Route:
+ File:
+ name: "ROUTING-${sd:type}" # <2>
+ fileName: "logs/${sd:type}.log" # <2>
+ JsonTemplateLayout:
+ EventTemplateAdditionalField:
+ name: "type"
+ value: "${sd:type}" # <2>
+ # end::appender[]
+ Loggers:
+ Root:
+ level: "INFO"
+ AppenderRef: "ROUTING"
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/scripts.json b/src/site/antora/modules/ROOT/examples/manual/configuration/scripts.json
new file mode 100644
index 0000000000..73db82029c
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/scripts.json
@@ -0,0 +1,65 @@
+{
+ "Configuration": {
+ "Appenders": {
+ "Console": {
+ "name": "STDOUT",
+ "PatternLayout": {
+ "ScriptPatternSelector": {
+ "defaultPattern": "%d %p %m%n",
+ "ScriptRef": {
+ "ref": "SELECTOR_SCRIPT",
+ "PatternMatch": [
+ {
+ "key": "NoLocation",
+ "pattern": "[%-5level] %c{1.} %msg%n"
+ },
+ {
+ "key": "Flow",
+ "pattern": "[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "Loggers": {
+ "Logger": {
+ "name": "EventLogger",
+ "ScriptFilter": {
+ "onMatch": "ACCEPT",
+ "onMismatch": "DENY",
+ "Script": {
+ "name": "EVENT_LOGGER_FILTER",
+ "language": "groovy",
+ "scriptText": "if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf('FLOW'))) { return true; } else if (logEvent.getContextMap().containsKey('UserId')) { return true; } return false;"
+ }
+ }
+ },
+ "Root": {
+ "level": "INFO",
+ "ScriptFilter": {
+ "onMatch": "ACCEPT",
+ "onMismatch": "DENY",
+ "ScriptRef": {
+ "ref": "ROOT_FILTER"
+ }
+ },
+ "AppenderRef": {
+ "ref": "STDOUT"
+ }
+ },
+ "Scripts": {
+ "Script": {
+ "name": "SELECTOR_SCRIPT",
+ "language": "javascript",
+ "scriptText": "var result; if (logEvent.getLoggerName().equals('JavascriptNoLocation')) { result = 'NoLocation'; } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf('FLOW')) { result = 'Flow'; } result;"
+ },
+ "ScriptFile": {
+ "name": "ROOT_FILTER",
+ "path": "scripts/filter.groovy"
+ }
+ }
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/scripts.properties b/src/site/antora/modules/ROOT/examples/manual/configuration/scripts.properties
new file mode 100644
index 0000000000..8c41afe7d5
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/scripts.properties
@@ -0,0 +1,67 @@
+#
+# 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 = STDOUT
+appender.0.layout.type = PatternLayout
+
+appender.0.layout.selector = ScriptPatternSelector
+appender.0.layout.selector.defaultPattern = %d %p %m%n
+appender.0.layout.selector.scriptRef.type = ScriptRef
+appender.0.layout.selector.scriptRef.ref = SELECTOR_SCRIPT
+appender.0.layout.selector.match[0].type = PatternMatch
+appender.0.layout.selector.match[0].key = NoLocation
+appender.0.layout.selector.match[0].pattern = [%-5level] %c{1.} %msg%n
+appender.0.layout.selector.match[1].type = PatternMatch
+appender.0.layout.selector.match[1].key = Flow
+appender.0.layout.selector.match[1].pattern = [%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n
+
+logger.0.name = EventLogger
+logger.0.filter.0.type = ScriptFilter
+logger.0.filter.0.onMatch = ACCEPT
+logger.0.filter.0.onMismatch = DENY
+logger.0.filter.0.script.type = Script
+logger.0.filter.0.script.name = EVENT_LOGGER_FILTER
+logger.0.filter.0.script.language = groovy
+logger.0.filter.0.script.scriptText = if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW"))) {\
+ return true;\
+ } else if (logEvent.getContextMap().containsKey("UserId")) {\
+ return true;\
+ }\
+ return false;
+
+rootLogger.level = INFO
+rootLogger.filter.0.type = ScriptFilter
+rootLogger.filter.0.onMatch = ACCEPT
+rootLogger.filter.0.onMismatch = DENY
+rootLogger.filter.0.scriptRef.type = ScriptRef
+rootLogger.filter.0.scriptRef.ref = ROOT_FILTER
+rootLogger.appenderRef.0.ref = STDOUT
+
+script.0.type = Script
+script.0.name = SELECTOR_SCRIPT
+script.0.language = javascript
+script.0.scriptText = var result;\
+ if (logEvent.getLoggerName().equals("JavascriptNoLocation")) {\
+ result = "NoLocation";\
+ } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {\
+ result = "Flow";\
+ }\
+ result;
+
+script.1.type = ScriptFile
+script.1.name = ROOT_FILTER
+script.1.path = scripts/filter.groovy
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/scripts.xml b/src/site/antora/modules/ROOT/examples/manual/configuration/scripts.xml
new file mode 100644
index 0000000000..f7e8b4cfeb
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/scripts.xml
@@ -0,0 +1,68 @@
+<?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="STDOUT">
+ <PatternLayout>
+ <ScriptPatternSelector defaultPattern="%d %p %m%n">
+ <ScriptRef ref="SELECTOR_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>
+ <Logger name="EventLogger">
+ <ScriptFilter onMatch="ACCEPT" onMismatch="DENY">
+ <Script name="EVENT_LOGGER_FILTER" language="groovy"><![CDATA[
+ if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
+ return true;
+ } else if (logEvent.getContextMap().containsKey("UserId")) {
+ return true;
+ }
+ return false;
+ ]]>
+ </Script>
+ </ScriptFilter>
+ </Logger>
+ <Root level="INFO">
+ <ScriptFilter onMatch="ACCEPT" onMismatch="DENY">
+ <ScriptRef ref="ROOT_FILTER"/>
+ </ScriptFilter>
+ <AppenderRef ref="STDOUT"/>
+ </Root>
+ </Loggers>
+ <Scripts>
+ <Script name="SELECTOR_SCRIPT" language="javascript"><![CDATA[
+ var result;
+ if (logEvent.getLoggerName().equals("JavascriptNoLocation")) {
+ result = "NoLocation";
+ } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
+ result = "Flow";
+ }
+ result;
+ ]]>
+ </Script>
+ <ScriptFile name="ROOT_FILTER" path="scripts/filter.groovy"/>
+ </Scripts>
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/scripts.yaml b/src/site/antora/modules/ROOT/examples/manual/configuration/scripts.yaml
new file mode 100644
index 0000000000..6b5d6ccca1
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/scripts.yaml
@@ -0,0 +1,70 @@
+#
+# 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: "STDOUT"
+ PatternLayout:
+ ScriptPatternSelector:
+ defaultPattern: "%d %p %m%n"
+ ScriptRef:
+ ref: "SELECTOR_SCRIPT"
+ PatternMatch:
+ - key: "NoLocation"
+ pattern: "[%-5level] %c{1.} %msg%n"
+ - key: "Flow"
+ pattern: "[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"
+ Loggers:
+ Logger:
+ name: "EventLogger"
+ ScriptFilter:
+ onMatch: "ACCEPT"
+ onMismatch: "DENY"
+ Script:
+ name: "EVENT_LOGGER_FILTER"
+ language: "groovy"
+ scriptText: |
+ if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
+ return true;
+ } else if (logEvent.getContextMap().containsKey("UserId")) {
+ return true;
+ }
+ return false;
+ Root:
+ level: "INFO"
+ ScriptFilter:
+ onMatch: "ACCEPT"
+ onMismatch: "DENY"
+ ScriptRef:
+ ref: "ROOT_FILTER"
+ AppenderRef:
+ ref: "STDOUT"
+ Scripts:
+ Script:
+ name: "SELECTOR_SCRIPT"
+ language: "javascript"
+ scriptText: |
+ var result;
+ if (logEvent.getLoggerName().equals("JavascriptNoLocation")) {
+ result = "NoLocation";
+ } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
+ result = "Flow";
+ }
+ result;
+ ScriptFile:
+ name: "ROOT_FILTER"
+ path: "scripts/filter.groovy"
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/xinclude-appenders.xml b/src/site/antora/modules/ROOT/examples/manual/configuration/xinclude-appenders.xml
new file mode 100644
index 0000000000..b34c7b2a71
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/xinclude-appenders.xml
@@ -0,0 +1,25 @@
+<?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.
+ -->
+<Appenders>
+ <Console name="CONSOLE">
+ <PatternLayout pattern="%d %m%n"/>
+ </Console>
+ <File name="FILE" fileName="${filename}">
+ <PatternLayout pattern="%d %p %C{1.} [%t] %m%n"/>
+ </File>
+</Appenders>
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/xinclude-loggers.xml b/src/site/antora/modules/ROOT/examples/manual/configuration/xinclude-loggers.xml
new file mode 100644
index 0000000000..eeb674535d
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/xinclude-loggers.xml
@@ -0,0 +1,25 @@
+<?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.
+ -->
+<Loggers>
+ <Rogger name="org.example" level="DEBUG" additivity="false">
+ <AppenderRef ref="FILE" />
+ </Rogger>
+ <Root level="ERROR">
+ <AppenderRef ref="CONSOLE" />
+ </Root>
+</Loggers>
diff --git a/src/site/antora/modules/ROOT/examples/manual/configuration/xinclude-main.xml b/src/site/antora/modules/ROOT/examples/manual/configuration/xinclude-main.xml
new file mode 100644
index 0000000000..8eb0e666a0
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/configuration/xinclude-main.xml
@@ -0,0 +1,29 @@
+<?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:xi="http://www.w3.org/2001/XInclude"
+ 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">
+ <Properties>
+ <Property name="filename" value="app.log"/>
+ </Properties>
+ <xi:include href="xinclude-appenders.xml"/>
+ <xi:include href="xinclude-loggers.xml"/>
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/filters/filters.json b/src/site/antora/modules/ROOT/examples/manual/filters/filters.json
new file mode 100644
index 0000000000..4acc4c43b7
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/filters/filters.json
@@ -0,0 +1,36 @@
+{
+ "Configuration": {
+ "Appenders": {
+ "Console": {
+ "name": "CONSOLE",
+ "ThresholdFilter": {
+ "level": "WARN" // <6>
+ }
+ }
+ },
+ "Loggers": {
+ "Root": {
+ "level": "INFO",
+ "ThresholdFilter": { // <3>
+ "level": "DEBUG"
+ },
+ "AppenderRef": {
+ "ref": "CONSOLE",
+ "level": "WARN", // <5>
+ "MarkerFilter": { // <4>
+ "marker": "ALERT",
+ "onMatch": "NEUTRAL",
+ "onMismatch": "DENY"
+ }
+ }
+ },
+ "Logger": {
+ "name": "org.example",
+ "level": "TRACE" // <2>
+ }
+ }
+ },
+ "MarkerFilter": { // <1>
+ "marker": "PRIVATE"
+ }
+}
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/examples/manual/filters/filters.properties b/src/site/antora/modules/ROOT/examples/manual/filters/filters.properties
new file mode 100644
index 0000000000..1077fc44e7
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/filters/filters.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.filter.type = ThresholdFilter # <6>
+appender.0.filter.level = WARN
+
+rootLogger.level = INFO
+rootLogger.filter.type = ThresholdFilter # <3>
+rootLogger.filter.level = DEBUG
+rootLogger.appenderRef.0.ref = CONSOLE
+rootLogger.appenderRef.0.level = WARN # <5>
+rootLogger.appenderRef.0.filter.type = MarkerFilter # <4>
+rootLogger.appenderRef.0.filter.marker = ALERT
+rootLogger.appenderRef.0.filter.onMatch = NEUTRAL
+rootLogger.appenderRef.0.filter.onMismatch = DENY
+
+logger.0.name = org.example
+logger.0.level = DEBUG # <2>
+logger.0.filter.type = ThresholdFilter # <3>
+logger.0.filter.level = TRACE
+
+filter.type = MarkerFilter # <1>
+filter.marker = PRIVATE
diff --git a/src/site/antora/modules/ROOT/examples/manual/filters/filters.xml b/src/site/antora/modules/ROOT/examples/manual/filters/filters.xml
new file mode 100644
index 0000000000..4c86b04faf
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/filters/filters.xml
@@ -0,0 +1,42 @@
+<?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">
+ <ThresholdFilter level="WARN"/> <!--6-->
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Root level="INFO">
+ <ThresholdFilter level="DEBUG"/> <!--3-->
+ <AppenderRef ref="CONSOLE" level="WARN"> <!--5-->
+ <MarkerFilter marker="ALERT"
+ onMatch="NEUTRAL"
+ onMismatch="DENY"/> <!--4-->
+ </AppenderRef>
+ </Root>
+ <Logger name="org.example" level="TRACE"> <!--2-->
+ <ThresholdFilter level="TRACE"/> <!--3-->
+ </Logger>
+ </Loggers>
+ <MarkerFilter marker="PRIVATE"/> <!--1-->
+</Configuration>
diff --git a/src/site/antora/modules/ROOT/examples/manual/filters/filters.yaml b/src/site/antora/modules/ROOT/examples/manual/filters/filters.yaml
new file mode 100644
index 0000000000..9a4f61f346
--- /dev/null
+++ b/src/site/antora/modules/ROOT/examples/manual/filters/filters.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"
+ ThresholdFilter: # <6>
+ level: "WARN"
+ Loggers:
+ Root:
+ level: "INFO"
+ ThreadsholdFilter: # <3>
+ level: "DEBUG"
+ AppenderRef:
+ ref: "CONSOLE"
+ level: "WARN" # <5>
+ MarkerFilter: # <4>
+ marker: "ALERT"
+ onMatch: "NEUTRAL"
+ onMismatch: "DENY"
+ Logger:
+ name: "org.example"
+ level: "TRACE" # <2>
+ ThresholdFilter:
+ level: "TRACE" # <3>
+ MarkerFilter: # <1>
+ marker: "PRIVATE"
diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc
index ec81d8cc05..b3a7b574d7 100644
--- a/src/site/antora/modules/ROOT/nav.adoc
+++ b/src/site/antora/modules/ROOT/nav.adoc
@@ -18,8 +18,8 @@
* xref:download.adoc[Download]
** xref:runtime-dependencies.adoc[]
** xref:release-notes.adoc[]
-* link:{logging-services-url}/support.html[Support]
-** link:{logging-services-url}/security.html[Security]
+* link:{logging-services-url}/support[Support]
+** link:{logging-services-url}/security[Security]
** xref:thanks.adoc[Thanks]
.Resources
@@ -40,20 +40,23 @@
** xref:manual/thread-context.adoc[]
** xref:manual/scoped-context.adoc[]
** xref:manual/resource-logger.adoc[]
-* xref:manual/configuration.adoc[]
+* Configuration
+** xref:manual/configuration.adoc[Configuration file]
+** xref:manual/appenders.adoc[]
+** xref:manual/layouts.adoc[]
+*** xref:manual/json-template-layout.adoc[]
+** xref:manual/lookups.adoc[]
+** xref:manual/customloglevels.adoc[]
+** xref:manual/filters.adoc[]
+** xref:manual/scripts.adoc[]
+** xref:manual/systemproperties.adoc[]
* xref:manual/usage.adoc[]
* xref:manual/cloud.adoc[]
-* xref:manual/lookups.adoc[]
-* xref:manual/appenders.adoc[]
-* xref:manual/layouts.adoc[]
-** xref:manual/json-template-layout.adoc[]
-* xref:manual/filters.adoc[]
* xref:manual/async.adoc[]
* xref:manual/garbagefree.adoc[]
* xref:manual/extending.adoc[]
+** xref::manual/customconfig.adoc[]
* xref:manual/plugins.adoc[]
-* xref:manual/customconfig.adoc[]
-* xref:manual/customloglevels.adoc[]
* xref:manual/jmx.adoc[]
* xref:manual/logsep.adoc[]
* xref:manual/performance.adoc[]
@@ -70,7 +73,8 @@
* xref:log4j-jpl.adoc[]
* xref:log4j-to-slf4j.adoc[]
* xref:log4j-flume-ng.adoc[]
-* xref:log4j-mongodb.adoc[]
+* xref:log4j-mongodb3.adoc[]
+* xref:log4j-mongodb4.adoc[]
* xref:log4j-iostreams.adoc[]
* xref:log4j-docker.adoc[]
* xref:log4j-spring-cloud-config-client.adoc[]
diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc
index 923d21bb35..24e1318010 100644
--- a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc
@@ -120,7 +120,7 @@ There are also a few system properties that can be used to maintain
application throughput even when the underlying appender cannot keep up
with the logging rate and the queue is filling up. See the details for
system properties
-xref:manual/configuration.adoc#log4j2.AsyncQueueFullPolicy[`log4j2.AsyncQueueFullPolicy`
+xref:manual/systemproperties.adoc#log4j.async.queueFullPolicy.type[`log4j.async.queueFullPolicy.type`
and `log4j2.DiscardThreshold`].
A typical AsyncAppender configuration might look like:
@@ -197,7 +197,7 @@ attribute from AsyncAppender as `LinkedTransferQueue` does not support a
maximum capacity.
|=======================================================================
-[#ConsoleAppender]
+[#consoleappender]
== ConsoleAppender
As one might expect, the ConsoleAppender writes its output to either
@@ -324,7 +324,7 @@ A Failover configuration might look like:
</Configuration>
----
-[#FileAppender]
+[#fileappender]
== FileAppender
The FileAppender is an OutputStreamAppender that writes to the File
@@ -716,7 +716,8 @@ As of Log4j 2.11.0, JDBC support has moved from the existing module
The JDBC Appender configured with a `DataSource` requires JNDI support so as of release 2.17.1
this appender will not function unless `log4j2.enableJndiJdbc=true` is configured as a system property
-or environment variable. See the xref:manual/configuration.adoc#enableJndiJdbc[enableJndiJdbc] system property.
+or environment variable. See the xref:manual/systemproperties.adoc#log4j.jndi.enableJdbc[log4j.jndi.enableJdbc] system
+property.
The JDBCAppender writes log events to a relational database table using
standard JDBC. It can be configured to obtain JDBC connections using a
@@ -2651,7 +2652,7 @@ by the script.
}
statusLogger.trace 'SCRIPT: returning ' + result;
result;
- ]] >
+ ]]>
</Script>
</ScriptCondition>
</Delete>
diff --git a/src/site/antora/modules/ROOT/pages/manual/architecture.adoc b/src/site/antora/modules/ROOT/pages/manual/architecture.adoc
index 4cab5fa7b8..9572238869 100644
--- a/src/site/antora/modules/ROOT/pages/manual/architecture.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/architecture.adoc
@@ -31,6 +31,7 @@ the root LoggerConfig. LoggerConfig objects are created from Logger
declarations in the configuration. The LoggerConfig is associated with
the Appenders that actually deliver the LogEvents.
+[#logger-hierarchy]
=== Logger Hierarchy
The first and foremost advantage of any logging API over plain
@@ -150,6 +151,7 @@ Logger name.
Nevertheless, naming loggers after the class where they are located
seems to be the best strategy known so far.
+[#loggerconfig]
=== LoggerConfig
link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/LoggerConfig.html[`LoggerConfig`]
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
index b997b15267..5fa49fba25 100644
--- a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
@@ -14,1858 +14,1226 @@
See the License for the specific language governing permissions and
limitations under the License.
////
+[id=configuration]
= Configuration
-Inserting log requests into the application code requires a fair amount
-of planning and effort. Observation shows that approximately 4 percent
-of code is dedicated to logging. Consequently, even moderately sized
-applications will have thousands of logging statements embedded within
-their code. Given their number, it becomes imperative to manage these
-log statements without the need to modify them manually.
-
-Configuration of Log4j 2 can be accomplished in 1 of 4 ways:
-
-1. Through a configuration file written in XML, JSON, YAML, or
-properties format.
-2. Programmatically, by creating a ConfigurationFactory and
-Configuration implementation.
-3. Programmatically, by calling the APIs exposed in the Configuration
-interface to add components to the default configuration.
-4. Programmatically, by calling methods on the internal Logger class.
-
-This page focuses primarily on configuring Log4j through a configuration
-file. Information on programmatically configuring Log4j can be found at
-xref:manual/extending.adoc[Extending Log4j 2] and
-xref:manual/customconfig.adoc[Programmatic Log4j Configuration].
-
-All available formats are functionally equivalent. For example, a
-configuration file in XML can be rewritten using the properties format
-(and the opposite) without any loss of functionality. However, the
-hierarchical nature of a Log4j configuration can be captured better in
-formats which naturally support nesting so XML, JSON, and YAML files,
-are usually easier to use.
-
-Note that unlike Log4j 1.x, the public Log4j 2 API does not expose
-methods to add, modify or remove appenders and filters or manipulate the
-configuration in any way.
-
-[#Architecture]
-== Architecture
-
-In part because support for XML was added first, Log4j's configuration is reflected as a tree structure.
-In fact every configuration dialect, including the ConfigurationBuilder, generates a Node for every
-configuration element. A node is a fairly simple structure that contains a set of attributes, a set of
-child nodes and a PluginType. It is important to note that every Node must have a corresponding plugn,
-as the plugin is the component that actually performs the work represented by the node.
-
-Every document type supported by Log4j has a ConfigurationFactory. The factory itself is a Log4j plugin
-that declares what file extensions it supports and what its priority is. Properties have the highest
-precedence with a value of 8, followed by yaml, json and xml. When autoconfiguration is performed Log4j
-will call each of these factories in order to determine which, if any, support the specified configuration
-file format. If one is found that factory will create the corresponding Configuratoin object and pass the
-reference to the configuration data to it.
-
-Every configuration implementation, such as XMLConfiguration, YamlConfiguration, JsonConfiguration, etc.
-has the primary task of converting the configuration text into the Node tree, typically by parsing the
-text with whatever tool is available for that document type. It should be noted that while most of the
-supported document types are inherintly tree structured, the Java properties syntax is not. Because of the
-need to convert the syntax into a Node tree the Java properties syntax used by Log4j required all properties
-follow a naming pattern that made the tree structure clear. As a consequence, the Java Properties format
-tends to be more verbose than using a different document type.
-
-Once the Node tree is created control is delegated to AbstractConfiguration, which convertes the Nodes into
-their respective Java objects using Log4j's Plugin system and provides all the common functionality.
-
-[#Arbiters]
-== Arbiters
-
-In some situations it is desirable to have a single logging configuration that can be used in any
-deployment environment. For example, it may be necessary to have a different default logging level in
-production then in development. Another case might be where one type of appender is used when running
-natively but another is used when deployed to a docker container. One way to handle that is to use
-a tool such as Spring Cloud Config Server that can be environment aware and serve a different file for
-each environment. Another option is to include Arbiters in the configuration.
-
-An Arbiter is a Log4j plugin that has the job of determining whether other configured elements should be
-included in the generated configuration. While all other "Core" plugins are designed to execute as part of
-Log4j's runtime logic Arbiters execute after the Node tree has been constructed but before the tree is
-converted to a configuration. An Arbiter is a Node itself which is always removed from the Node tree
-before it the tree is processed. All an arbiter really does is provide a method that returns a boolean
-result that determines whether the child nodes of the arbiter should remain in the configuration or be
-pruned.
-
-Arbiters may occur anywhere an element is allowed in the configuration. So an Aribiter could encapsulate
-something as simple as a single property declaration or a whole set of Appenders or Loggers. Arbiters
-may also be nested although Arbiters that are the descendant of another arbiter will only be evalued if the
-ancestor returned true. The child elements of an Arbiter must be valid elements for whatever element is
-the parent of the Arbiter.
-
-This example shows two Arbiters configured that will include either a Console Appender or a List Appender
-depending on whether the value of the env System Property is "dev" or "prod".
+Logging is a standard method for monitoring the health of an application and diagnosing problems that may arise within it.
+Even moderately sized applications can contain thousands of logging statements.
-[source,xml]
-----
-<Configuration name="ConfigTest" status="ERROR" monitorInterval="5">
- <Appenders>
-
- <SystemPropertyArbiter propertyName="env" propertyValue="dev">
- <Console name="Out">
- <PatternLayout pattern="%m%n"/>
- </Console>
- </SystemPropertyArbiter>
- <SystemPropertyArbiter propertyName="env" propertyValue="prod">
- <List name="Out">
- </List>
- </SystemPropertyArbiter>
-
- </Appenders>
- <Loggers>
- <Logger name="org.apache.test" level="trace" additivity="false">
- <AppenderRef ref="Out"/>
- </Logger>
- <Root level="error">
- <AppenderRef ref="Out"/>
- </Root>
- </Loggers>
-</Configuration>
-----
-
-Normally Arbiters act in isolation from other Arbiters. That is, the outcome of one Arbiter will not
-impact any other Arbiters. This can be cumbersome when you simply want to use one of a set of choices. A
-special plugin named "Select" can be used in this case. Each element under the Select is required to be
-an Arbiter. The first Arbiter that returns a true value will be the one used while others are ignored.
-If no Arbiter returns true a DefaultAtrbiter may be configured with the default configuration elements.
-The DefaultArbiter is an Arbiter that always returns true, so using it outside of a Select would result in
-its configured elements always being included just as if it hadn't been present.
-
-This example shows an Arbiter that uses Javascript residing in a separate file to determine whether to
-include the Console Appender. If the result is false then a List Appender will be included.
+To decide which of these statements will be logged and where, users need to configure Log4j Core in one of two ways:
-[source,xml]
-----
-<Configuration name="ConfigTest" status="ERROR" monitorInterval="5">
- <Appenders>
- <Select>
- <ScriptArbiter>
- <ScriptFile language="JavaScript" path="src/test/resources/scripts/prodtest.js" charset="UTF-8" />
- <Console name="Out">
- <PatternLayout pattern="%m%n"/>
- </Console>
- </ScriptArbiter>
- <DefaultArbiter>
- <List name="Out">
- </List>
- </DefaultArbiter>
- </Select>
- </Appenders>
- <Loggers>
- <Logger name="org.apache.test" level="trace" additivity="false">
- <AppenderRef ref="Out"/>
- </Logger>
- <Root level="error">
- <AppenderRef ref="Out"/>
- </Root>
- </Loggers>
-</Configuration>
-----
-
-Natively Log4j contains the SystemProperty Arbiter that can evaluate whether to include elements based on
-whether a SystemProperty is non-null or has a specific value, a ClassArbiter that makes its decision
-based on whether the specified class is present, and a ScriptArbiter that makes its decision based
-on the result of the script configured with it.
-
-For Spring Boot users an Arbiter named <code>SpringProfile</code> has been provided. The specified profiles
-are evaluated by Spring's <code>Environment.acceptsProfiles()</code> method, so any expressions it supports
-may be used as the name attribute.
-
-This example will use a Console Appender when the Spring profile is "dev" or "staging" and a List
-Appender when the active profile is "prod".
+* through a <<configuration-file>>.
+Since version 2.0, the configuration file format has been considered part of the public API and has remained stable across significant version upgrades.
-[source,xml]
+* through xref:manual/customconfig.adoc[Programmatic Configuration], which provides a larger spectrum of possible customizations but might require code changes during version upgrades.
+
+[NOTE]
+====
+To prevent a chicken-and-egg problem, users can only supply some configuration options (e.g., the configuration file location) through xref:manual/systemproperties.adoc[configuration properties].
+====
+
+[#configuration-file]
+== Configuration file
+
+Users can configure Log4j Core using different file formats.
+Log4j includes XML, JSON, YAML, and Java properties formats factories.
+
+As detailed in the table below, some configuration formats require additional dependencies on the classpath.
+
+include::partial$configuration-file-format-deps.adoc[]
+
+[WARNING]
+====
+The format of the configuration file changed between Log4j{nbsp}1 and Log4j{nbsp}2.
+Files in the Log4j{nbsp}1 format are ignored by default.
+
+To enable partial support for old configuration formats, see xref:manual/migration.adoc#enabling-the-log4j-1-x-bridge[Enabling the Log4j{nbsp}1 bridge].
+====
+
+[id=automatic-configuration]
+=== [[AutomaticConfiguration]] Configuration file location
+
+Upon initialization of a new logger context, Log4j assigns it a context name and scans the following **classpath** locations for a configuration file:
+
+. Files named `log4j2-test<contextName>.<extension>`
+. Files named `log4j2-test.<extension>`,
+. Files named `log4j2<contextName>.<extension>`
+. Files named `log4j2.<extension>`,
+. If no configuration file is found, Log4j uses the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/DefaultConfiguration[DefaultConfiguration], and the status logger prints a warning.
+The default configuration prints all messages less specific than
+xref:manual/systemproperties.adoc#log4j.configuration.level[log4j.configuration.level]
+to the console.
+
+[CAUTION]
+====
+The configuration files prefixed by `log4j2-test` should only be used on the test classpath.
+
+If multiple configuration files in the same category are found, Log4j uses a deterministic order to choose one of them (see link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Order[@Order]).
+
+Nevertheless:
+
+* If you're developing an app, don't use config files with different extensions.
+* If you're developing a library, only add config files to your test classpath.
+====
+
+The `<contextName>` and `<extension>` placeholders above have the following meaning
+
+<contextName>:: depends on the runtime environment in which Log4j runs:
+
+* for standalone Java SE applications, it is a random identifier,
+* for web applications, it is derived from the application descriptor.
+See
+link:../../jakarta/log4j-jakarta-web.html#config[Log4j Jakarta
+ Web application configuration] for more details.
+
+<extension>:: must be one of the file extensions assigned to a configuration file format:
++
+[cols="1,1"]
+|===
+| Configuration file format | Extension
+
+| XML
+| `xml`
+
+| JSON
+| `json` or `jsn`
+
+| YAML
+| `yaml` or `yml`
+
+|Java properties
+| `properties`
+|===
+
+[NOTE]
+====
+It is also possible to override the location of the configuration file using the
+xref:manual/systemproperties.adoc#log4j.configuration.location[log4j.configuration.location]
+configuration property.
+In this case, Log4j will guess the configuration file format from the provided configuration file extension or use the default configuration factory if the extension is unknown.
+
+See xref:manual/systemproperties.adoc#log4j.configuration.location[log4j.configuration.location] for details.
+====
+
+[id=configuration-syntax]
+=== [[ConfigurationSyntax]] Syntax
+
+The Log4j runtime is composed of xref:manual/plugins.adoc[plugins], which are like beans in the Spring Framework and Java EE.
+Appenders, layouts, filters, configuration loaders, and similar components are all accessed as plugins.
+
+All configuration files are represented internally as a tree of
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Node[Node]s, which is translated into a tree of Log4j plugins.
+The tree's root creates a link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration[Configuration] object.
+
+A node is a relatively simple structure representing a single Log4j plugin (see xref:plugin-reference.adoc[] for a complete list), such as an appender, layout, or logger configuration.
+
+Each node has:
+
+* a set of simple string key-value pairs called **attributes**.
+Attributes are **matched by name** against the list of available configuration options of a Log4j plugin.
+
+* The **plugin type** attribute specifies the kind of Log4j plugin we want to instantiate.
+
+* A set of child nodes called **nested elements**.
+They are **matched by type** against the list of nested components a plugin accepts.
+
+Log4j maps the concepts above to the specifics of the configuration format as follows:
+
+[tabs]
+=====
+XML::
++
+Since XML was the original configuration format developed, the mapping from configuration nodes and XML elements is trivial:
++
+* Each configuration node is represented by an XML element.
+* Each configuration attribute is represented by an XML attribute.
+* The **plugin type** of a node is equal to the name of the XML tag.
+* Each configuration nested element is represented by a nested XML element.
++
+[NOTE]
+====
+There is an alternative XML configuration format called "XML strict format" that is activated by setting the `strict` attribute of the main `<Configuration>` element to `true`.
+It allows users to use any tag names as long as they provide the plugin type using a `type` property.
+
+The _XML strict format_ was conceived as a simplified XML format that can be validated by an XML schema but has fallen into disuse: nowadays, the automatically generated schemas published at https://logging.apache.org/xml/ns/
+offer a better alternative and allow users to use a more concise syntax.
+====
+
+JSON::
++
+In the JSON configuration format:
++
+[id=configuration-with-json]
+====
+* Each configuration node is represented by a JSON object,
+* JSON properties of type string, number, or boolean are mapped to node attributes.
+* JSON properties of type object or array represent nested configuration elements.
+* The **plugin type** of a JSON object is given by:
+** the value of the `type` key, if present,
+** or the key associated with the JSON object otherwise.
+** If the JSON object representing the node is part of an array, the key associated with the JSON array is used.
+====
++
+[TIP]
+====
+If you need to specify multiple plugins of the same type, you can use JSON arrays.
+The snippet below represents two plugins of type `File`.
+
+[source,json]
----
-<Configuration name="ConfigTest" status="ERROR" monitorInterval="5">
- <Appenders>
-
- <SpringProfile name="dev | staging">
- <Console name="Out">
- <PatternLayout pattern="%m%n"/>
- </Console>
- </SpringProfile>
- <SpringProfile name="prod">
- <List name="Out">
- </List>
- </SpringProfile>
-
- </Appenders>
- <Loggers>
- <Logger name="org.apache.test" level="trace" additivity="false">
- <AppenderRef ref="Out"/>
- </Logger>
- <Root level="error">
- <AppenderRef ref="Out"/>
- </Root>
- </Loggers>
-</Configuration>
-----
-
-[#AutomaticConfiguration]
-== Automatic Configuration
-
-Log4j has the ability to automatically configure itself during
-initialization. When Log4j starts it will locate all the
-ConfigurationFactory plugins and arrange them in weighted order from
-highest to lowest. As delivered, Log4j contains four
-ConfigurationFactory implementations: one for JSON, one for YAML, one
-for properties, and one for XML.
-
-1. Log4j will inspect the `"log4j2.configurationFile"` system property
-and, if set, will attempt to load the configuration using the
-`ConfigurationFactory` that matches the file extension. Note that this
-is not restricted to a location on the local file system and may contain
-a URL.
-2. If no system property is set the properties ConfigurationFactory
-will look for `log4j2-test.properties` in the classpath.
-3. If no such file is found the YAML ConfigurationFactory will look for
-`log4j2-test.yaml` or `log4j2-test.yml` in the classpath.
-4. If no such file is found the JSON ConfigurationFactory will look for
-`log4j2-test.json` or `log4j2-test.jsn` in the classpath.
-5. If no such file is found the XML ConfigurationFactory will look for
-`log4j2-test.xml` in the classpath.
-6. If a test file cannot be located the properties ConfigurationFactory
-will look for `log4j2.properties` on the classpath.
-7. If a properties file cannot be located the YAML ConfigurationFactory
-will look for `log4j2.yaml` or `log4j2.yml` on the classpath.
-8. If a YAML file cannot be located the JSON ConfigurationFactory will
-look for `log4j2.json` or `log4j2.jsn` on the classpath.
-9. If a JSON file cannot be located the XML ConfigurationFactory will
-try to locate `log4j2.xml` on the classpath.
-10. If no configuration file could be located the `DefaultConfiguration`
-will be used. This will cause logging output to go to the console.
-
-An example application named `MyApp` that uses log4j can be used to
-illustrate how this is done.
-
-[source,java]
-----
-import com.foo.Bar;
-
-// Import log4j classes.
-import org.apache.logging.log4j.Logger;
-import org.apache.logging.log4j.LogManager;
-
-public class MyApp {
-
- // Define a static logger variable so that it references the
- // Logger instance named "MyApp".
- private static final Logger logger = LogManager.getLogger(MyApp.class);
-
- public static void main(final String... args) {
-
- // Set up a simple configuration that logs on the console.
-
- logger.trace("Entering application.");
- Bar bar = new Bar();
- if (!bar.doIt()) {
- logger.error("Didn't do it.");
- }
- logger.trace("Exiting application.");
+{
+ "File": [
+ {
+ "name": "file1"
+ },
+ {
+ "name": "file2"
}
+ ]
}
----
+====
+
+YAML::
++
+In the YAML configuration format:
++
+[id=configuration-with-yaml]
+====
+* A YAML mapping represents each configuration node,
+* YAML properties of scalar type are mapped to node attributes.
+* YAML properties of collection type are used to represent nested configuration elements.
+* The **plugin type** of a YAML mapping is given by:
+** the value of the `type` key, if present,
+** or the key associated with the YAML mapping otherwise.
+** If the YAML mapping representing the node is part of a YAML block sequence, the key associated with the YAML sequence is used.
+====
++
+[TIP]
+====
+If you need to specify multiple plugins of the same type, you can use YAML block sequences.
+The snippet below represents two plugins of type `File`.
+
+[source,yaml]
+----
+File:
+ - name: file1
+ - name: file2
+----
+====
+
+Java properties::
++
+In the Java properties configuration format:
++
+[id=configuration-with-properties]
+====
+* Properties that share a common prefix (e.g., `appender.foo`) are mapped to a subtree of the configuration node tree.
+* Configuration attributes are specified by appending the property's name (e.g., `name`) to the prefix of the node, separated by a dot (e.g., `appender.foo.name`).
+* The **plugin type** must be specified as an attribute named `type`.
+* Nested elements are created by:
+** Choosing an arbitrary id for the nested component (e.g., `<0>`)
+** Appending the id to the prefix of the parent component (e.g., `appender.foo.<0>`)
+** Specifying the type of the nested plugin by assigning a `type` attribute (e.g., `appender.foo.<0>.type`)
+====
++
+[NOTE]
+====
+Nested components use the assigned ID for sorting purposes only.
+====
+=====
+
+See also <<format-specific-notes>> for exceptions to the rules above.
+
+[id=main-configuration-elements]
+=== Main configuration elements
+
+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.
+Their configuration must specify which level of messages they log and to which appenders they send the messages.
++
+See <<configuring-loggers>> for details.
+
+[id=configuring-appenders]
+[[Appenders]] Appenders::
++
+Appenders 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.
-`MyApp` begins by importing log4j related classes. It then defines a
-static logger variable with the name `MyApp` which happens to be the
-fully qualified name of the class.
+A moderately complex configuration might look like this:
-`MyApp` uses the `Bar` class defined in the package`com.foo`.
+[tabs]
+====
+XML::
++
+[source,xml]
+----
+include::example$manual/configuration/main-elements.xml[lines=1;18..-1]
+----
-[source,java]
+JSON::
++
+[source,json]
+----
+include::example$manual/configuration/main-elements.json[]
----
-package com.foo;
-import org.apache.logging.log4j.Logger;
-import org.apache.logging.log4j.LogManager;
-public class Bar {
- static final Logger logger = LogManager.getLogger(Bar.class.getName());
+YAML::
++
+[source,yaml]
+----
+include::example$manual/configuration/main-elements.yaml[lines=17..-1]
+----
- public boolean doIt() {
- logger.entry();
- logger.error("Did it again!");
- return logger.exit(false);
- }
-}
+Java properties::
++
+[source,properties]
----
+include::example$manual/configuration/main-elements.properties[lines=17..-1]
+----
+====
-Log4j will provide a default configuration if it cannot locate a
-configuration file. The default configuration, provided in the
-DefaultConfiguration class, will set up:
+<1> Configures a console appender named `CONSOLE` with a pattern layout.
+<2> Configures a file appender named `MAIN` with a JSON template layout.
+<3> Configures a file appender named `DEBUG_LOG` with a pattern layout.
+<4> Configures the root logger at level `INFO` and connects it to the `CONSOLE` and `MAIN` appenders.
+The `CONSOLE` appender will only log messages less specific than `WARN`.
+<5> Configures a logger named `"org.example"` at level `DEBUG` and connects it to the `DEBUG_LOG` appender.
+The logger is configured to forward messages to its parent (the root appender).
-* A
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/ConsoleAppender.html[`ConsoleAppender`]
-attached to the root logger.
-* A
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternLayout.html[`PatternLayout`]
-set to the pattern "%d\{HH:mm:ss.SSS} [%t] %-5level %logger\{36} -
-%msg%n" attached to the ConsoleAppender
+Using the above configuration, the list of appenders that will be used for each log event depends only on the level of the event and the name of the logger, as in the table below:
-Note that by default Log4j assigns the root logger to `Level.ERROR`.
+[cols="2m,2m,5"]
+|===
+| Logger name | Log event level | Appenders
-The output of MyApp would be similar to:
+| org.example.foo
+| WARN
+| `CONSOLE`, `MAIN`, `DEBUG_LOG`
-....
-17:13:01.540 [main] ERROR com.foo.Bar - Did it again!
-17:13:01.540 [main] ERROR MyApp - Didn't do it.
-....
+| org.example.foo
+| DEBUG
+| `MAIN`, `DEBUG_LOG`
-As was described previously, Log4j will first attempt to configure
-itself from configuration files. A configuration equivalent to the
-default would look like:
+| org.example.foo
+| TRACE
+| _none_
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="WARN">
- <Appenders>
- <Console name="Console" target="SYSTEM_OUT">
- <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
- </Console>
- </Appenders>
- <Loggers>
- <Root level="error">
- <AppenderRef ref="Console"/>
- </Root>
- </Loggers>
-</Configuration>
-----
-
-Once the file above is placed into the classpath as log4j2.xml you will
-get results identical to those listed above. Changing the root level to
-trace will result in results similar to:
-
-....
-17:13:01.540 [main] TRACE MyApp - Entering application.
-17:13:01.540 [main] TRACE com.foo.Bar - entry
-17:13:01.540 [main] ERROR com.foo.Bar - Did it again!
-17:13:01.540 [main] TRACE com.foo.Bar - exit with (false)
-17:13:01.540 [main] ERROR MyApp - Didn't do it.
-17:13:01.540 [main] TRACE MyApp - Exiting application.
-....
-
-Note that status logging is disabled when the default configuration is
-used.
-
-[#Configuration_From_a_URI]
-== Configuration From a URI
-
-When `log4j2.configurationFile` references a URL, Log4j will first determine if the URL reference
-a file using the file protocol. If it does Log4j will validate that the file URL is valid and continue
-processing as previously described. If it contains a protocol other than file then Log4j will inspect
-the value of the `log4j2.Configuration.allowedProtocols` system property. If the provided list
-contains the protocol specified then Log4j will use the URI to locate the specified configuration file. If
-not an exception will be thrown and an error message will be logged. If no value is provided for the
-system property it will default to "https". Use of any protocol other than "file" can be prevented by
-setting the system property value to "_none". This value would be an invalid protocol so cannot conflict
-with any custom protocols that may be present.
-
-Log4j supports access to remote URLs that require authentication. Log4j supports basic authentication
-out of the box. If the `log4j2.Configuration.username` and `log4j2.Configuration.password`
-are specified those values will be used to perform the authentication. If the password is encrypted a custom
-password decryptor may be supplied by specifying the fully qualified class name in the
-`log4j2.Configuration.passwordDecryptor` system property. A custom
-`AuthenticationProvider` may be used by setting the
-`log4j2.Configuration.authenticationProvider` system property to the fully qualified class name
-of the provider.
-
-[#Additivity]
-== Additivity
-
-Perhaps it is desired to eliminate all the TRACE output from everything
-except `com.foo.Bar`. Simply changing the log level would not accomplish
-the task. Instead, the solution is to add a new logger definition to the
-configuration:
+| com.example
+| WARN
+| `CONSOLE`, `MAIN`
-[source,xml]
-----
-<Configuration>
- <!-- ... -->
- <Logger name="com.foo.Bar" level="TRACE"/>
- <Root level="ERROR">
- <AppenderRef ref="STDOUT"/>
- </Root>
-</Configuration>
-----
+| com.example
+| INFO
+| `MAIN`
+
+| com.example
+| DEBUG
+| _none_
+
+|===
+
+[id=additional-configuration-elements]
+=== Additional configuration elements
+
+A Log4j Core configuration file can also contain these configuration elements:
+
+CustomLevels::
++
+Log4j allows the configuration of custom log-level names.
++
+See xref:manual/customloglevels.adoc[Custom log level configuration] for details.
+
+Filters::
++
+Users can add Components to loggers, appender references, appenders, or the global configuration object to provide additional filtering of log events.
++
+See xref:manual/filters.adoc[Filter configuration] for details.
+
+Properties::
++
+Represent a set of reusable configuration values for property substitution.
++
+See <<property-substitution>> for details.
+
+Scripts::
++
+Scripts are a container for JSR 223 scripts that users can use in other Log4j components.
++
+For details, see xref:manual/scripts.adoc[Scripts configuration].
+
+[id=global-configuration-attributes]
+=== Global configuration attributes
+
+The main `Configuration` element has a set of attributes that can be used to tune how the configuration file is used.
+The principal attributes are listed below.
+See xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Configuration[Plugin reference] for a complete list.
+
+[id=configuration-attribute-monitorInterval]
+==== [[AutomaticReconfiguration]] `monitorInterval`
+
+[cols="1h,5"]
+|===
+| Type | `int`
+| Default value | `0`
+|===
+
+Determines the polling interval used by Log4j to check for changes to the configuration file.
+If a change in the configuration file is detected, Log4j automatically reconfigures the logger context.
+If set to `0`, polling is disabled.
+
+[CAUTION]
+====
+Log4j Core is designed with reliability in mind, unlike other logging backends.
+
+During a reconfiguration process, no messages are lost.
+
+Unless the new configuration file removes an appender, the old ones work without interruption.
+
+Some changed appender options will be **ignored** during reconfiguration.
+For example, appenders that need to close resources, like the append mode used to open a file, will ignore such options.
-With this configuration all log events from `com.foo.Bar` will be
-recorded while only error events will be recorded from all other
-components.
+To modify these options during a reconfiguration, you also need to change the resource used by the appender (e.g., the file name used by a file appender).
+====
-In the previous example all the events from `com.foo.Bar` were still
-written to the Console. This is because the logger for `com.foo.Bar` did
-not have any appenders configured while its parent did. In fact, the
-following configuration
+[id=configuration-attribute-status]
+==== `status`
+[cols="1h,5"]
+|===
+| Type
+| link:../javadoc/log4j-api/org/apache/logging/log4j/Level.html[LEVEL]
+
+| Status
+| **DEPRECATED**
+
+| Default value
+| link:../../2.x/manual/systemproperties.html#log4j.sta.statusLoggerLevel[log4j2.statusLoggerLevel]
+|===
+
+Overrides the logging level of the status logger.
+
+WARNING: Since 2.24.0 this attribute is deprecated and should be replaced with the
+link:../../2.x/manual/systemproperties.html#log4j.sta.statusLoggerLevel[log4j2.statusLoggerLevel]
+configuration property.
+
+[id=configuration-elements-filters]
+==== Filters
+
+See xref:manual/filters.adoc#filters[Filters] for additional filtering capabilities that can be applied to the global configuration object.
+
+[id=configuring-loggers]
+=== [[Loggers]] Loggers
+
+Log4j 2 contains multiple types of logger configurations that can be added to the `Loggers` element of the configuration:
+
+`Root`:: is the logger that receives all events that do not have a more specific logger defined.
++
+See also xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-LoggerConfig-RootLogger[Plugin reference].
+
+`AsyncRoot`:: is an alternative implementation of the root logger used in the xref:manual/async.adoc#MixedSync-Async[mixed synchronous and asynchronous mode].
++
+See also xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-async-AsyncLoggerConfig-RootLogger[Plugin reference].
+
+`Logger`:: the most common logger kind, which collects log events from itself and all the children loggers, which do not have an explicit configuration (see xref:manual/architecture.adoc#logger-hierarchy[logger hierarchy]).
++
+See also xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-LoggerConfig[Plugin Reference].
+
+`AsyncLogger`:: the equivalent of `Logger`, used in the xref:manual/async.adoc#MixedSync-Async[mixed synchronous and asynchronous mode].
++
+See also xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-async-AsyncLoggerConfig[Plugin Reference].
+
+There **must** be at least a `Root` or `AsyncRoot` element in every configuration file.
+Other logger configurations are optional.
+
+Every
+link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[Logger]
+in your application is assigned to one of these logger configurations (see
+xref:manual/architecture.adoc#loggerconfig[architecture]), which determines the events that will be logged and those that won't.
+
+Let's start with an example of logger configuration:
+
+[tabs]
+====
+XML::
++
[source,xml]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="WARN">
- <Appenders>
- <Console name="Console" target="SYSTEM_OUT">
- <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="com.foo.Bar" level="trace">
- <AppenderRef ref="Console"/>
- </Logger>
- <Root level="error">
- <AppenderRef ref="Console"/>
- </Root>
- </Loggers>
-</Configuration>
-----
-
-would result in
-
-....
-17:13:01.540 [main] TRACE com.foo.Bar - entry
-17:13:01.540 [main] TRACE com.foo.Bar - entry
-17:13:01.540 [main] ERROR com.foo.Bar - Did it again!
-17:13:01.540 [main] TRACE com.foo.Bar - exit (false)
-17:13:01.540 [main] TRACE com.foo.Bar - exit (false)
-17:13:01.540 [main] ERROR MyApp - Didn't do it.
-....
-
-Notice that the trace messages from `com.foo.Bar` appear twice. This is
-because the appender associated with logger `com.foo.Bar` is first used,
-which writes the first instance to the Console. Next, the parent of
-`com.foo.Bar`, which in this case is the root logger, is referenced. The
-event is then passed to its appender, which is also writes to the
-Console, resulting in the second instance. This is known as additivity.
-While additivity can be quite a convenient feature (as in the first
-previous example where no appender reference needed to be configured),
-in many cases this behavior is considered undesirable and so it is
-possible to disable it by setting the additivity attribute on the logger
-to false:
+include::example$manual/configuration/loggers.xml[tag=loggers]
+----
-[source,xml]
+JSON::
++
+[source,json]
+----
+include::example$manual/configuration/loggers.json[tag=loggers]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="WARN">
- <Appenders>
- <Console name="Console" target="SYSTEM_OUT">
- <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="com.foo.Bar" level="trace" additivity="false">
- <AppenderRef ref="Console"/>
- </Logger>
- <Root level="error">
- <AppenderRef ref="Console"/>
- </Root>
- </Loggers>
-</Configuration>
-----
-
-Once an event reaches a logger with its additivity set to false the
-event will not be passed to any of its parent loggers, regardless of
-their additivity setting.
-
-[#AutomaticReconfiguration]
-== Automatic Reconfiguration
-
-When configured from a File, Log4j has the ability to automatically
-detect changes to the configuration file and reconfigure itself. If the
-`monitorInterval` attribute is specified on the configuration element
-and is set to a non-zero value then the file will be checked the next
-time a log event is evaluated and/or logged and the monitorInterval has
-elapsed since the last check. The example below shows how to configure
-the attribute so that the configuration file will be checked for changes
-only after at least 30 seconds have elapsed. The minimum interval is 5
-seconds.
-[source,xml]
+YAML::
++
+[source,yaml]
+----
+include::example$manual/configuration/loggers.yaml[tag=loggers]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration monitorInterval="30">
-...
-</Configuration>
-----
-
-[#ChainsawSupport]
-== Chainsaw can automatically process your log files (Advertising appender configurations)
-
-Log4j provides the ability to 'advertise' appender configuration details
-for all file-based appenders as well as socket-based appenders. For
-example, for file-based appenders, the file location and the pattern
-layout in the file are included in the advertisement. Chainsaw and other
-external systems can discover these advertisements and use that
-information to intelligently process the log file.
-
-The mechanism by which an advertisement is exposed, as well as the
-advertisement format, is specific to each Advertiser implementation. An
-external system which would like to work with a specific Advertiser
-implementation must understand how to locate the advertised
-configuration as well as the format of the advertisement. For example, a
-'database' Advertiser may store configuration details in a database
-table. An external system can read that database table in order to
-discover the file location and the file format.
-
-Log4j provides one Advertiser implementation, a 'multicastdns'
-Advertiser, which advertises appender configuration details via IP
-multicast using the http://jmdns.sourceforge.net library.
-
-Chainsaw automatically discovers log4j's multicastdns-generated
-advertisements and displays those discovered advertisements in
-Chainsaw's Zeroconf tab (if the jmdns library is in Chainsaw's
-classpath). To begin parsing and tailing a log file provided in an
-advertisement, just double-click the advertised entry in Chainsaw's
-Zeroconf tab. Currently, Chainsaw only supports FileAppender
-advertisements.
-
-To advertise an appender configuration:
-
-* Add the JmDns library from http://jmdns.sourceforge.net to the
-application classpath
-* Set the 'advertiser' attribute of the configuration element to
-'multicastdns'
-* Set the 'advertise' attribute on the appender element to 'true'
-* If advertising a FileAppender-based configuration, set the
-'advertiseURI' attribute on the appender element to an appropriate URI
-
-FileAppender-based configurations require an additional 'advertiseURI'
-attribute to be specified on the appender. The 'advertiseURI' attribute
-provides Chainsaw with information on how the file can be accessed. For
-example, the file may be remotely accessible to Chainsaw via ssh/sftp by
-specifying a Commons VFS (http://commons.apache.org/proper/commons-vfs/)
-sftp:// URI, an http:// URI may be used if the file is accessible
-through a web server, or a file:// URI can be specified if accessing the
-file from a locally-running instance of Chainsaw.
-
-Here is an example advertisement-enabled appender configuration which
-can be used by a locally-running Chainsaw to automatically tail the log
-file (notice the file:// advertiseURI):
-
-*Please note, you must add the JmDNS library mentioned above.*
-[source,xml]
+Java properties::
++
+[source,properties]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration advertiser="multicastdns">
- ...
- <Appenders>
- <File name="File1" fileName="output.log" bufferedIO="false" advertiseURI="file://path/to/output.log" advertise="true">
- ...
- </File>
- </Appenders>
-</Configuration>
+include::example$manual/configuration/loggers.properties[tags=loggers]
----
+====
+
+In the example above, we have four logger configurations.
+They differ from each other regarding the level of log messages that they allow, whether
+xref:manual/layouts.adoc#location-information[location information]
+will be printed, and which appenders will be used.
+The table below summarizes the effects of each logger configuration:
+
+.Logger configurations
+[cols="1,2,2,2,2,5"]
+|===
+|
+| <<logger-attributes-name,Logger name>>
+| <<logger-attributes-level,Level>>
+| <<logger-attributes-additivity,Additivity>>
+| <<logger-attributes-includeLocation,Includes location>>
+h| Appenders used
+
+| 1
+| _empty_
+| `INFO`
+| N/A
+| _default_
+| `APPENDER1`
+
+| 2
+| `org.example.no_additivity`
+| `INFO`
+
+(inherited)
+| `false`
+| _default_
+| `APPENDER2`
+
+| 3
+| `org.example.no_location`
+| `INFO`
+
+(inherited)
+| `true`
+| `false`
+| `APPENDER1` and `APPENDER3`
+
+| 4
+| `org.example.level`
+| `DEBUG`
+| `true`
+| _default_
+| `APPENDER1` and `APPENDER4`
+|===
+
+In the following part of this section, we explain in detail all the available options for logger configurations:
+
+[id=logger-attributes-name]
+==== `name`
+
+[cols="1h,5"]
+|===
+| Type
+| `String`
+
+| Applies to
+| `Logger` and `AsyncLogger`
+|===
-[#ConfigurationSyntax]
-== Configuration Syntax
+Specifies the name of the logger configuration.
-As of version 2.9, for security reasons, Log4j does not process DTD in
-XML files. If you want to split the configuration in multiple files, use
-link:#XInclude[XInclude] or link:#CompositeConfiguration[Composite
-Configuration].
+Since loggers are usually named using fully qualified class names, this value usually contains the fully qualified name of a class or a package.
-As the previous examples have shown as well as those to follow, Log4j
-allows you to easily redefine logging behavior without needing to modify
-your application. It is possible to disable logging for certain parts of
-the application, log only when specific criteria are met such as the
-action being performed for a specific user, route output to Flume or a
-log reporting system, etc. Being able to do this requires understanding
-the syntax of the configuration files.
+[id=logger-attributes-additivity]
+==== [[Additivity]] `additivity`
-The configuration element in the XML file accepts several attributes:
+[cols="1h,5"]
+|===
+| Type | `boolean`
+| Default value | `true`
+| Applies to | `Logger` and `AsyncLogger`
+|===
+
+If `true` (default), all the messages this logger receives will also be transmitted to its
+xref:manual/architecture.adoc#logger-hierarchy[parent logger]).
+
+[id=logger-attributes-level]
+==== `level`
+
+[cols="1h,5"]
+|===
+| Type
+| link:../javadoc/log4j-api/org/apache/logging/log4j/Level.html[Level]
+
+| Default value
+a|
+* xref:manual/systemproperties.adoc#log4j.configuration.level[log4j.configuration.level],
+for `Root` and `AsyncRoot`,
+* inherited from the
+xref:manual/architecture.adoc#logger-hierarchy[parent logger],
+for `Logger` and `AsyncLogger`.
+|===
+
+Specifies the level threshold that a log event must have to be logged.
+Log events that are more specific than this setting will be filtered out.
+
+See also xref:manual/filters.adoc#filters[Filters] if you require additional filtering.
+
+[id=logger-attributes-includeLocation]
+==== `includeLocation`
-[cols="1m,5a"]
+[cols="1h,5"]
|===
-|Attribute Name |Description
-
-|advertiser
-|(Optional) The Advertiser plugin name which will be used to
-advertise individual FileAppender or SocketAppender configurations. The
-only Advertiser plugin provided is "multicastdns".
-
-|dest
-|Either "err" for stderr, "out" for stdout, a file path, or a URL.
-
-|monitorInterval
-|The minimum amount of time, in seconds, that must
-elapse before the file configuration is checked for changes.
-
-|name
-|The name of the configuration.
-
-|schema
-|Identifies the location for the classloader to located the XML
-Schema to use to validate the configuration. Only valid when strict is
-set to true. If not set no schema validation will take place.
-
-|shutdownHook
-|Specifies whether or not Log4j should automatically
-shutdown when the JVM shuts down. The shutdown hook is enabled by
-default but may be disabled by setting this attribute to "disable"
-
-|shutdownTimeout
-|Specifies how many milliseconds appenders and
-background tasks will get to shutdown when the JVM shuts down. Default
-is zero which mean that each appender uses its default timeout, and
-don't wait for background tasks. Not all appenders will honor this, it
-is a hint and not an absolute guarantee that the shutdown procedure will
-not take longer. Setting this too low increase the risk of losing
-outstanding log events not yet written to the final destination. See
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/LoggerContext.html$%7Besc.hash%7Dstop(long,%20java.util.concurrent.TimeUnit)[LoggerContext.stop(long,
-java.util.concurrent.TimeUnit)]. (Not used if `shutdownHook` is set to
-"disable".)
-
-|status
-|The level of internal Log4j events that should be logged to the console.
-Valid values for this attribute are "off", "trace", "debug", "info", "warn",
-"error", "fatal", and "all". Log4j will log details about initialization,
-rollover and other internal actions to the status logger. Setting
-`status="trace"` is one of the first tools available to you if you need
-to troubleshoot log4j.
-
-(Alternatively, setting system property `log4j2.debug` will also print
-internal Log4j2 logging to the console, including internal logging that
-took place before the configuration file was found.)
-
-|strict
-|Enables the use of the strict XML format. Not supported in JSON
-configurations.
-
-|verbose
-|Enables diagnostic information while loading plugins.
+| Type
+| `boolean`
+
+| Default value
+a|
+* `false`, if an asynchronous `ContextSelector` is used.
+* Otherwise,
+** `true` for `Root` and `Logger`,
+** `false` for `AsyncRoot` and `AsyncLogger`.
+
+See
+xref:manual/systemproperties.adoc#log4j.loggerContext.selector[log4j.loggerContext.selector]
+for more details.
|===
-[[XML]]
-=== Configuration with XML
+Specifies whether Log4j is allowed to compute location information.
+If set to `false`, Log4j will not attempt to infer the location of the logging call unless said location was provided explicitly using one of the available
+https://logging.apache.org/log4j/2.x/javadoc/log4j-api/org/apache/logging/log4j/LogBuilder.html[LogBuilder
+.withLocation()]
+methods.
-Log4j can be configured using two XML flavors; concise and strict.
+See xref:manual/layouts.adoc#location-information[Location information] for more details.
-=== Concise Syntax
+[id=logger-elements-appenderrefs]
+==== Appender references
-The concise format makes configuration very easy as the element names match
-the components they represent however it cannot be validated with an XML
-schema. For example, the ConsoleAppender is configured by declaring an
-XML element named Console under its parent appenders element. However,
-element and attribute names are not case sensitive. In addition,
-attributes can either be specified as an XML attribute or as an XML
-element that has no attributes and has a text value. So
+Loggers use appender references to list the appenders to deliver log events.
+See <<configuring-appenderrefs>> below for more details.
+
+[id=logger-elements-properties]
+==== Additional context properties
+
+Loggers can emit additional context data that will be integrated with other context data sources such as xref:manual/thread-context.adoc[ThreadContext].
+
+[CAUTION]
+====
+The `value` of each property is subject to <<property-substitution,property substitution>> twice:
+
+* when the configuration is loaded,
+* each time a log event is generated.
+
+Therefore, if you wish to insert a value that changes in time, you must double the `$` sign, as shown in the example below.
+====
+
+[tabs]
+====
+XML::
++
[source,xml]
----
-<PatternLayout pattern="%m%n"/>
+include::example$manual/configuration/logger-properties.xml[tag=loggers]
----
-and
+JSON::
++
+[source,json]
+----
+include::example$manual/configuration/logger-properties.json[tag=loggers]
+----
-[source,xml]
+YAML::
++
+[source,yaml]
----
-<PatternLayout>
- <Pattern>%m%n</Pattern>
-</PatternLayout>
+include::example$manual/configuration/logger-properties.yaml[tag=loggers]
----
-are equivalent.
+Java properties::
++
+[source,properties]
+----
+include::example$manual/configuration/logger-properties.properties[tag=loggers]
+----
+====
+
+[id=logger-elements-filters]
+==== Filters
+
+See xref:manual/filters.adoc#filters[Filters] for additional filtering capabilities that can be applied to a logger configuration.
+
+[id=configuring-appenderrefs]
+=== Appender references
+
+Many Log4j components, such as loggers, use appender references to designate which appenders will be used to deliver their events.
+
+Unlike in Log4j 1, where appender references were simple pointers, in Log4j 2, they have additional filtering capabilities.
+
+Appender references can have the following configuration attributes and elements:
+
+[id=appenderref-attributes-name]
+==== `ref`
+
+[cols="1h,5"]
+|===
+| Type | `String`
+|===
+
+Specifies the name of the appender to use.
+
+[id=appenderref-attributes-level]
+==== `level`
-The file below represents the structure of an XML configuration, but
-note that the elements in italics below represent the concise element
-names that would appear in their place.
+[cols="1h,5"]
+|===
+| Type | link:../javadoc/log4j-api/org/apache/logging/log4j/Level.html[Level]
+|===
+
+Specifies the level threshold that a log event must have to be logged.
+Log events that are more specific than this setting will be filtered out.
+
+[id=appenderrefs-elements-filters]
+==== Filters
+
+See xref:manual/filters.adoc#filters[Filters] for additional filtering capabilities that can be applied to a logger configuration.
+[id=property-substitution]
+=== Property substitution
+
+Log4j provides a simple and extensible mechanism to reuse values in the configuration file using `$\{name}` expressions, such as those used in Bash, Ant or Maven.
+
+Reusable configuration values can be added directly to a configuration file by using a xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-PropertiesPlugin[Properties] component.
+
+[tabs]
+====
+XML::
++
[source,xml]
----
-<?xml version="1.0" encoding="UTF-8"?>;
-<Configuration>
- <Properties>
- <Property name="name1">value</property>
- <Property name="name2" value="value2"/>
- </Properties>
- <filter ... />
- <Appenders>
- <appender ... >
- <filter ... />
- </appender>
- ...
- </Appenders>
- <Loggers>
- <Logger name="name1">
- <filter ... />
- </Logger>
- ...
- <Root level="level">
- <AppenderRef ref="name"/>
- </Root>
- </Loggers>
-</Configuration>
-----
-
-See the many examples on this page for sample appender, filter and
-logger declarations.
-
-=== Strict XML
-
-In addition to the concise XML format above, Log4j allows configurations
-to be specified in a more "normal" XML manner that can be validated
-using an XML Schema. This is accomplished by replacing the friendly
-element names above with their object type as shown below. For example,
-instead of the ConsoleAppender being configured using an element named
-Console it is instead configured as an appender element with a type
-attribute containing "Console".
+include::example$manual/configuration/properties.xml[lines=1;18..24;26]
+----
-[source,xml]
+JSON::
++
+[source,json]
+----
+include::example$manual/configuration/properties.json[]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration>
- <Properties>
- <Property name="name1">value</property>
- <Property name="name2" value="value2"/>
- </Properties>
- <Filter type="type" ... />
- <Appenders>
- <Appender type="type" name="name">
- <Filter type="type" ... />
- </Appender>
- ...
- </Appenders>
- <Loggers>
- <Logger name="name1">
- <Filter type="type" ... />
- </Logger>
- ...
- <Root level="level">
- <AppenderRef ref="name"/>
- </Root>
- </Loggers>
-</Configuration>
-----
-
-Below is a sample configuration using the strict format.
+YAML::
++
+[source,yaml]
+----
+include::example$manual/configuration/properties.yaml[lines=17..-1]
+----
+
+Java properties::
++
+[source,properties]
+----
+include::example$manual/configuration/properties.properties[lines=17..-1]
+----
+====
+
+An extensible lookup mechanism can also provide reusable configuration values.
+See xref:manual/lookups.adoc[Lookup]s for more information.
+
+Configuration values defined this way can be used in **any** configuration attribute by using the following expansion rules:
+
+`$\{name}`::
++
+If the `Properties` element of the configuration file has a property named `name`, its value is substituted.
+Otherwise, the placeholder is not expanded.
++
+[WARNING]
+====
+If `name` contains a `:` character, it is expanded as in the rule below.
+====
+
+`${lookup:name}`::
+If both these conditions hold:
++
+--
+* `lookup` is a prefix assigned to a xref:manual/lookups.adoc[Lookup],
+* the lookup has a value assigned to `name`,
+--
++
+the value for the lookup is substituted.
+Otherwise, the expansion of `$\{name}` is substituted.
++
+If `name` starts with a hyphen `-` (e.g. `-variable`), it must be escaped with a backslash `\` (e.g. `\-variable`).
++
+The most common lookup prefixes are:
++
+* `sys` for Java system properties (see xref:manual/lookups.adoc#system-properties-lookup[System Properties lookup]),
+* `env` for environment variables (see xref:manual/lookups.adoc#environment-lookup[Environment lookup]).
+
+The above expansions have a version with an additional `default` value that is **expanded** if the lookup fails:
+
+`${name:-default}`::
++
+If the `Properties` element of the configuration file has a property named `name,` its value is substituted.
+Otherwise, the **expansion** of `default` is substituted.
++
+[WARNING]
+====
+If `name` contains a `:` character, it is expanded as in the rule below.
+====
+
+`${lookup:name:-default}`::
++
+If both these conditions hold:
++
+--
+* `lookup` is a prefix assigned to a xref:manual/lookups.adoc[Lookup],
+* the lookup has a value assigned to `name,`
+--
++
+the value for the lookup is substituted.
+Otherwise, the expansion of `${name:-default}` is substituted.
+
+[NOTE]
+====
+To prevent the expansion of one of the expressions above, the initial `$` must be doubled as `$$`.
+
+The same rule applies to the `name` parameter: if it contains a `${` sequence, it must be escaped as `$${`.
+====
+
+.Property substitution example
+=====
+
+If your configuration file contains the following definitions:
+
+[tabs]
+====
+XML::
++
[source,xml]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="debug" strict="true" name="XMLConfigTest"
- packages="org.apache.logging.log4j.test">
- <Properties>
- <Property name="filename">target/test.log</Property>
- </Properties>
- <Filter type="ThresholdFilter" level="trace"/>
-
- <Appenders>
- <Appender type="Console" name="STDOUT">
- <Layout type="PatternLayout" pattern="%m MDC%X%n"/>
- <Filters>
- <Filter type="MarkerFilter" marker="FLOW" onMatch="DENY" onMismatch="NEUTRAL"/>
- <Filter type="MarkerFilter" marker="EXCEPTION" onMatch="DENY" onMismatch="ACCEPT"/>
- </Filters>
- </Appender>
- <Appender type="Console" name="FLOW">
- <Layout type="PatternLayout" pattern="%C{1}.%M %m %ex%n"/><!-- class and line number -->
- <Filters>
- <Filter type="MarkerFilter" marker="FLOW" onMatch="ACCEPT" onMismatch="NEUTRAL"/>
- <Filter type="MarkerFilter" marker="EXCEPTION" onMatch="ACCEPT" onMismatch="DENY"/>
- </Filters>
- </Appender>
- <Appender type="File" name="File" fileName="${filename}">
- <Layout type="PatternLayout">
- <Pattern>%d %p %C{1.} [%t] %m%n</Pattern>
- </Layout>
- </Appender>
- </Appenders>
-
- <Loggers>
- <Logger name="org.apache.logging.log4j.test1" level="debug" additivity="false">
- <Filter type="ThreadContextMapFilter">
- <KeyValuePair key="test" value="123"/>
- </Filter>
- <AppenderRef ref="STDOUT"/>
- </Logger>
-
- <Logger name="org.apache.logging.log4j.test2" level="debug" additivity="false">
- <AppenderRef ref="File"/>
- </Logger>
-
- <Root level="trace">
- <AppenderRef ref="STDOUT"/>
- </Root>
- </Loggers>
-
-</Configuration>
-----
-
-[#JSON]
-=== Configuration with JSON
-
-In addition to XML, Log4j can be configured using JSON. The JSON format
-is very similar to the concise XML format. Each key represents the name
-of a plugin and the key/value pairs associated with it are its
-attributes. Where a key contains more than a simple value it itself will
-be a subordinate plugin. In the example below, ThresholdFilter, Console,
-and PatternLayout are all plugins while the Console plugin will be
-assigned a value of STDOUT for its name attribute and the
-ThresholdFilter will be assigned a level of debug.
+include::example$manual/configuration/properties-example.xml[lines=18..-1]
+----
+JSON::
++
[source,json]
----
-{ "configuration": { "status": "error", "name": "RoutingTest",
- "packages": "org.apache.logging.log4j.test",
- "properties": {
- "property": { "name": "filename",
- "value" : "target/rolling1/rollingtest-$${sd:type}.log" }
- },
- "ThresholdFilter": { "level": "debug" },
- "appenders": {
- "Console": { "name": "STDOUT",
- "PatternLayout": { "pattern": "%m%n" },
- "ThresholdFilter": { "level": "debug" }
- },
- "Routing": { "name": "Routing",
- "Routes": { "pattern": "$${sd:type}",
- "Route": [
- {
- "RollingFile": {
- "name": "Rolling-${sd:type}", "fileName": "${filename}",
- "filePattern": "target/rolling1/test1-${sd:type}.%i.log.gz",
- "PatternLayout": {"pattern": "%d %p %c{1.} [%t] %m%n"},
- "SizeBasedTriggeringPolicy": { "size": "500" }
- }
- },
- { "AppenderRef": "STDOUT", "key": "Audit"}
- ]
- }
- }
- },
- "loggers": {
- "logger": { "name": "EventLogger", "level": "info", "additivity": "false",
- "AppenderRef": { "ref": "Routing" }},
- "root": { "level": "error", "AppenderRef": { "ref": "STDOUT" }}
- }
- }
-}
+include::example$manual/configuration/properties-example.json[]
----
-Note that in the RoutingAppender the Route element has been declared as
-an array. This is valid because each array element will be a Route
-component. This won't work for elements such as appenders and filters,
-where each element has a different name in the concise format. Appenders
-and filters can be defined as array elements if each appender or filter
-declares an attribute named "type" that contains the type of the
-appender. The following example illustrates this as well as how to
-declare multiple loggers as an array.
+YAML::
++
+[source,yaml]
+----
+include::example$manual/configuration/properties-example.yaml[lines=17..-1]
+----
-[source,json]
+Java properties::
++
+[source,properties]
----
-{ "configuration": { "status": "debug", "name": "RoutingTest",
- "packages": "org.apache.logging.log4j.test",
- "properties": {
- "property": { "name": "filename",
- "value" : "target/rolling1/rollingtest-$${sd:type}.log" }
- },
- "ThresholdFilter": { "level": "debug" },
- "appenders": {
- "appender": [
- { "type": "Console", "name": "STDOUT", "PatternLayout": { "pattern": "%m%n" }, "ThresholdFilter": { "level": "debug" }},
- { "type": "Routing", "name": "Routing",
- "Routes": { "pattern": "$${sd:type}",
- "Route": [
- {
- "RollingFile": {
- "name": "Rolling-${sd:type}", "fileName": "${filename}",
- "filePattern": "target/rolling1/test1-${sd:type}.%i.log.gz",
- "PatternLayout": {"pattern": "%d %p %c{1.} [%t] %m%n"},
- "SizeBasedTriggeringPolicy": { "size": "500" }
- }
- },
- { "AppenderRef": "STDOUT", "key": "Audit"}
- ]
- }
- }
- ]
- },
- "loggers": {
- "logger": [
- { "name": "EventLogger", "level": "info", "additivity": "false",
- "AppenderRef": { "ref": "Routing" }},
- { "name": "com.foo.bar", "level": "error", "additivity": "false",
- "AppenderRef": { "ref": "STDOUT" }}
- ],
- "root": { "level": "error", "AppenderRef": { "ref": "STDOUT" }}
- }
- }
-}
+include::example$manual/configuration/properties-example.properties[lines=17..-1]
----
+====
-Additional xref:runtime-dependencies.adoc[runtime dependencies] are
-required for using JSON configuration files.
+and the OS environment variable `FOO` has a value of `environment`, Log4j will evaluate the expression as follows
-[#YAML]
-=== Configuration with YAML
+[cols="1m,1m"]
+|===
+| Expression | Value
+
+| $\{FOO} | foo
+| $\{BAZ} | $\{BAZ}
+| ${BAR:-$\{FOO}} | bar
+| ${BAZ:-$\{FOO}} | foo
+| ${env:FOO} | environment
+| ${env:BAR} | bar
+| ${env:BAZ} | $\{BAZ}
+| ${env:BAR:-$\{FOO}} | bar
+| ${env:BAZ:-$\{FOO}} | foo
+|===
+=====
-Log4j also supports using YAML for configuration files. The structure
-follows the same pattern as both the XML and YAML configuration formats.
-For example:
+[CAUTION]
+=====
+For security reasons, if the **expansion** of a `${...}` expression contains other expressions, these will **not** be expanded.
+The only exception to this rule is the expansion of properties in the `Properties` container.
-[source,yaml]
+Properties defined in the `Properties` container can depend on each other.
+If your configuration contains, for example:
+
+[tabs]
+====
+XML::
++
+[source,xml]
+----
+include::example$manual/configuration/properties-recursion.xml[lines=18..-1]
----
-Configuration:
- status: warn
- name: YAMLConfigTest
- properties:
- property:
- name: filename
- value: target/test-yaml.log
- thresholdFilter:
- level: debug
- appenders:
- Console:
- name: STDOUT
- target: SYSTEM_OUT
- PatternLayout:
- Pattern: "%m%n"
- File:
- name: File
- fileName: ${filename}
- PatternLayout:
- Pattern: "%d %p %C{1.} [%t] %m%n"
- Filters:
- ThresholdFilter:
- level: error
-
- Loggers:
- logger:
- -
- name: org.apache.logging.log4j.test1
- level: debug
- additivity: false
- ThreadContextMapFilter:
- KeyValuePair:
- key: test
- value: 123
- AppenderRef:
- ref: STDOUT
- -
- name: org.apache.logging.log4j.test2
- level: debug
- additivity: false
- AppenderRef:
- ref: File
- Root:
- level: error
- AppenderRef:
- ref: STDOUT
-
-----
-
-Additional xref:runtime-dependencies.adoc[runtime dependencies] are
-required for using YAML configuration files.
-
-[#Properties]
-=== Configuration with Properties
-
-As of version 2.4, Log4j now supports configuration via properties
-files. Note that the property syntax is NOT the same as the syntax used
-in Log4j 1. Like the XML and JSON configurations, properties
-configurations define the configuration in terms of plugins and
-attributes to the plugins.
-
-Prior to version 2.6, the properties configuration requires that you
-list the identifiers of the appenders, filters and loggers, in a comma
-separated list in properties with those names. Each of those components
-will then be expected to be defined in sets of properties that begin
-with _component.<.identifier>._. The identifier does not have to match
-the name of the component being defined but must uniquely identify all
-the attributes and subcomponents that are part of the component. If the
-list of identifiers is not present the identifier must not contain a '.'.
-Each individual component MUST have a "type" attribute specified that
-identifies the component's Plugin type.
-
-As of version 2.6, this list of identifiers is no longer required as
-names are inferred upon first usage, however if you wish to use more
-complex identifies you must still use the list. If the list is present
-it will be used.
-
-Unlike the base components, when creating subcomponents you cannot
-specify an element containing a list of identifiers. Instead, you must
-define the wrapper element with its type as is shown in the policies
-definition in the rolling file appender below. You then define each of
-the subcomponents below that wrapper element, as the
-TimeBasedTriggeringPolicy and SizeBasedTriggeringPolicy are defined
-below.
-
-As of version 2.17.2, `rootLogger` and `logger._key_` properties can be specified to set the
-level and zero or more appender refs to create for that logger. The level and appender refs are
-separated by comma `,` characters with optional whitespace surrounding the comma. The
-following example demonstrates how the shorthand is expanded when reading properties configurations.
-[source,properties]
+JSON::
++
+[source,json]
+----
+include::example$manual/configuration/properties-recursion.json[]
----
-appender.stdout.type = Console
-# ... other appender properties
-appender.file.type = File
-# ... other appender properties
-logger.app = INFO, stdout, file
-logger.app.name = com.example.app
-
-# is equivalent to:
-# appender.stdout.type = Console
-# appender.stdout.name = stdout
-# ...
-appender.file.type = File
-appender.file.name = file
-# ...
-logger.app.name = com.example.app
-logger.app.level = INFO
-logger.app.appenderRef.$1.ref = stdout
-logger.app.appenderRef.$2.ref = file
-----
-
-Properties configuration files support the advertiser, monitorInterval,
-name, packages, shutdownHook, shutdownTimeout, status, verbose, and dest
-attributes. See link:#ConfigurationSyntax[Configuration Syntax] for the
-definitions of these attributes.
-[source,properties]
+YAML::
++
+[source,yaml]
+----
+include::example$manual/configuration/properties-recursion.yaml[lines=17..-1]
----
-status = error
-dest = err
-name = PropertiesConfig
-
-property.filename = target/rolling/rollingtest.log
-
-filter.threshold.type = ThresholdFilter
-filter.threshold.level = debug
-
-appender.console.type = Console
-appender.console.name = STDOUT
-appender.console.layout.type = PatternLayout
-appender.console.layout.pattern = %m%n
-appender.console.filter.threshold.type = ThresholdFilter
-appender.console.filter.threshold.level = error
-
-appender.rolling.type = RollingFile
-appender.rolling.name = RollingFile
-appender.rolling.fileName = ${filename}
-appender.rolling.filePattern = target/rolling2/test1-%d{MM-dd-yy-HH-mm-ss}-%i.log.gz
-appender.rolling.layout.type = PatternLayout
-appender.rolling.layout.pattern = %d %p %C{1.} [%t] %m%n
-appender.rolling.policies.type = Policies
-appender.rolling.policies.time.type = TimeBasedTriggeringPolicy
-appender.rolling.policies.time.interval = 2
-appender.rolling.policies.time.modulate = true
-appender.rolling.policies.size.type = SizeBasedTriggeringPolicy
-appender.rolling.policies.size.size=100MB
-appender.rolling.strategy.type = DefaultRolloverStrategy
-appender.rolling.strategy.max = 5
-
-logger.rolling.name = com.example.my.app
-logger.rolling.level = debug
-logger.rolling.additivity = false
-logger.rolling.appenderRef.rolling.ref = RollingFile
-
-rootLogger.level = info
-rootLogger.appenderRef.stdout.ref = STDOUT
-
-----
-
-
-[#Loggers]
-=== Configuring Loggers
-
-An understanding of how loggers work in Log4j is critical before trying
-to configure them. Please reference the Log4j
-xref:manual/architecture.adoc[architecture] if more information is required.
-Trying to configure Log4j without understanding those concepts will lead
-to frustration.
-
-A LoggerConfig is configured using the `logger` element. The `logger`
-element must have a name attribute specified, will usually have a level
-attribute specified and may also have an additivity attribute specified.
-The level may be configured with one of TRACE, DEBUG, INFO, WARN, ERROR,
-ALL or OFF. If no level is specified it will default to ERROR. The
-additivity attribute may be assigned a value of true or false. If the
-attribute is omitted the default value of true will be used.
-
-Capturing location information (the class name, file name, method name, and line number of the caller)
-can be slow. Log4j tries to optimize this by reducing the size of the stack that must be traversed
-to find the caller of the logging method. It does this by determining if any component that might
-be accessed requires location information. This can cause performance issues if a logger is configured
-at a level like trace or debug with the expectation that most logs will be filtered on an Appender
-reference or Appender as Log4j will calculate the location information even though the log event
-is going to be discarded. To disable this behavior the `includeLocation` attribute
-can be set to false on the LoggerConfig. This will cause Log4j to defer calculating the location
-information until absolutely necessary.
-
-A LoggerConfig (including the root LoggerConfig) can be configured with
-properties that will be added to the properties copied from the
-ThreadContextMap. These properties can be referenced from Appenders,
-Filters, Layouts, etc just as if they were part of the ThreadContext
-Map. The properties can contain variables that will be resolved either
-when the configuration is parsed or dynamically when each event is
-logged. See link:#PropertySubstitution[Property Substitution] for more
-information on using variables.
-
-The LoggerConfig may also be configured with one or more AppenderRef
-elements. Each appender referenced will become associated with the
-specified LoggerConfig. If multiple appenders are configured on the
-LoggerConfig each of them be called when processing logging events.
-
-*_Every configuration must have a root logger_*. If one is not
-configured the default root LoggerConfig, which has a level of ERROR and
-has a Console appender attached, will be used. The main differences
-between the root logger and other loggers are
-
-1. The root logger does not have a name attribute.
-2. The root logger does not support the additivity attribute since it
-has no parent.
-
-[#Appenders]
-=== Configuring Appenders
-
-An appender is configured either using the specific appender plugin's
-name or with an appender element and the type attribute containing the
-appender plugin's name. In addition each appender must have a name
-attribute specified with a value that is unique within the set of
-appenders. The name will be used by loggers to reference the appender as
-described in the previous section.
-
-Most appenders also support a layout to be configured (which again may
-be specified either using the specific Layout plugin's name as the
-element or with "layout" as the element name along with a type attribute
-that contains the layout plugin's name. The various appenders will
-contain other attributes or elements that are required for them to
-function properly.
-
-[#Filters]
-=== Configuring Filters
-
-Log4j allows a filter to be specified in any of 4 places:
-
-1. At the same level as the appenders, loggers and properties elements.
-These filters can accept or reject events before they have been passed
-to a LoggerConfig.
-2. In a logger element. These filters can accept or reject events for
-specific loggers.
-3. In an appender element. These filters can prevent or cause events to
-be processed by the appender.
-4. In an appender reference element. These filters are used to
-determine if a Logger should route the event to an appender.
-
-Although only a single `filter` element can be configured, that element
-may be the `filters` element which represents the CompositeFilter. The
-`filters` element allows any number of `filter` elements to be
-configured within it. The following example shows how multiple filters
-can be configured on the ConsoleAppender.
-[source,xml]
+Java properties::
++
+[source,properties]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="debug" name="XMLConfigTest" packages="org.apache.logging.log4j.test">
- <Properties>
- <Property name="filename">target/test.log</Property>
- </Properties>
- <ThresholdFilter level="trace"/>
-
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%m MDC%X%n"/>
- </Console>
- <Console name="FLOW">
- <!-- this pattern outputs class name and line number -->
- <PatternLayout pattern="%C{1}.%M %m %ex%n"/>
- <filters>
- <MarkerFilter marker="FLOW" onMatch="ACCEPT" onMismatch="NEUTRAL"/>
- <MarkerFilter marker="EXCEPTION" onMatch="ACCEPT" onMismatch="DENY"/>
- </filters>
- </Console>
- <File name="File" fileName="${filename}">
- <PatternLayout>
- <pattern>%d %p %C{1.} [%t] %m%n</pattern>
- </PatternLayout>
- </File>
- </Appenders>
-
- <Loggers>
- <Logger name="org.apache.logging.log4j.test1" level="debug" additivity="false">
- <ThreadContextMapFilter>
- <KeyValuePair key="test" value="123"/>
- </ThreadContextMapFilter>
- <AppenderRef ref="STDOUT"/>
- </Logger>
-
- <Logger name="org.apache.logging.log4j.test2" level="debug" additivity="false">
- <Property name="user">${sys:user.name}</Property>
- <AppenderRef ref="File">
- <ThreadContextMapFilter>
- <KeyValuePair key="test" value="123"/>
- </ThreadContextMapFilter>
- </AppenderRef>
- <AppenderRef ref="STDOUT" level="error"/>
- </Logger>
-
- <Root level="trace">
- <AppenderRef ref="STDOUT"/>
- </Root>
- </Loggers>
-
-</Configuration>
-----
-
-[#PropertySubstitution]
-== Property Substitution
-
-Log4j 2 supports the ability to specify tokens in the configuration as
-references to properties defined elsewhere. Some of these properties
-will be resolved when the configuration file is interpreted while others
-may be passed to components where they will be evaluated at runtime. To
-accomplish this, Log4j uses variations of
-https://commons.apache.org/proper/commons-lang/[Apache Commons Lang]'s
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrSubstitutor.html[`StrSubstitutor`]
-and
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html[`StrLookup`]
-classes. In a manner similar to Ant or Maven, this allows variables
-declared as `$\{name}` to be resolved using properties declared in the
-configuration itself. For example, the following example shows the
-filename for the rolling file appender being declared as a property.
+include::example$manual/configuration/properties-recursion.properties[lines=17..-1]
+----
+====
+
+the `logging.dir` property will be expanded **before** the `logging.file` property, and the expanded value will be substituted in `${logging.dir}/app.log`.
+Therefore, the value of the `logging.file` property will be:
+* `./logs/app.log` if the environment variable `APP_BASE` is not defined,
+* `/var/lib/app/logs/app.log` if the environment variable `APP_BASE` has a value of `/var/lib/app`.
+
+
+=====
+
+[id=lazy-property-substitution]
+==== Lazy property substitution
+
+For most attributes, property substitution is performed only once at **configuration time**, but there are two categories of exceptions to this rule:
+
+* Some attributes are **also** evaluated when a component-specific event occurs.
+For example
+<<logger-elements-properties,additional context properties>>
+and the `pattern` attribute of the example below are evaluated at each log event, while the `filePattern` attribute of a
+xref:manual/appenders.adoc#rollingfileappender[rolling file appender]
+is evaluated at each rollover.
++
+In this case:
+
+** If you want property substitution to happen only once, use one dollar sign, e.g., `${date:HH:mm:ss}`.
+** If you want property substitution to happen at each cyclic event, you use two dollar signs, e.g., `$${date:HH:mm:ss}`
+
+* Other components defer the evaluation of their child components.
+In this case, you only need one dollar `$` sign.
++
+This case happens for the children of the `Route` element below:
+
+[tabs]
+====
+XML::
++
[source,xml]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="debug" name="RoutingTest" packages="org.apache.logging.log4j.test">
- <Properties>
- <Property name="filename">target/rolling1/rollingtest-$${sd:type}.log</Property>
- </Properties>
- <ThresholdFilter level="debug"/>
-
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%m%n"/>
- <ThresholdFilter level="debug"/>
- </Console>
- <Routing name="Routing">
- <Routes pattern="$${sd:type}">
- <Route>
- <RollingFile name="Rolling-${sd:type}" fileName="${filename}"
- filePattern="target/rolling1/test1-${sd:type}.%i.log.gz">
- <PatternLayout>
- <pattern>%d %p %c{1.} [%t] %m%n</pattern>
- </PatternLayout>
- <SizeBasedTriggeringPolicy size="500" />
- </RollingFile>
- </Route>
- <Route ref="STDOUT" key="Audit"/>
- </Routes>
- </Routing>
- </Appenders>
-
- <Loggers>
- <Logger name="EventLogger" level="info" additivity="false">
- <AppenderRef ref="Routing"/>
- </Logger>
-
- <Root level="error">
- <AppenderRef ref="STDOUT"/>
- </Root>
- </Loggers>
-
-</Configuration>
-----
-
-While this is useful, there are many more places properties can
-originate from. To accommodate this, Log4j also supports the syntax
-`${prefix:name}` where the prefix identifies tells Log4j that variable
-name should be evaluated in a specific context. See the
-xref:manual/lookups.adoc[Lookups] manual page for more details. The contexts
-that are built in to Log4j are:
-
-[cols="1m,5"]
-|===
-|Prefix |Context
-
- <tr>
- <td>base64</td>
- <td>
- Base64 encoded data. The format is <code>${base64:Base64_encoded_data}</code>.
- For example:
- <code>${base64:SGVsbG8gV29ybGQhCg==}</code> yields <code>Hello World!</code>.
- </td>
- </tr>
-
-|base64
-|Base64 encoded data. The format is `${base64:Base64_encoded_data}`.
-For example: `${base64:SGVsbG8gV29ybGQhCg==}` yields `Hello World!`.
-
-|bundle
-|Resource bundle. The format is `${bundle:BundleName:BundleKey}`.
-The bundle name follows package naming conventions, for example:
-`${bundle:com.domain.Messages:MyKey}`.
-
-|ctx
-|Thread Context Map (MDC)
-
-|date
-|Inserts the current date and/or time using the specified format
-
-|docker
-| Returns attributes from the Docker container the application is running in. The format is ${docker:some.attribute}. See xref:log4j-docker.adoc[Docker documentation] for requirements and a list of available attributes.
-
-|env
-|System environment variables. The formats are `${env:ENV_NAME}` and `${env:ENV_NAME:-default_value}`.
-
-| event
-| Retrieves values from fields within the log event. The format is ${event:some.field}. See the Lookups manual page for a list of available fields.
-| java
-| Retrieves information about the Java environment the application is running in. The format is ${java:some.property}. See the Lookups manual page for a list of available properties.
-
-|jndi
-|A value set in the default JNDI Context.
-
-|jvmrunargs
-|A JVM input argument accessed through JMX, but not a main argument; see
-https://docs.oracle.com/javase/6/docs/api/java/lang/management/RuntimeMXBean.html#getInputArguments--[RuntimeMXBean.getInputArguments()].
-Not available on Android.
-
-| k8s
-| Returns attributes from the Kubernetes environment the application is running in. The format is ${k8s:some.attribute}. See the Lookups manual page for a list of available attributes.
-
-|log4j
-|Log4j configuration properties. The expressions
-`${log4j:configLocation}` and `${log4j:configParentLocation}`
-respectively provide the absolute path to the log4j configuration file
-and its parent folder.
-
-| lower
-| Converts the passed in argument to lower case (usually used with nested lookups). The format is ${lower:argument}.
-
-|main
-|A value set with
-../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/MapLookup.html#setMainArguments-java.lang.String:A-[MapLookup.setMainArguments(String[])]
-
-|map
-|A value from a MapMessage
-
-| marker
-| Allows use of markers in configurations. The formats are ${marker:} and ${marker:some.name}. See the Lookups manual page for further details.
-
-|sd
-|A value from a StructuredDataMessage. The key "id" will return the
-name of the StructuredDataId without the enterprise number. The key
-"type" will return the message type. Other keys will retrieve individual
-elements from the Map.
-
-| spring
-| Returns values of Spring properties from the Spring configuration. The format is ${spring:some.property}. See the Lookups manual page for requirements and details.
-
-|sys
-|System properties. The formats are `${sys:some.property}` and
-`${sys:some.property:-default_value}`.
-
-| upper
-| Converts the passed in argument to upper case (usually used with nested lookups). The format is ${upper:argument}.
-| web
-| Returns values of variables associated with the Servlet Context. The format is ${spring:some.key}. See the Lookups manual page for a list of available keys.
-|===
+include::example$manual/configuration/routing.xml[tag=appender]
+----
-[#DefaultProperties]
-== Default Properties
-A default property map can be declared in the configuration file by placing a Properties
-element directly after the Configuration element and before any Loggers, Filters,
-Appenders, etc. are declared. If the value cannot be located in the specified lookup the
-value in the default property map will be used. The default map is pre-populated with a value
-for "hostName" that is the current system's host name or IP address and
-the "contextName" with is the value of the current logging context. See many places
-a Properties element is used in this section for examples.
-
-Default properties may also be specified in the Lookup by using the syntax `${lookupName:key:-defaultValue}`.
-In some cases the key might contain a leading '-'. When this is the case an escape character must be
-included, such as ``${main:\--file:-app.properties}`. This would use the
-`MainMapLookup` for a key named `--file`. If the key is not found then
-<code>app.properties</code> would be used as the default value.
-
-[#EnablingMessagePatternLookups]
-== Enabling Message Pattern Lookups
-A message is processed (by default) without using lookups, for example if you defined
-`<Property name="foo.bar">FOO_BAR</Property>`, then `logger.info("${foo.bar}")` will output `${foo.bar}` instead of `FOO_BAR`.
-You could enable message pattern lookups by defining the message pattern using `%m\{lookups}`.
-
-[#RuntimeLookup]
-== Lookup Variables with Multiple Leading '$' Characters
-
-An interesting feature of StrLookup processing is that when a variable
-reference is declared with multiple leading '$' characters each time the
-variable is resolved the leading '$' is simply removed. In the previous
-example the "Routes" element is capable of resolving the variable at
-runtime. To allow this the prefix value is specified as a variable with
-two leading '$' characters. When the configuration file is first
-processed the first '$' character is simply removed. Thus, when the
-Routes element is evaluated at runtime it is the variable declaration
-"$\{sd:type}" which causes the event to be inspected for a
-StructuredDataMessage and if one is present the value of its type
-attribute to be used as the routing key. Not all elements support
-resolving variables at runtime. Components that do will specifically
-call that out in their documentation.
-
-If no value is found for the key in the Lookup associated with the
-prefix then the value associated with the key in the properties
-declaration in the configuration file will be used. If no value is found
-the variable declaration will be returned as the value. Default values
-may be declared in the configuration by doing:
+JSON::
++
+[source,json]
+----
+include::example$manual/configuration/routing.json[tag=appender]
+----
-[source,xml]
+YAML::
++
+[source,yaml]
+----
+include::example$manual/configuration/routing.yaml[tag=appender]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration>
- <Properties>
- <Property name="type">Audit</property>
- </Properties>
- ...
-</Configuration>
-----
-
-_As a footnote, it is worth pointing out that the variables in the
-RollingFile appender declaration will also not be evaluated when the
-configuration is processed. This is simply because the resolution of the
-whole RollingFile element is deferred until a match occurs. See
-xref:manual/appenders.adoc#RoutingAppender[RoutingAppender] for more
-information._
-
-[#Scripts]
-== Scripts
-
-Log4j provides support for
-https://docs.oracle.com/javase/6/docs/technotes/guides/scripting/[JSR
-223] scripting languages to be used in some of its components. Any
-language that provides support for the JSR 223 scripting engine may be
-used. A list of the languages and bindings for them can be found at the
-https://java.net/projects/scripting/sources/svn/show/trunk/engines[Scripting
-Engine] web site. However, some of the languages listed there, such as
-JavaScript, Groovy and Beanshell, directly support the JSR 223 scripting
-framework and only require that the jars for that language be installed.
-
-As of Log4j 2.17.2 the languages to be supported must be specified as a comma separated list in the
-`log4j2.Script.enableLanguages` system property.
-
-The components that support using scripts do so by allowing a `<script>`,
-`<scriptFile>`, or `<scriptRef>` element to be configured on them. The
-script element contains a name for the script, the language of the
-script, and the script text. The scriptFile element contains the name of
-the script, its location, its language, its charset, and whether the
-file should be watched for changes. The scriptRef element contains the
-name of the script that is defined in the `<scripts>` configuration
-element. The name of the script is used to store the script, along with
-its ScriptEngine, so it can quickly be located each time the script
-needs to be run. While the name is not required, providing it will help
-in debugging problems when the script is running. The language must be
-provided on the script element and must specify one of the language
-names that appear in the Configuration status log as described in the
-next section. If the language is not specified on the scriptFile element
-the language will be determined by the file extension of the script
-path. If file monitoring is requested it will only be enabled if a
-non-zero monitorInterval is specified on the configuration element. That
-interval will be used to check for changes in the file.
-[source,xml]
+Java properties::
++
+[source,properties]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="debug" name="RoutingTest">
- <Scripts>
- <Script name="selector" language="javascript"><![CDATA[
- var result;
- if (logEvent.getLoggerName().equals("JavascriptNoLocation")) {
- result = "NoLocation";
- } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
- result = "Flow";
- }
- result;
- ]]></Script>
- <ScriptFile name="groovy.filter" path="scripts/filter.groovy"/>
- </Scripts>
-
- <Appenders>
- <Console name="STDOUT">
- <ScriptPatternSelector defaultPattern="%d %p %m%n">
- <ScriptRef ref="selector"/>
- <PatternMatch key="NoLocation" pattern="[%-5level] %c{1.} %msg%n"/>
- <PatternMatch key="Flow" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
- </ScriptPatternSelector>
- <PatternLayout pattern="%m%n"/>
- </Console>
- </Appenders>
-
- <Loggers>
- <Logger name="EventLogger" level="info" additivity="false">
- <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY">
- <Script name="GroovyFilter" language="groovy"><![CDATA[
- if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
- return true;
- } else if (logEvent.getContextMap().containsKey("UserId")) {
- return true;
- }
- return false;
- ]]>
- </Script>
- </ScriptFilter>
- <AppenderRef ref="STDOUT"/>
- </Logger>
-
- <Root level="error">
- <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY">
- <ScriptRef ref="groovy.filter"/>
- </ScriptFilter>
- <AppenderRef ref="STDOUT"/>
- </Root>
- </Loggers>
-
-</Configuration>
-----
-
-If the status attribute on the Configuration element is set to DEBUG the
-list of script engines currently installed and their attributes will be
-listed. Although some engines may say they are not thread safe, Log4j
-takes steps to insure that the scripts will run in a thread-safe manner
-if the engine advertises that it is not thread safe.
-
-....
-2015-09-27 16:13:22,925 main DEBUG Installed script engines
-2015-09-27 16:13:22,963 main DEBUG AppleScriptEngine Version: 1.1, Language: AppleScript, Threading: Not Thread Safe,
- Compile: false, Names: {AppleScriptEngine, AppleScript, OSA}
-2015-09-27 16:13:22,983 main DEBUG Groovy Scripting Engine Version: 2.0, Language: Groovy, Threading: MULTITHREADED,
- Compile: true, Names: {groovy, Groovy}
-2015-09-27 16:13:23,030 main DEBUG BeanShell Engine Version: 1.0, Language: BeanShell, Threading: MULTITHREADED,
- Compile: true, Names: {beanshell, bsh, java}
-2015-09-27 16:13:23,039 main DEBUG Mozilla Rhino Version: 1.7 release 3 PRERELEASE, Language: ECMAScript, Threading: MULTITHREADED,
- Compile: true, Names: {js, rhino, JavaScript, javascript, ECMAScript, ecmascript}
-....
-
-When the scripts are executed they will be provided with a set of
-variables that should allow them to accomplish whatever task they are
-expected to perform. See the documentation for the individual components
-for the list of variables that are available to the script.
-
-The components that support scripting expect a return value to be passed
-back to the calling Java code. This is not a problem for several of the
-scripting languages, but Javascript does not allow a return statement
-unless it is within a function. However, Javascript will return the
-value of the last statement executed in the script. As a consequence,
-code such as that shown below will result in the desired behavior.
-
-[source,javascript]
-----
-var result;
-if (logEvent.getLoggerName().equals("JavascriptNoLocation")) {
- result = "NoLocation";
-} else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
- result = "Flow";
-}
-result;
+include::example$manual/configuration/routing.properties[tag=appender]
----
+====
-=== A special note on Beanshell
+<1> The `pattern` attribute is evaluated at configuration time and also each time a log event is routed.
+Therefore, the dollar `$` sign needs to be escaped.
+<2> All the attributes inside the `File` element have a **deferred** evaluation, therefore they need only one `$` sign.
-JSR 223 scripting engines are supposed to identify that they support the
-Compilable interface if they support compiling their scripts. Beanshell
-does this. However, whenever the compile method is called it throws an
-Error (not an Exception). Log4j catches this but will log the warning
-shown below for each Beanshell script when it tries to compile them. All
-Beanshell scripts will then be interpreted on each execution.
+[id=arbiters]
+=== [[Arbiters]] Arbiters
-....
-2015-09-27 16:13:23,095 main DEBUG Script BeanShellSelector is compilable
-2015-09-27 16:13:23,096 main WARN Error compiling script java.lang.Error: unimplemented
- at bsh.engine.BshScriptEngine.compile(BshScriptEngine.java:175)
- at bsh.engine.BshScriptEngine.compile(BshScriptEngine.java:154)
- at org.apache.logging.log4j.core.script.ScriptManager$MainScriptRunner.<init>(ScriptManager.java:125)
- at org.apache.logging.log4j.core.script.ScriptManager.addScript(ScriptManager.java:94)
-
-....
+While property substitution allows using the same configuration file in multiple deployment environments, sometimes changing the values of configuration attributes is not enough.
-[#XInclude]
-== XInclude
+Arbiters are to configuration elements what property substitution is for configuration attributes: they allow to conditionally add a subtree of configuration elements to a configuration file.
-XML configuration files can include other files with
-http://www.xml.com/lpt/a/1009[XInclude]. Here is an example log4j2.xml
-file that includes two other files:
+Arbiters may occur anywhere an element is allowed in the configuration and can be nested.
+So, an Arbiter could encapsulate something as simple as a single property declaration or a whole set of appenders, loggers, or other arbiters.
+The child elements of an arbiter must be valid elements for whatever element is the parent of the arbiter.
-.log4j2.xml
+For a complete list of available arbiters, see
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-Arbiter[plugin reference].
+In the examples below, we'll use the
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-DefaultArbiter[DefaultArbiter],
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-SelectArbiter[Select]
+and
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-SystemPropertyArbiter[SystemPropertyArbiter].
+
+For example, you might want to use a different layout in a production and development environment:
+
+[tabs]
+====
+XML::
++
[source,xml]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<configuration xmlns:xi="http://www.w3.org/2001/XInclude"
- status="warn" name="XIncludeDemo">
- <properties>
- <property name="filename">xinclude-demo.log</property>
- </properties>
- <ThresholdFilter level="debug"/>
- <xi:include href="log4j-xinclude-appenders.xml" />
- <xi:include href="log4j-xinclude-loggers.xml" />
-</configuration>
+include::example$manual/configuration/arbiters.xml[lines=1;18..-1]
----
-.log4j-xinclude-appenders.xml
-[source,xml]
+JSON::
++
+[source,json]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%m%n" />
- </Console>
- <File name="File" fileName="${filename}" bufferedIO="true" immediateFlush="true">
- <PatternLayout>
- <pattern>%d %p %C{1.} [%t] %m%n</pattern>
- </PatternLayout>
- </File>
-</appenders>
+include::example$manual/configuration/arbiters.json[]
----
-.log4j-xinclude-loggers.xml
+YAML::
++
+[source,yaml]
+----
+include::example$manual/configuration/arbiters.yaml[lines=17..-1]
+----
+
+Java properties::
++
+[source,properties]
+----
+include::example$manual/configuration/arbiters.properties[lines=17..-1]
+----
+====
+
+<1> If the Java system property `env` has a value of `dev`, a pattern layout will be used.
+<2> If the Java system property `env` has a value of `prod`, a JSON template layout will be used.
+
+The above example has a problem: if the Java system property `env` has a value different from `dev` or `prod`, the appender will have no layout.
+
+This is a case when the `Select` plugin is useful: this configuration element contains a list of arbiters and a
+`DefaultArbiter` element.
+If none of the arbiters match, the configuration from the `DefaultArbiter` element will be used:
+
+[tabs]
+====
+XML::
++
[source,xml]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<loggers>
- <logger name="org.apache.logging.log4j.test1" level="debug" additivity="false">
- <ThreadContextMapFilter>
- <KeyValuePair key="test" value="123" />
- </ThreadContextMapFilter>
- <AppenderRef ref="STDOUT" />
- </logger>
+include::example$manual/configuration/arbiters-select.xml[tag=select]
+----
- <logger name="org.apache.logging.log4j.test2" level="debug" additivity="false">
- <AppenderRef ref="File" />
- </logger>
+JSON::
++
+[source,json]
+----
+include::example$manual/configuration/arbiters-select.json[tag=select]
+----
- <root level="error">
- <AppenderRef ref="STDOUT" />
- </root>
-</loggers>
+YAML::
++
+[source,yaml]
+----
+include::example$manual/configuration/arbiters-select.yaml[tag=select]
----
+Java properties::
++
+[source,properties]
+----
+include::example$manual/configuration/arbiters-select.properties[tag=select]
+----
+====
+
+<1> If the Java system property `env` has a value of `dev`, a pattern layout will be used.
+<2> Otherwise, a JSON template layout will be used.
+
[#CompositeConfiguration]
-== Composite Configuration
-
-Log4j allows multiple configuration files to be used by specifying them
-as a list of comma separated file paths on log4j2.configurationFile or,
-when using URLs, by adding secondary configuration locations as query
-parameters named "override". The merge logic can be controlled by specifying
-a class that implements the MergeStrategy interface on the log4j.mergeStrategy
-property. The default merge strategy will merge the files using the following rules:
-
-1. The global configuration attributes are aggregated with those in
-later configurations replacing those in previous configurations, with
-the exception that the highest status level and the lowest
-monitorInterval greater than 0 will be used.
-2. Properties from all configurations are aggregated. Duplicate
-properties replace those in previous configurations.
-3. Filters are aggregated under a CompositeFilter if more than one
-Filter is defined. Since Filters are not named duplicates may be
-present.
-4. Scripts and ScriptFile references are aggregated. Duplicate
-definitions replace those in previous configurations.
-5. Appenders are aggregated. Appenders with the same name are replaced
-by those in later configurations, including all of the Appender's
-subcomponents.
-6. Loggers are all aggregated. Logger attributes are individually
-merged with duplicates being replaced by those in later configurations.
-Appender references on a Logger are aggregated with duplicates being
-replaced by those in later configurations. Filters on a Logger are
-aggregated under a CompositeFilter if more than one Filter is defined.
-Since Filters are not named duplicates may be present. Filters under
-Appender references included or discarded depending on whether their
-parent Appender reference is kept or discarded.
-
-[#StatusMessages]
-== Status Messages
-
-****
-*Troubleshooting tip for the impatient:*
-
-From log4j-2.9 onward, log4j2 will print all internal logging to the
-console if system property `log4j2.debug` is either defined empty or its value
-equals to `true` (ignoring case).
-
-Prior to log4j-2.9, there are two places where internal logging can be
-controlled:
-
-* Before a configuration is found, status logger level can be controlled
-with system property
-`org.apache.logging.log4j.simplelog.StatusLogger.level`.
-* After a configuration is found, status logger level can be controlled
-in the configuration file with the "status" attribute, for example:
-`<Configuration status="trace">`.
-****
-
-Just as it is desirable to be able to diagnose problems in applications,
-it is frequently necessary to be able to diagnose problems in the
-logging configuration or in the configured components. Since logging has
-not been configured, "normal" logging cannot be used during
-initialization. In addition, normal logging within appenders could
-create infinite recursion which Log4j will detect and cause the
-recursive events to be ignored. To accomodate this need, the Log4j 2 API
-includes a
-link:../javadoc/log4j-api/org/apache/logging/log4j/status/StatusLogger.html[`StatusLogger`].
-Components declare an instance of the StatusLogger similar to:
-
-[source,java]
-----
-protected final static Logger logger = StatusLogger.getLogger();
-----
-
-Since StatusLogger implements the Log4j 2 API's Logger interface, all
-the normal Logger methods may be used.
-
-When configuring Log4j it is sometimes necessary to view the generated
-status events. This can be accomplished by adding the status attribute
-to the configuration element or a default value can be provided by
-setting the "Log4jDefaultStatusLevel" system property. Valid values of
-the status attribute are "trace", "debug", "info", "warn", "error" and
-"fatal". The following configuration has the status attribute set to
-debug.
+=== Composite Configuration
+
+Log4j allows multiple configuration files to be used at the same time by specifying them as a list of comma-separated file paths or URLs in the
+xref:manual/systemproperties.adoc#log4j2.configurationFile[log4j2.configurationFile]
+configuration property.
+
+These configuration files are merged into a single configuration file using
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy.html[MergeStrategy]
+service that can be customized using the
+xref:manual/systemproperties.adoc#log4j2.mergeStrategy[log4j2.mergeStrategy]
+configuration property.
+
+The default merge strategy will merge the files using the following rules:
+
+. <<global-configuration-attributes>> in later configurations replace those in previous configurations.
++
+The exception is the `monitorInterval` attribute: the lowest positive value from all the configuration files will be used.
+
+. <<property-substitution,Properties>> from all configurations are aggregated.
+Duplicate properties replace those in previous configurations.
+
+. xref:manual/filters.adoc[Filters] are aggregated under
+xref:manual/filters.adoc#CompositeFilter[CompositeFilter], if more than one filter is defined.
+
+. xref:manual/scripts.adoc[] are aggregated.
+Duplicate definitions replace those in previous configurations.
+
+. xref:manual/appenders.adoc[Appenders] are aggregated.
+Appenders with the same name are **replaced** by those in later configurations, including all their elements.
+
+. <<configuring-loggers,Loggers>> are all aggregated.
+Logger attributes are individually merged, and those in later configurations replace duplicates.
+Appender references on a logger are aggregated, and those in later configurations replace duplicates.
+The strategy merges filters on loggers using the rule above.
+
+[id=format-specific-notes]
+=== Format specific notes
+
+[id=xml-features]
+==== XML format
+
+[id=xml-global-configuration-attributes]
+===== Global configuration attributes
+
+The XML format supports the following additional attributes on the `Configuration` element.
+
+[id=configuration-attribute-schema]
+====== `schema`
+
+[cols="1h,5"]
+|===
+| Type | classpath resource
+| Default value | `null`
+|===
+
+Specifies the path to a classpath resource containing an XML schema.
+
+[id=configuration-attribute-strict]
+====== `strict`
+
+[cols="1h,5"]
+|===
+| Type | `boolean`
+| Default value | `false`
+|===
+
+If set to `true,` all configuration files will be checked against the XML schema provided by the
+<<configuration-attribute-schema>>.
+
+This setting also enables "XML strict mode" and allows one to specify an element's **plugin type** through a `type` attribute instead of the tag name.
+
+[id=xinclude]
+===== [[XInlcude]] XInclude
+XML configuration files can include other files with
+https://www.w3.org/TR/xinclude/[XInclude].
+
+NOTE: The list of `XInclude` and `XPath` features supported depends upon your
+https://docs.oracle.com/javase/{java-target-version}/docs/technotes/guides/xml/jaxp/index.html[JAXP implementation].
+
+Here is an example log4j2.xml file that includes two other files:
+
+.log4j2.xml
[source,xml]
----
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="debug" name="RoutingTest">
- <Properties>
- <Property name="filename">target/rolling1/rollingtest-$${sd:type}.log</Property>
- </Properties>
- <ThresholdFilter level="debug"/>
-
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%m%n"/>
- <ThresholdFilter level="debug"/>
- </Console>
- <Routing name="Routing">
- <Routes pattern="$${sd:type}">
- <Route>
- <RollingFile name="Rolling-${sd:type}" fileName="${filename}"
- filePattern="target/rolling1/test1-${sd:type}.%i.log.gz">
- <PatternLayout>
- <pattern>%d %p %c{1.} [%t] %m%n</pattern>
- </PatternLayout>
- <SizeBasedTriggeringPolicy size="500" />
- </RollingFile>
- </Route>
- <Route ref="STDOUT" key="Audit"/>
- </Routes>
- </Routing>
- </Appenders>
-
- <Loggers>
- <Logger name="EventLogger" level="info" additivity="false">
- <AppenderRef ref="Routing"/>
- </Logger>
-
- <Root level="error">
- <AppenderRef ref="STDOUT"/>
- </Root>
- </Loggers>
-
-</Configuration>
-----
-
-During startup this configuration produces:
-
-....
-2011-11-23 17:08:00,769 DEBUG Generated plugins in 0.003374000 seconds
-2011-11-23 17:08:00,789 DEBUG Calling createProperty on class org.apache.logging.log4j.core.config.Property for element property with params(name="filename", value="target/rolling1/rollingtest-${sd:type}.log")
-2011-11-23 17:08:00,792 DEBUG Calling configureSubstitutor on class org.apache.logging.log4j.core.config.PropertiesPlugin for element properties with params(properties={filename=target/rolling1/rollingtest-${sd:type}.log})
-2011-11-23 17:08:00,794 DEBUG Generated plugins in 0.001362000 seconds
-2011-11-23 17:08:00,797 DEBUG Calling createFilter on class org.apache.logging.log4j.core.filter.ThresholdFilter for element ThresholdFilter with params(level="debug", onMatch="null", onMismatch="null")
-2011-11-23 17:08:00,800 DEBUG Calling createLayout on class org.apache.logging.log4j.core.layout.PatternLayout for element PatternLayout with params(pattern="%m%n", Configuration(RoutingTest), null, charset="null")
-2011-11-23 17:08:00,802 DEBUG Generated plugins in 0.001349000 seconds
-2011-11-23 17:08:00,804 DEBUG Calling createAppender on class org.apache.logging.log4j.core.appender.ConsoleAppender for element Console with params(PatternLayout(%m%n), null, target="null", name="STDOUT", ignoreExceptions="null")
-2011-11-23 17:08:00,804 DEBUG Calling createFilter on class org.apache.logging.log4j.core.filter.ThresholdFilter for element ThresholdFilter with params(level="debug", onMatch="null", onMismatch="null")
-2011-11-23 17:08:00,813 DEBUG Calling createRoute on class org.apache.logging.log4j.core.appender.routing.Route for element Route with params(AppenderRef="null", key="null", Node=Route)
-2011-11-23 17:08:00,823 DEBUG Calling createRoute on class org.apache.logging.log4j.core.appender.routing.Route for element Route with params(AppenderRef="STDOUT", key="Audit", Node=Route)
-2011-11-23 17:08:00,825 DEBUG Calling createRoutes on class org.apache.logging.log4j.core.appender.routing.Routes for element Routes with params(pattern="${sd:type}", routes={Route(type=dynamic default), Route(type=static Reference=STDOUT key='Audit')})
-2011-11-23 17:08:00,827 DEBUG Calling createAppender on class org.apache.logging.log4j.core.appender.routing.RoutingAppender for element Routing with params(name="Routing", ignoreExceptions="null", Routes({Route(type=dynamic default),Route(type=static Reference=STDOUT key='Audit')}), Configuration(RoutingTest), null, null)
-2011-11-23 17:08:00,827 DEBUG Calling createAppenders on class org.apache.logging.log4j.core.config.AppendersPlugin for element appenders with params(appenders={STDOUT, Routing})
-2011-11-23 17:08:00,828 DEBUG Calling createAppenderRef on class org.apache.logging.log4j.core.config.plugins.AppenderRefPlugin for element AppenderRef with params(ref="Routing")
-2011-11-23 17:08:00,829 DEBUG Calling createLogger on class org.apache.logging.log4j.core.config.LoggerConfig for element logger with params(additivity="false", level="info", name="EventLogger", AppenderRef={Routing}, null)
-2011-11-23 17:08:00,830 DEBUG Calling createAppenderRef on class org.apache.logging.log4j.core.config.plugins.AppenderRefPlugin for element AppenderRef with params(ref="STDOUT")
-2011-11-23 17:08:00,831 DEBUG Calling createLogger on class org.apache.logging.log4j.core.config.LoggerConfig$RootLogger for element root with params(additivity="null", level="error", AppenderRef={STDOUT}, null)
-2011-11-23 17:08:00,833 DEBUG Calling createLoggers on class org.apache.logging.log4j.core.config.LoggersPlugin for element loggers with params(loggers={EventLogger, root})
-2011-11-23 17:08:00,834 DEBUG Reconfiguration completed
-2011-11-23 17:08:00,846 DEBUG Calling createLayout on class org.apache.logging.log4j.core.layout.PatternLayout for element PatternLayout with params(pattern="%d %p %c{1.} [%t] %m%n", Configuration(RoutingTest), null, charset="null")
-2011-11-23 17:08:00,849 DEBUG Calling createPolicy on class org.apache.logging.log4j.core.appender.rolling.SizeBasedTriggeringPolicy for element SizeBasedTriggeringPolicy with params(size="500")
-2011-11-23 17:08:00,851 DEBUG Calling createAppender on class org.apache.logging.log4j.core.appender.RollingFileAppender for element RollingFile with params(fileName="target/rolling1/rollingtest-Unknown.log", filePattern="target/rolling1/test1-Unknown.%i.log.gz", append="null", name="Rolling-Unknown", bufferedIO="null", immediateFlush="null", SizeBasedTriggeringPolicy(SizeBasedTriggeringPolicy(size=500)), null, PatternLayout(%d %p %c{1.} [%t] %m%n), null, ignoreExceptions="null")
-2011-11-23 17:08:00,858 DEBUG Generated plugins in 0.002014000 seconds
-2011-11-23 17:08:00,889 DEBUG Reconfiguration started for context sun.misc.Launcher$AppClassLoader@37b90b39
-2011-11-23 17:08:00,890 DEBUG Generated plugins in 0.001355000 seconds
-2011-11-23 17:08:00,959 DEBUG Generated plugins in 0.001239000 seconds
-2011-11-23 17:08:00,961 DEBUG Generated plugins in 0.001197000 seconds
-2011-11-23 17:08:00,965 WARN No Loggers were configured, using default
-2011-11-23 17:08:00,976 DEBUG Reconfiguration completed
-....
-
-If the status attribute is set to error then only error messages will be
-written to the console. This makes troubleshooting configuration errors
-possible. As an example, if the configuration above is changed to have
-the status set to error and the logger declaration is:
+include::example$manual/configuration/xinclude-main.xml[lines=1;18..-1]
+----
+.xinclude-appenders.xml
[source,xml]
----
-<logger name="EventLogger" level="info" additivity="false">
- <AppenderRef ref="Routng"/>
-</logger>
+include::example$manual/configuration/xinclude-appenders.xml[lines=1;18..-1]
----
-the following error message will be produced.
-
-....
-2011-11-24 23:21:25,517 ERROR Unable to locate appender Routng for logger EventLogger
-....
-
-Applications may wish to direct the status output to some other
-destination. This can be accomplished by setting the dest attribute to
-either "err" to send the output to stderr or to a file location or URL.
-This can also be done by insuring the configured status is set to OFF
-and then configuring the application programmatically such as:
-
-[source,java]
+.xinclude-loggers.xml
+[source,xml]
----
-StatusConsoleListener listener = new StatusConsoleListener(Level.ERROR);
-StatusLogger.getLogger().registerListener(listener);
+include::example$manual/configuration/xinclude-loggers.xml[lines=1;18..-1]
----
-[#UnitTestingInMaven]
-== Testing in Maven
+[id=java-properties-features]
+==== Java properties format
+
+[TIP]
+====
+The Java properties format is not well suited to represent hierarchical structures.
-Maven can run unit and functional tests during the build cycle. By
-default, any files placed in `src/test/resources` are automatically
-copied to target/test-classes and are included in the classpath during
-execution of any tests. As such, placing a log4j2-test.xml into this
-directory will cause it to be used instead of a log4j2.xml or
-log4j2.json that might be present. Thus a different log configuration
-can be used during testing than what is used in production.
+Switch to XML to avoid additional dependencies, or choose YAML for a format similar to Java properties but less verbose.
+====
-A second approach, which is extensively used by Log4j 2, is to set the
-log4j2.configurationFile property in the method annotated with
-@BeforeClass in the junit test class. This will allow an arbitrarily
-named file to be used during the test.
+The Java properties configuration format is the most verbose of the available formats.
+To make it more usable, a series of exceptions to the rules in <<configuration-with-properties,Java properties syntax>> have been introduced over time:
-A third approach, also used extensively by Log4j 2, is to use the
-`LoggerContextRule` JUnit test rule which provides additional
-convenience methods for testing. This requires adding the `log4j-core`
-`test-jar` dependency to your test scope dependencies. For example:
+. The following direct children of `Configuration` have predefined prefixes and do not require to specify a `type` attribute:
+* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-AppendersPlugin[Appender container] has a predefined `appender` prefix.
+* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-CustomLevels[Custom levels container] has a predefined `customLevel` prefix.
+* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-LoggersPlugin[Loggers container] has a predefined `logger` prefix.
+* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-PropertiesPlugin[Properties container] has a predefined `property` prefix.
+* The xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-ScriptsPlugin[Scripts container] has a predefined `script` prefix.
-[source,java]
+. Properties that start with `property` are used for <<property-substitution>>.
+Their syntax is:
++
+[source,properties]
+----
+property.<key> = <value>
----
-public class AwesomeTest {
- @Rule
- public LoggerContextRule init = new LoggerContextRule("MyTestConfig.xml");
- @Test
- public void testSomeAwesomeFeature() {
- final LoggerContext ctx = init.getLoggerContext();
- final Logger logger = init.getLogger("org.apache.logging.log4j.my.awesome.test.logger");
- final Configuration cfg = init.getConfiguration();
- final ListAppender app = init.getListAppender("List");
- logger.warn("Test message");
- final List<LogEvent> events = app.getEvents();
- // etc.
- }
-}
+. Properties that start with `customLevel` are used to define custom levels.
+Their syntax is:
++
+[source,properties]
+----
+customLevel.<name> = <intValue>
+----
++
+where `<name>` is the name of the level and `<intValue>` its numerical value.
+
+. The root logger can be configured using properties that start with `rootLogger`.
+
+. A shorthand notation is available that allows users to write:
++
+[source,properties]
----
+rootLogger = INFO, APPENDER
+----
++
+instead of:
++
+[source,properties]
+----
+rootLogger.level = INFO
+rootLogger.appenderRef.0.ref = APPENDER
+----
+
+. All the keys of the form `logger.<name>.appenderRef.<id>`, where `<name>` and `<id>` are arbitrary, are considered appender references.
+
+. To add a filter to a component use a `filter.<id>` prefix instead of just `<id>`.
diff --git a/src/site/antora/modules/ROOT/pages/manual/filters.adoc b/src/site/antora/modules/ROOT/pages/manual/filters.adoc
index ab3ce64fc5..1913771c83 100644
--- a/src/site/antora/modules/ROOT/pages/manual/filters.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/filters.adoc
@@ -14,37 +14,81 @@
See the License for the specific language governing permissions and
limitations under the License.
////
+[id=filters]
= Filters
-Filters allow Log Events to be evaluated to determine if or how they
-should be published. A Filter will be called on one of its `filter`
-methods and will return a `Result`, which is an Enum that has one of 3
-values - `ACCEPT`, `DENY` or `NEUTRAL`.
-
-Filters may be configured in one of four locations:
-
-1. Context-wide Filters are configured directly in the configuration.
-Events that are rejected by these filters will not be passed to loggers
-for further processing. Once an event has been accepted by a
-Context-wide filter it will not be evaluated by any other Context-wide
-Filters nor will the Logger's Level be used to filter the event. The
-event will be evaluated by Logger and Appender Filters however.
-2. Logger Filters are configured on a specified Logger. These are
-evaluated after the Context-wide Filters and the Log Level for the
-Logger. Events that are rejected by these filters will be discarded and
-the event will not be passed to a parent Logger regardless of the
-additivity setting.
-3. Appender Filters are used to determine if a specific Appender should
-handle the formatting and publication of the event.
-4. Appender Reference Filters are used to determine if a Logger should
-route the event to an appender.
+Log4j supports filtering of log events at each level of the logging pipeline using two features:
+
+* the `level` attributes that can be set on loggers and appender references,
+* filter components that can be attached to loggers, appenders, appender references or the global configuration object.
+
+Filters evaluate the parameters of a logging call (context-wide filter) or a log event and return one of three results:
+
+ACCEPT:: The log event is accepted by the filter and goes to the next stage of the logging pipeline,
+
+DENY:: The log event is unconditionally dropped,
+
+NEUTRAL:: Log4j behaves as if the filter was not present.
+
+To decide whether a log event from a certain logger is delivered to a specific appender, the following procedure is followed:
+
+[tabs]
+====
+XML::
++
+[source,xml]
+----
+include::example$manual/filters/filters.xml[lines=1;18..-1]
+----
+
+JSON::
++
+[source,json]
+----
+include::example$manual/filters/filters.json[]
+----
+
+YAML::
++
+[source,yaml]
+----
+include::example$manual/filters/filters.yaml[lines=17..-1]
+----
+
+Java properties::
++
+[source,properties]
+----
+include::example$manual/filters/filters.properties[lines=17..-1]
+----
+====
+
+<1> First the context-wide filter is consulted.
+If it returns `ACCEPT` the log message goes directly to point 3.
+<2> Then Log4j checks the message against the configured logger level.
+<3> The filter configured on a logger is applied next.
+If the logger is additive, the filter on the parent logger is applied recursively until we end up on the logger that references the given appender.
+<4> Next comes the turn of the filter configured on an appender reference,
+<5> followed by a level check against the configured level of the reference.
+<6> The process ends with the filter attached to an appender.
+
+[CAUTION]
+====
+For performance reasons, log events should be filtered as soon as possible in the logging pipeline.
+This reduces the costs (formatting, transfer through an asynchronous barrier) of disabled log events.
+====
+
+[TIP]
+====
+Users migrating from Log4j 1 often replace the `threshold` property of a Log4j 1 appender with a <<ThresholdFilter>> on the equivalent Log4j 2 appender.
+
+Using the `level` property of appender references will give a better performance.
+====
[#BurstFilter]
== BurstFilter
-The BurstFilter provides a mechanism to control the rate at which
-LogEvents are processed by silently discarding events after the maximum
-limit has been reached.
+The BurstFilter provides a mechanism to control the rate at which LogEvents are processed by silently discarding events after the maximum limit has been reached.
.Burst Filter Parameters
[cols="1m,1,4"]
@@ -70,12 +114,12 @@ times the rate.
|onMatch
|String
-|Action to take when the filter matches. May be ACCEPT,
+|Action to take when the filter matches. Can be ACCEPT,
DENY or NEUTRAL. The default value is NEUTRAL.
|onMismatch
|String
-|Action to take when the filter does not match. May
+|Action to take when the filter does not match. Can
be ACCEPT, DENY or NEUTRAL. The default value is DENY.
|===
@@ -106,9 +150,9 @@ A configuration containing the BurstFilter might look like:
[#CompositeFilter]
== CompositeFilter
-The CompositeFilter provides a way to specify more than one filter. It
-is added to the configuration as a filters element and contains other
-filters to be evaluated. The filters element accepts no parameters.
+The CompositeFilter provides a way to specify more than one filter.
+It is added to the configuration as a filter element and contains other filters to be evaluated.
+The filter element accepts no parameters.
A configuration containing the CompositeFilter might look like:
@@ -152,11 +196,9 @@ A configuration containing the CompositeFilter might look like:
[#DynamicThresholdFilter]
== DynamicThresholdFilter
-The DynamicThresholdFilter allows filtering by log level based on
-specific attributes. For example, if the user's loginId is being
-captured in the ThreadContext Map then it is possible to enable debug
-logging for only that user. If the log event does not contain the
-specified ThreadContext item NEUTRAL will be returned.
+The DynamicThresholdFilter allows filtering by log level based on specific attributes.
+For example, if the user's loginId is being captured in the ThreadContext Map then it is possible to enable debug logging for only that user.
+If the log event does not contain the specified ThreadContext item NEUTRAL will be returned.
.Dynamic Threshold Filter Parameters
[cols="1m,1,4"]
@@ -171,7 +213,7 @@ specified ThreadContext item NEUTRAL will be returned.
|String
|Level of messages to be filtered. The default
threshold only applies if the log event contains the specified
-ThreadContext Map item and its value does not match any key in the
+ThreadContext Map item and its value do not match any key in the
key/value pairs.
|keyValuePair
@@ -182,12 +224,12 @@ key matches.
|onMatch
|String
-|Action to take when the filter matches. May be ACCEPT,
+|Action to take when the filter matches. Can be ACCEPT,
DENY or NEUTRAL. The default value is NEUTRAL.
|onMismatch
|String
-|Action to take when the filter does not match. May
+|Action to take when the filter does not match. Can
be ACCEPT, DENY or NEUTRAL. The default value is DENY.
|===
@@ -271,8 +313,7 @@ The filter will return `onMismatch` result (i.e., `DENY`, the default) for log e
[#MapFilter]
== MapFilter
-The MapFilter allows filtering against data elements that are in a
-MapMessage.
+The MapFilter allows filtering against data elements that are in a MapMessage.
.Map Filter Parameters
[cols="1m,1,4"]
@@ -282,7 +323,7 @@ MapMessage.
|keyValuePair
|KeyValuePair[]
|One or more KeyValuePair elements that
-define the key in the map and the value to match on. If the same key is
+define the key in the map and the value to match. If the same key is
specified more than once then the check for that key will automatically
be an "or" since a Map can only contain a single value.
@@ -294,17 +335,16 @@ key/value pairs must match.
|onMatch
|String
-|Action to take when the filter matches. May be ACCEPT,
+|Action to take when the filter matches. Can be ACCEPT,
DENY or NEUTRAL. The default value is NEUTRAL.
|onMismatch
|String
-|Action to take when the filter does not match. May
+|Action to take when the filter does not match. Can
be ACCEPT, DENY or NEUTRAL. The default value is DENY.
|===
-As in this configuration, the MapFilter can be used to log particular
-events:
+As in this configuration, the MapFilter can be used to log particular events:
[source,xml]
----
@@ -332,8 +372,7 @@ events:
</Configuration>
----
-This sample configuration will exhibit the same behavior as the
-preceding example since the only logger configured is the root.
+This sample configuration will exhibit the same behavior as the preceding example since the only logger configured is the root.
[source,xml]
----
@@ -362,9 +401,7 @@ preceding example since the only logger configured is the root.
</Configuration>
----
-This third sample configuration will exhibit the same behavior as the
-preceding examples since the only logger configured is the root and the
-root is only configured with a single appender reference.
+This third sample configuration will exhibit the same behavior as the preceding examples since the only logger configured is the root and the root is only configured with a single appender reference.
[source,xml]
----
@@ -396,9 +433,8 @@ root is only configured with a single appender reference.
[#MarkerFilter]
== MarkerFilter
-The MarkerFilter compares the configured Marker value against the Marker
-that is included in the LogEvent. A match occurs when the Marker name
-matches either the Log Event's Marker or one of its parents.
+The MarkerFilter compares the configured Marker value against the Marker that is included in the LogEvent.
+A match occurs when the Marker name matches either the Log Event's Marker or one of its parents.
.Marker Filter Parameters
[cols="1m,1,4"]
@@ -411,17 +447,16 @@ matches either the Log Event's Marker or one of its parents.
|onMatch
|String
-|Action to take when the filter matches. May be ACCEPT,
+|Action to take when the filter matches. Can be ACCEPT,
DENY or NEUTRAL. The default value is NEUTRAL.
|onMismatch
|String
-|Action to take when the filter does not match. May
+|Action to take when the filter does not match. Can
be ACCEPT, DENY or NEUTRAL. The default value is DENY.
|===
-A sample configuration that only allows the event to be written by the
-appender if the Marker matches:
+A sample configuration that only allows the event to be written by the appender if the Marker matches:
[source,xml]
----
@@ -448,7 +483,9 @@ appender if the Marker matches:
[#MutableThreadContextMapFilter]
== MutableThreadContextMapFilter
-The MutableThreadContextMapFilter or MutableContextMapFilter allows filtering against data elements that are in the current context. By default this is the ThreadContext Map. The values to compare are defined externally and can be periodically polled for changes.
+The MutableThreadContextMapFilter or MutableContextMapFilter allows filtering against data elements that are in the current context.
+By default, this is the ThreadContext Map.
+The values to compare are defined externally and can be periodically polled for changes.
.Mutable Context Map Filter Parameters
[cols="1m,1,4"]
@@ -467,21 +504,20 @@ key/value pairs must match.
|pollInterval
|int
-|The number of seconds to wait before checking to see if the configuration has been modified. When using HTTP or HTTPS the server must support the If-Modified-Since header and return a Last-Modified header containing the date and time the file was last modified. Note that by default only the https, file, and jar protocols are allowed. Support for other protocols can be enabled by specifying them in the log4j2.Configuration.allowedProtocols system property
+|The number of seconds to wait before checking to see if the configuration has been modified. When using HTTP or HTTPS the server must support the If-Modified-Since header and return a Last-Modified header containing the date and time the file was last modified. Note that by default only the https, file, and jar protocols are allowed. Support for other protocols can be enabled by specifying them in the `log4j2.Configuration.allowedProtocols` system property
|onMatch
|String
-|Action to take when the filter matches. May be ACCEPT,
+|Action to take when the filter matches. Can be ACCEPT,
DENY or NEUTRAL. The default value is NEUTRAL.
|onMismatch
|String
-|Action to take when the filter does not match. May
+|Action to take when the filter does not match. Can
be ACCEPT, DENY or NEUTRAL. The default value is DENY.
|===
-A sample configuration that only allows the event to be written by the
-appender if the Marker matches:
+A sample configuration that only allows the event to be written by the appender if the Marker matches:
[source,xml]
----
@@ -505,7 +541,9 @@ appender if the Marker matches:
</Root>
</Loggers>
----
+
The configuration file supplied to the filter should look similar to:
+
[source,json]
----
{
@@ -519,8 +557,8 @@ The configuration file supplied to the filter should look similar to:
[#NoMarkerFilter]
== NoMarkerFilter
-The NoMarkerFilter checks that there is no marker included in the LogEvent. A match occurs when there is no
-marker in the Log Event.
+The NoMarkerFilter checks that there is no marker included in the LogEvent.
+A match occurs when there is no marker in the Log Event.
.No Marker Filter Parameters
[cols="1m,1,3"]
@@ -529,17 +567,16 @@ marker in the Log Event.
|onMatch
|String
-|Action to take when the filter matches. May be ACCEPT,
+|Action to take when the filter matches. Can be ACCEPT,
DENY or NEUTRAL. The default value is NEUTRAL.
|onMismatch
|String
-|Action to take when the filter does not match. May
+|Action to take when the filter does not match. Can
be ACCEPT, DENY or NEUTRAL. The default value is DENY.
|===
-A sample configuration that only allows the event to be written by the
-appender if no marker is there:
+A sample configuration that only allows the event to be written by the appender if no marker is there:
[source,xml]
----
@@ -566,8 +603,7 @@ appender if no marker is there:
[#RegexFilter]
== RegexFilter
-The RegexFilter allows the formatted or unformatted message to be
-compared against a regular expression.
+The RegexFilter allows the formatted or unformatted message to be compared against a regular expression.
.Regex Filter Parameters
[cols="1m,1,4"]
@@ -581,22 +617,21 @@ compared against a regular expression.
|useRawMsg
|boolean
|If true the unformatted message will be used,
-otherwise the formatted message will be used. The default value is
+otherwise, the formatted message will be used. The default value is
false.
|onMatch
|String
-|Action to take when the filter matches. May be ACCEPT,
+|Action to take when the filter matches. Can be ACCEPT,
DENY or NEUTRAL. The default value is NEUTRAL.
|onMismatch
|String
-|Action to take when the filter does not match. May
+|Action to take when the filter does not match. Can
be ACCEPT, DENY or NEUTRAL. The default value is DENY.
|===
-A sample configuration that only allows the event to be written by the
-appender if it contains the word "test":
+A sample configuration that only allows the event to be written by the appender if it contains the word "test":
[source,xml]
----
@@ -621,7 +656,6 @@ appender if it contains the word "test":
----
[[Script]]
-
The ScriptFilter executes a script that returns true or false.
.Script Filter Parameters
@@ -635,12 +669,12 @@ The ScriptFilter executes a script that returns true or false.
|onMatch
|String
-|Action to take when the script returns true. May be
+|Action to take when the script returns true. Can be
ACCEPT, DENY or NEUTRAL. The default value is NEUTRAL.
|onMismatch
|String
-|Action to take when the filter returns false. May
+|Action to take when the filter returns false. Can
be ACCEPT, DENY or NEUTRAL. The default value is DENY.
|===
@@ -693,14 +727,12 @@ Throwable as part of the Message.
|substitutor
|StrSubstitutor
-|The StrSubstitutor used to replace lookup variables.
+|The StrSubstitutor is used to replace lookup variables.
|===
-The sample below shows how to declare script fields and then reference
-them in specific components. See
-xref:manual/appenders.adoc#ScriptCondition[ScriptCondition] for an example of
-how the `ScriptPlugin` element can be used to embed script code directly in
-the configuration.
+The sample below shows how to declare script fields and then reference them in specific components.
+See
+xref:manual/appenders.adoc#ScriptCondition[ScriptCondition] for an example of how the `ScriptPlugin` element can be used to embed script code directly in the configuration.
[source,xml]
----
@@ -741,8 +773,7 @@ the configuration.
[#StructuredDataFilter]
== StructuredDataFilter
-The StructuredDataFilter is a MapFilter that also allows filtering on
-the event id, type and message.
+The StructuredDataFilter is a MapFilter that also allows filtering on the event id, type and message.
.StructuredData Filter Parameters
[cols="1m,1,4"]
@@ -753,7 +784,7 @@ the event id, type and message.
|KeyValuePair[]
|One or more KeyValuePair elements that
define the key in the map and the value to match on. "id", "id.name",
-"type", and "message" should be used to match on the StructuredDataId,
+"type", and "message" should be used to match the StructuredDataId,
the name portion of the StructuredDataId, the type, and the formatted
message respectively. If the same key is specified more than once then
the check for that key will automatically be an "or" since a Map can
@@ -767,17 +798,16 @@ key/value pairs must match.
|onMatch
|String
-|Action to take when the filter matches. May be ACCEPT,
+|Action to take when the filter matches. Can be ACCEPT,
DENY or NEUTRAL. The default value is NEUTRAL.
|onMismatch
|String
-|Action to take when the filter does not match. May
+|Action to take when the filter does not match. Can
be ACCEPT, DENY or NEUTRAL. The default value is DENY.
|===
-As in this configuration, the StructuredDataFilter can be used to log
-particular events:
+As in this configuration, the StructuredDataFilter can be used to log particular events:
[source,xml]
----
@@ -808,9 +838,8 @@ particular events:
[#ThreadContextMapFilter]
== ThreadContextMapFilter
-The ThreadContextMapFilter or ContextMapFilter allows filtering against
-data elements that are in the current context. By default this is the
-ThreadContext Map.
+The ThreadContextMapFilter or ContextMapFilter allows filtering against data elements that are in the current context.
+By default, this is the ThreadContext Map.
.Context Map Filter Parameters
[cols="1m,1,4"]
@@ -820,7 +849,7 @@ ThreadContext Map.
|keyValuePair
|KeyValuePair[]
|One or more KeyValuePair elements that
-define the key in the map and the value to match on. If the same key is
+define the key in the map and the value to match. If the same key is
specified more than once then the check for that key will automatically
be an "or" since a Map can only contain a single value.
@@ -832,12 +861,12 @@ key/value pairs must match.
|onMatch
|String
-|Action to take when the filter matches. May be ACCEPT,
+|Action to take when the filter matches. Can be ACCEPT,
DENY or NEUTRAL. The default value is NEUTRAL.
|onMismatch
|String
-|Action to take when the filter does not match. May
+|Action to take when the filter does not match. Can
be ACCEPT, DENY or NEUTRAL. The default value is DENY.
|===
@@ -901,10 +930,9 @@ The ContextMapFilter can also be applied to a logger for filtering:
[#ThresholdFilter]
== ThresholdFilter
-This filter returns the onMatch result if the level in the LogEvent is
-the same or more specific than the configured level and the onMismatch
-value otherwise. For example, if the ThresholdFilter is configured with
-Level ERROR and the LogEvent contains Level DEBUG then the onMismatch
+This filter returns the onMatch result if the level in the LogEvent is the same or more specific than the configured level and the `onMismatch`
+value otherwise.
+For example, if the ThresholdFilter is configured with Level ERROR and the LogEvent contains Level DEBUG then the `onMismatch`
value will be returned since ERROR events are more specific than DEBUG.
.Threshold Filter Parameters
@@ -914,21 +942,20 @@ value will be returned since ERROR events are more specific than DEBUG.
|level
|String
-|A valid Level name to match on.
+|A valid Level name to match.
|onMatch
|String
-|Action to take when the filter matches. May be ACCEPT,
+|Action to take when the filter matches. Can be ACCEPT,
DENY or NEUTRAL. The default value is NEUTRAL.
|onMismatch
|String
-|Action to take when the filter does not match. May
+|Action to take when the filter does not match. Can
be ACCEPT, DENY or NEUTRAL. The default value is DENY.
|===
-A sample configuration that only allows the event to be written by the
-appender if the level matches:
+A sample configuration that only allows the event to be written by the appender if the level matches:
[source,xml]
----
@@ -955,8 +982,7 @@ appender if the level matches:
[#TimeFilter]
== TimeFilter
-The time filter can be used to restrict filter to only a certain portion
-of the day.
+The time filter can be used to restrict the filter to only a certain portion of the day.
.Time Filter Parameters
[cols="1m,1,4"]
@@ -979,17 +1005,16 @@ timestamp.
|onMatch
|String
-|Action to take when the filter matches. May be ACCEPT,
+|Action to take when the filter matches. Can be ACCEPT,
DENY or NEUTRAL. The default value is NEUTRAL.
|onMismatch
|String
-|Action to take when the filter does not match. May
+|Action to take when the filter does not match. Can
be ACCEPT, DENY or NEUTRAL. The default value is DENY.
|===
-A sample configuration that only allows the event to be written by the
-appender from 5:00 to 5:30 am each day using the default timezone:
+A sample configuration that only allows the event to be written by the appender from 5:00 to 5:30 am each day using the default timezone:
[source,xml]
----
diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
index 45242d866f..62aafe1483 100644
--- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
@@ -621,12 +621,10 @@ log4j2.properties::
+
[source,properties]
----
-appender.0.type = Console
-appender.0.name = CONSOLE
-appender.0.layout = PatternLayout # <1>
-appender.0.layout.pattern = %d [%t] %5p %c{1.} - %m%n
-rootLogger.level = INFO
-rootLogger.appenderRef.0.ref = CONSOLE
+Appenders.Console.name = CONSOLE
+Appenders.Console.PatternLayout.pattern = %d [%t] %5p %c{1.} - %m%n # <1>
+Loggers.Root.level = INFO
+Loggers.Root.AppenderRef.ref = CONSOLE
----
====
@@ -634,91 +632,7 @@ rootLogger.appenderRef.0.ref = CONSOLE
In order to use these formats, the following additional dependencies are required:
-[tabs]
-====
-
-Maven::
-+
-[tabs]
-=====
-
-log4j2.xml::
-+
-JPMS users need to add:
-+
-[source,java]
-----
-module foo.bar {
- requires java.xml;
-}
-----
-+
-to their `module-info.java` descriptor.
-
-log4j2.json::
-+
-No dependency required.
-
-log4j2.yaml::
-+
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-config-yaml</artifactId>
-</dependency>
-----
-
-log4j2.properties::
-+
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-config-properties</artifactId>
-</dependency>
-----
-
-=====
-
-Gradle::
-+
-[tabs]
-=====
-
-log4j2.xml::
-+
-JPMS users need to add:
-+
-[source,java]
-----
-module foo.bar {
- requires java.xml;
-}
-----
-+
-to their `module-info.java` descriptor.
-
-log4j2.json::
-+
-No dependency required.
-
-log4j2.yaml::
-+
-[source,groovy]
-----
-runtimeOnly 'org.apache.logging.log4j:log4j-config-yaml'
-----
-
-log4j2.properties::
-+
-[source,groovy]
-----
-runtimeOnly 'org.apache.logging.log4j:log4j-config-properties'
-----
-
-=====
-====
+include::partial$configuration-file-format-deps.adoc[]
[#impl-jul]
=== Installing JUL
diff --git a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
index 214011130b..e113bb1460 100644
--- a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
@@ -30,11 +30,27 @@ The root class for layouts that use a Charset is
default is UTF-8. Each layout that extends `AbstractStringLayout` can
provide its own default. See each layout below.
-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.
+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.
+
+[#common-concerns]
+== Common concerns
+
+[#location-information]
+=== Location information
+
+Computing the location information of a logging statement is an expensive operation.
+For this reason many Log4j components implement the
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/LocationAware.html[LocationAware]
+interface to only compute location information when needed.
+
+While the methods of determining if location information is required are specific to each layout, most layouts implement `LocationAware`.
+
+[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].
+====
[#CSVLayouts]
== CSV Layouts
@@ -333,7 +349,7 @@ JSON Template Layout will render JSON documents as follows:
See xref:manual/json-template-layout.adoc[JSON Template Layout] page for the complete
documentation.
-[#PatternLayout]
+[#pattern-layout]
== Pattern Layout
A flexible layout configurable with pattern string. The goal of this
diff --git a/src/site/antora/modules/ROOT/pages/manual/migration.adoc b/src/site/antora/modules/ROOT/pages/manual/migration.adoc
index 202cae8d91..62a2aa54b9 100644
--- a/src/site/antora/modules/ROOT/pages/manual/migration.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/migration.adoc
@@ -39,8 +39,8 @@ image:whichjar-log4j-1.2-api.png[Using log4j 2 via the log4j 1.x API]
For most applications this is sufficient.
This is a low-effort way to migrate, and may also allow for migration to proceed gradually over time.
-[#EnablingLog4j12Bridge]
-=== Enabling the Log4j 1.x bridge
+[#enabling-the-log4j-1-x-bridge]
+=== [[EnablingLog4j12Bridge]]Enabling the Log4j 1.x bridge
Enable the Log4j 1.x bridge via one of the following steps:
diff --git a/src/site/antora/modules/ROOT/pages/manual/scripts.adoc b/src/site/antora/modules/ROOT/pages/manual/scripts.adoc
new file mode 100644
index 0000000000..df835933db
--- /dev/null
+++ b/src/site/antora/modules/ROOT/pages/manual/scripts.adoc
@@ -0,0 +1,127 @@
+////
+ 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.
+////
+[id=scripts]
+= Scripts
+
+Log4j provides support for
+https://docs.oracle.com/javase/6/docs/technotes/guides/scripting/[JSR
+223] scripting languages to be used in some of its components.
+
+[WARNING]
+====
+In order to enable a scripting language, its name must be included in the
+xref:manual/systemproperties.adoc#log4j2.scriptEnableLanguages[log4j2.scriptEnableLanguages]
+configuration property.
+====
+
+Each component that allows scripts can contain on of the following configuration elements:
+
+Script::
++
+This element specifies the content of the script directly and has:
++
+--
+* a required `language` configuration attribute that specifies the name of the JSR 223 language to use,
+* a required `scriptText` configuration attribute that contains the text of the script.
+In the XML configuration format, the text of the script can also be written as content of the `<Script>` XML element.
+This allows the usage of a `CDATA` block.
+--
++
+The element can be assigned a name using the `name` configuration attribute.
++
+See also
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-Script[Plugin reference].
+
+ScriptFile::
++
+This element points to an external script file and has:
++
+--
+* a required `path` attribute that points to the path to a file name.
+* an optional `language` attribute that specifies the name of the JSR 223 language to use.
+If not provided, the language is deduced from the extension of the file.
+* an optional `isWatched` attribute.
+If set to `true` the script file will be monitored for changes.
+--
++
+The element can be assigned a name using the `name` configuration attribute.
++
+See also
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-ScriptFile[Plugin reference].
+
+ScriptRef::
++
+This element references a **named** script from the global
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-ScriptsPlugin[Scripts]
+container plugin in the configuration file.
++
+See also
+xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-ScriptRef[Plugin reference].
+
+The environment in which the script runs is different for each Log4j script-based component.
+
+[tabs]
+====
+XML::
++
+[source,xml]
+----
+include::example$configuration/scripts.xml[lines=1;18..-1]
+----
+
+JSON::
++
+[source,json]
+----
+include::example$configuration/scripts.json[]
+----
+
+YAML::
++
+[source,yaml]
+----
+include::example$configuration/scripts.yaml[lines=17..-1]
+----
+
+Java properties::
++
+[source,properties]
+----
+include::example$configuration/scripts.properties[lines=17..-1]
+----
+====
+
+[id=a-special-note-on-beanshell]
+== A special note on Beanshell
+
+JSR 223 scripting engines are supposed to identify that they support the
+https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/script/Compilable.html[Compilable]
+interface if they support compiling their scripts.
+
+Beanshell does extend the `Compilable` interface, but an attempt to compile a script ends up in an
+https://docs.oracle.com/javase/{java-target-version}/docs/api/java/lang/Error.html[Error]
+being thrown.
+Log4j catches the throwable, but issues a warning in the status logger.
+
+----
+2015-09-27 16:13:23,095 main DEBUG Script BeanShellSelector is compilable
+2015-09-27 16:13:23,096 main WARN Error compiling script java.lang.Error: unimplemented
+ at bsh.engine.BshScriptEngine.compile(BshScriptEngine.java:175)
+ at bsh.engine.BshScriptEngine.compile(BshScriptEngine.java:154)
+ at org.apache.logging.log4j.core.script.ScriptManager$MainScriptRunner.<init>(ScriptManager.java:125)
+ at org.apache.logging.log4j.core.script.ScriptManager.addScript(ScriptManager.java:94)
+----
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/pages/plugin-reference.adoc b/src/site/antora/modules/ROOT/pages/plugin-reference.adoc
index c3417aa050..ebcc9b60ba 100644
--- a/src/site/antora/modules/ROOT/pages/plugin-reference.adoc
+++ b/src/site/antora/modules/ROOT/pages/plugin-reference.adoc
@@ -18,3 +18,770 @@ Licensed to the Apache Software Foundation (ASF) under one or more
This file is a stub.
Its content will be auto-generated during build.
+
+The purpose of the sections below is to remove IDE errors while editing configuration files.
+
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-AbstractBuilder]
+== `AbstractBuilder`
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-appender-AppenderBuilder]
+== `AppenderBuilder`
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-appender-AsyncAppenderBuilder]
+== org.apache.log4j.AsyncAppender
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-appender-ConsoleAppenderBuilder]
+== org.apache.log4j.ConsoleAppender
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-appender-DailyRollingFileAppenderBuilder]
+== org.apache.log4j.DailyRollingFileAppender
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-appender-EnhancedRollingFileAppenderBuilder]
+== org.apache.log4j.rolling.RollingFileAppender
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-appender-FileAppenderBuilder]
+== org.apache.log4j.FileAppender
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-appender-NullAppenderBuilder]
+== org.apache.log4j.varia.NullAppender
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-appender-RewriteAppenderBuilder]
+== org.apache.log4j.rewrite.RewriteAppender
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-appender-RollingFileAppenderBuilder]
+== org.apache.log4j.RollingFileAppender
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-appender-SocketAppenderBuilder]
+== org.apache.log4j.net.SocketAppender
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-appender-SyslogAppenderBuilder]
+== org.apache.log4j.net.SyslogAppender
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-Builder]
+== `Builder`
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-filter-DenyAllFilterBuilder]
+== org.apache.log4j.varia.DenyAllFilter
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-filter-FilterBuilder]
+== `FilterBuilder`
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-filter-LevelMatchFilterBuilder]
+== org.apache.log4j.varia.LevelMatchFilter
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-filter-LevelRangeFilterBuilder]
+== org.apache.log4j.varia.LevelRangeFilter
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-filter-StringMatchFilterBuilder]
+== org.apache.log4j.varia.StringMatchFilter
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-layout-HtmlLayoutBuilder]
+== org.apache.log4j.HTMLLayout
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-layout-LayoutBuilder]
+== `LayoutBuilder`
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-layout-PatternLayoutBuilder]
+== org.apache.log4j.PatternLayout
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-layout-SimpleLayoutBuilder]
+== org.apache.log4j.SimpleLayout
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-layout-TTCCLayoutBuilder]
+== org.apache.log4j.TTCCLayout
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-layout-XmlLayoutBuilder]
+== org.apache.log4j.xml.XMLLayout
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-Parser]
+== `Parser`
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-rolling-CompositeTriggeringPolicyBuilder]
+== org.apache.log4j.rolling.CompositeTriggeringPolicy
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-rolling-SizeBasedTriggeringPolicyBuilder]
+== org.apache.log4j.rolling.SizeBasedTriggeringPolicy
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-rolling-TimeBasedRollingPolicyBuilder]
+== org.apache.log4j.rolling.TimeBasedRollingPolicy
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-builders-rolling-TriggeringPolicyBuilder]
+== `TriggeringPolicyBuilder`
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-config-PropertiesConfigurationFactory]
+== Log4j1PropertiesConfigurationFactory
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-layout-Log4j1SyslogLayout]
+== Log4j1SyslogLayout
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-layout-Log4j1XmlLayout]
+== Log4j1XmlLayout
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-pattern-Log4j1LevelPatternConverter]
+== Log4j1LevelPatternConverter
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-pattern-Log4j1MdcPatternConverter]
+== Log4j1MdcPatternConverter
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-pattern-Log4j1NdcPatternConverter]
+== Log4j1NdcPatternConverter
+[#org-apache-logging-log4j_log4j-1-2-api_org-apache-log4j-xml-XmlConfigurationFactory]
+== Log4j1XmlConfigurationFactory
+[#org-apache-logging-log4j_log4j-cassandra_com-datastax-driver-core-BatchStatement-Type]
+== `Type`
+[#org-apache-logging-log4j_log4j-cassandra_org-apache-logging-log4j-cassandra-CassandraAppender]
+== Cassandra
+[#org-apache-logging-log4j_log4j-core_com-conversantmedia-util-concurrent-SpinPolicy]
+== `SpinPolicy`
+[#org-apache-logging-log4j_log4j-core_org-apache-commons-csv-QuoteMode]
+== `QuoteMode`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-AbstractLifeCycle]
+== `AbstractLifeCycle`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-AbstractAppender]
+== `AbstractAppender`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-AbstractOutputStreamAppender]
+== `AbstractOutputStreamAppender`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-AbstractWriterAppender]
+== `AbstractWriterAppender`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-Appender]
+== `Appender`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-AppenderSet]
+== AppenderSet
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-AsyncAppender]
+== Async
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-ConsoleAppender]
+== Console
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-ConsoleAppender-Target]
+== `Target`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-CountingNoOpAppender]
+== CountingNoOp
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-AbstractDatabaseAppender]
+== `AbstractDatabaseAppender`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-ColumnMapping]
+== ColumnMapping
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-AbstractConnectionSource]
+== `AbstractConnectionSource`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-AbstractDriverManagerConnectionSource]
+== `AbstractDriverManagerConnectionSource`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-ColumnConfig]
+== Column
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-ConnectionSource]
+== `ConnectionSource`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-DataSourceConnectionSource]
+== DataSource
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-DriverManagerConnectionSource]
+== DriverManager
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-FactoryMethodConnectionSource]
+== ConnectionFactory
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-db-jdbc-JdbcAppender]
+== JDBC
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-FailoverAppender]
+== Failover
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-FailoversPlugin]
+== failovers
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-FileAppender]
+== File
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-HttpAppender]
+== Http
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-MemoryMappedFileAppender]
+== MemoryMappedFile
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-mom-jeromq-JeroMqAppender]
+== JeroMQ
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-mom-JmsAppender]
+== JMS
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-mom-kafka-KafkaAppender]
+== Kafka
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-nosql-NoSqlAppender]
+== NoSql
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-NullAppender]
+== Null
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-OutputStreamAppender]
+== OutputStream
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-RandomAccessFileAppender]
+== RandomAccessFile
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rewrite-LoggerNameLevelRewritePolicy]
+== LoggerNameLevelRewritePolicy
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rewrite-MapRewritePolicy]
+== MapRewritePolicy
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rewrite-PropertiesRewritePolicy]
+== PropertiesRewritePolicy
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rewrite-RewriteAppender]
+== Rewrite
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rewrite-RewritePolicy]
+== `RewritePolicy`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-AbstractRolloverStrategy]
+== `AbstractRolloverStrategy`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-AbstractTriggeringPolicy]
+== `AbstractTriggeringPolicy`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-AbstractAction]
+== `AbstractAction`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-AbstractPathAction]
+== `AbstractPathAction`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-Action]
+== `Action`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-DeleteAction]
+== Delete
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-Duration]
+== `Duration`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-IfAccumulatedFileCount]
+== IfAccumulatedFileCount
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-IfAccumulatedFileSize]
+== IfAccumulatedFileSize
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-IfAll]
+== IfAll
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-IfAny]
+== IfAny
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-IfFileName]
+== IfFileName
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-IfLastModified]
+== IfLastModified
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-IfNot]
+== IfNot
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-PathCondition]
+== `PathCondition`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-PathSortByModificationTime]
+== SortByModificationTime
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-PathSorter]
+== `PathSorter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-PosixViewAttributeAction]
+== PosixViewAttribute
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-action-ScriptCondition]
+== ScriptCondition
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-CompositeTriggeringPolicy]
+== Policies
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-CronTriggeringPolicy]
+== CronTriggeringPolicy
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-DefaultRolloverStrategy]
+== DefaultRolloverStrategy
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-DirectFileRolloverStrategy]
+== `DirectFileRolloverStrategy`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-DirectWriteRolloverStrategy]
+== DirectWriteRolloverStrategy
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-RollingFileAppender]
+== RollingFile
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-NoOpTriggeringPolicy]
+== NoOpTriggeringPolicy
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-OnStartupTriggeringPolicy]
+== OnStartupTriggeringPolicy
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-RollingRandomAccessFileAppender]
+== RollingRandomAccessFile
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-RolloverStrategy]
+== `RolloverStrategy`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-SizeBasedTriggeringPolicy]
+== SizeBasedTriggeringPolicy
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-TimeBasedTriggeringPolicy]
+== TimeBasedTriggeringPolicy
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-rolling-TriggeringPolicy]
+== `TriggeringPolicy`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-routing-IdlePurgePolicy]
+== IdlePurgePolicy
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-routing-PurgePolicy]
+== `PurgePolicy`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-routing-Route]
+== Route
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-routing-Routes]
+== Routes
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-routing-RoutingAppender]
+== Routing
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-ScriptAppenderSelector]
+== ScriptAppenderSelector
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-SmtpAppender]
+== SMTP
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-SocketAppender]
+== `SocketAppender`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-SyslogAppender]
+== Syslog
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-WriterAppender]
+== Writer
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-async-ArrayBlockingQueueFactory]
+== ArrayBlockingQueue
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-async-AsyncLoggerConfig]
+== asyncLogger
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-async-AsyncLoggerConfig-RootLogger]
+== asyncRoot
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-async-AsyncWaitStrategyFactoryConfig]
+== AsyncWaitStrategyFactory
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-async-BlockingQueueFactory]
+== `BlockingQueueFactory`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-async-DisruptorBlockingQueueFactory]
+== DisruptorBlockingQueue
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-async-JCToolsBlockingQueueFactory]
+== JCToolsBlockingQueue
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-async-JCToolsBlockingQueueFactory-WaitStrategy]
+== `WaitStrategy`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-async-LinkedTransferQueueFactory]
+== LinkedTransferQueue
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-AppenderRef]
+== AppenderRef
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-AppendersPlugin]
+== appenders
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-Arbiter]
+== `Arbiter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-ClassArbiter]
+== ClassArbiter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-DefaultArbiter]
+== DefaultArbiter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-EnvironmentArbiter]
+== EnvironmentArbiter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-ScriptArbiter]
+== ScriptArbiter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-SelectArbiter]
+== Select
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-arbiters-SystemPropertyArbiter]
+== SystemPropertyArbiter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-builder-api-ConfigurationBuilderFactory]
+== `ConfigurationBuilderFactory`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Configuration]
+== Configuration
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-ConfigurationAware]
+== `ConfigurationAware`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-ConfigurationFactory]
+== `ConfigurationFactory`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-CustomLevelConfig]
+== CustomLevel
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-CustomLevels]
+== CustomLevels
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-DefaultAdvertiser]
+== default
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-HttpWatcher]
+== http
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-json-JsonConfigurationFactory]
+== JsonConfigurationFactory
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-LoggerConfig]
+== `LoggerConfig`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-LoggerConfig-RootLogger]
+== root
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-LoggersPlugin]
+== loggers
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverter]
+== `TypeConverter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-BigDecimalConverter]
+== BigDecimal
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-BigIntegerConverter]
+== BigInteger
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-BooleanConverter]
+== Boolean
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-ByteArrayConverter]
+== ByteArray
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-ByteConverter]
+== Byte
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-CharacterConverter]
+== Character
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-CharArrayConverter]
+== CharacterArray
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-CharsetConverter]
+== Charset
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-ClassConverter]
+== Class
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-CronExpressionConverter]
+== CronExpression
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-DoubleConverter]
+== Double
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-DurationConverter]
+== Duration
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-FileConverter]
+== File
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-FloatConverter]
+== Float
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-InetAddressConverter]
+== InetAddress
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-IntegerConverter]
+== Integer
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-LevelConverter]
+== Level
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-LongConverter]
+== Long
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-PathConverter]
+== Path
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-PatternConverter]
+== Pattern
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-SecurityProviderConverter]
+== SecurityProvider
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-ShortConverter]
+== Short
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-StringConverter]
+== String
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-UriConverter]
+== URI
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-UrlConverter]
+== URL
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-plugins-convert-TypeConverters-UuidConverter]
+== UUID
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-PropertiesPlugin]
+== properties
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-properties-PropertiesConfigurationFactory]
+== PropertiesConfigurationFactory
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Property]
+== property
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-ScriptsPlugin]
+== scripts
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-xml-XmlConfigurationFactory]
+== XmlConfigurationFactory
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-yaml-YamlConfigurationFactory]
+== YamlConfigurationFactory
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-AbstractFilterable]
+== `AbstractFilterable`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-AbstractFilter]
+== `AbstractFilter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-Filter]
+== `Filter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-BurstFilter]
+== BurstFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-CompositeFilter]
+== filters
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-DenyAllFilter]
+== DenyAllFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-DynamicThresholdFilter]
+== DynamicThresholdFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-Filterable]
+== `Filterable`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-LevelMatchFilter]
+== LevelMatchFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-LevelRangeFilter]
+== LevelRangeFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-MapFilter]
+== `MapFilter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-MarkerFilter]
+== MarkerFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-MutableThreadContextMapFilter]
+== MutableThreadContextMapFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-NoMarkerFilter]
+== NoMarkerFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-RegexFilter]
+== RegexFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-Filter-Result]
+== `Result`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-ScriptFilter]
+== ScriptFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-StringMatchFilter]
+== StringMatchFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-StructuredDataFilter]
+== StructuredDataFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-ThreadContextMapFilter]
+== ThreadContextMapFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-ThresholdFilter]
+== ThresholdFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-filter-TimeFilter]
+== TimeFilter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-impl-LocationAware]
+== `LocationAware`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-AbstractCsvLayout]
+== `AbstractCsvLayout`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-AbstractJacksonLayout]
+== `AbstractJacksonLayout`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-AbstractLayout]
+== `AbstractLayout`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-AbstractStringLayout]
+== `AbstractStringLayout`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-Layout]
+== `Layout`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-CsvLogEventLayout]
+== CsvLogEventLayout
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-CsvParameterLayout]
+== CsvParameterLayout
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-Encoder]
+== `Encoder`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-GelfLayout]
+== GelfLayout
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-GelfLayout-CompressionType]
+== `CompressionType`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-HtmlLayout]
+== HtmlLayout
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-HtmlLayout-FontSize]
+== `FontSize`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-JsonLayout]
+== JsonLayout
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-LevelPatternSelector]
+== LevelPatternSelector
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-LoggerFields]
+== LoggerFields
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-MarkerPatternSelector]
+== MarkerPatternSelector
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-MessageLayout]
+== MessageLayout
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-PatternLayout]
+== PatternLayout
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-PatternMatch]
+== PatternMatch
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-PatternSelector]
+== `PatternSelector`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-Rfc5424Layout]
+== Rfc5424Layout
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-ScriptPatternSelector]
+== ScriptPatternSelector
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-SerializedLayout]
+== SerializedLayout
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-SyslogLayout]
+== SyslogLayout
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-XmlLayout]
+== XmlLayout
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-layout-YamlLayout]
+== YamlLayout
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-LifeCycle2]
+== `LifeCycle2`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-LifeCycle]
+== `LifeCycle`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-AbstractConfigurationAwareLookup]
+== `AbstractConfigurationAwareLookup`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-AbstractLookup]
+== `AbstractLookup`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-ContextMapLookup]
+== ctx
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-DateLookup]
+== date
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-EnvironmentLookup]
+== env
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-EventLookup]
+== event
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-JavaLookup]
+== java
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-JmxRuntimeInputArgumentsLookup]
+== jvmrunargs
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-JndiLookup]
+== jndi
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-Log4jLookup]
+== log4j
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-LowerLookup]
+== lower
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-MainMapLookup]
+== main
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-MapLookup]
+== `MapLookup`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-MarkerLookup]
+== marker
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-ResourceBundleLookup]
+== bundle
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-StrLookup]
+== `StrLookup`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-StructuredDataLookup]
+== sd
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-SystemPropertiesLookup]
+== sys
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-lookup-UpperLookup]
+== upper
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-Advertiser]
+== `Advertiser`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-Facility]
+== `Facility`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-MulticastDnsAdvertiser]
+== multicastdns
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-Protocol]
+== `Protocol`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-Rfc1349TrafficClass]
+== `Rfc1349TrafficClass`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-SocketAddress]
+== SocketAddress
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-SocketOptions]
+== SocketOptions
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-SocketPerformancePreferences]
+== SocketPerformancePreferences
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-ssl-AbstractKeyStoreConfiguration]
+== `AbstractKeyStoreConfiguration`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-ssl-KeyStoreConfiguration]
+== KeyStore
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-ssl-SslConfiguration]
+== Ssl
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-ssl-StoreConfiguration]
+== `StoreConfiguration`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-ssl-TrustStoreConfiguration]
+== TrustStore
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-AbstractPatternConverter]
+== `AbstractPatternConverter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-AbstractStyleNameConverter]
+== `AbstractStyleNameConverter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-AbstractStyleNameConverter-Black]
+== black
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-AbstractStyleNameConverter-Blue]
+== blue
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-AbstractStyleNameConverter-Cyan]
+== cyan
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-AbstractStyleNameConverter-Green]
+== green
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-AbstractStyleNameConverter-Magenta]
+== magenta
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-AbstractStyleNameConverter-Red]
+== red
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-AbstractStyleNameConverter-White]
+== white
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-AbstractStyleNameConverter-Yellow]
+== yellow
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-AnsiConverter]
+== `AnsiConverter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-ArrayPatternConverter]
+== `ArrayPatternConverter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-ClassNamePatternConverter]
+== ClassNamePatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-DatePatternConverter]
+== DatePatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-EncodingPatternConverter]
+== encode
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-EndOfBatchPatternConverter]
+== EndOfBatchPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-EqualsBaseReplacementConverter]
+== `EqualsBaseReplacementConverter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-EqualsIgnoreCaseReplacementConverter]
+== equalsIgnoreCase
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-EqualsReplacementConverter]
+== equals
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-ExtendedThrowablePatternConverter]
+== ExtendedThrowablePatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-FileDatePatternConverter]
+== FileDatePatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-FileLocationPatternConverter]
+== FileLocationPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-FullLocationPatternConverter]
+== FullLocationPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-HighlightConverter]
+== highlight
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-IntegerPatternConverter]
+== IntegerPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-LevelPatternConverter]
+== LevelPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-LineLocationPatternConverter]
+== LineLocationPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-LineSeparatorPatternConverter]
+== LineSeparatorPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-LogEventPatternConverter]
+== `LogEventPatternConverter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-LoggerFqcnPatternConverter]
+== LoggerFqcnPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-LoggerPatternConverter]
+== LoggerPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-MapPatternConverter]
+== MapPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-MarkerPatternConverter]
+== MarkerPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-MarkerSimpleNamePatternConverter]
+== MarkerNamePatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-MaxLengthConverter]
+== maxLength
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-MdcPatternConverter]
+== MdcPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-MessagePatternConverter]
+== MessagePatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-MethodLocationPatternConverter]
+== MethodLocationPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-NamePatternConverter]
+== `NamePatternConverter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-NanoTimePatternConverter]
+== NanoTimePatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-NdcPatternConverter]
+== NdcPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-PatternConverter]
+== `PatternConverter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-ProcessIdPatternConverter]
+== ProcessIdPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-RegexReplacement]
+== replace
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-RegexReplacementConverter]
+== replace
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-RelativeTimePatternConverter]
+== RelativeTimePatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-RepeatPatternConverter]
+== repeat
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-RootThrowablePatternConverter]
+== RootThrowablePatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-SequenceNumberPatternConverter]
+== SequenceNumberPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-StyleConverter]
+== style
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-ThreadIdPatternConverter]
+== ThreadIdPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-ThreadNamePatternConverter]
+== ThreadPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-ThreadPriorityPatternConverter]
+== ThreadPriorityPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-ThrowablePatternConverter]
+== `ThrowablePatternConverter`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-UuidPatternConverter]
+== UuidPatternConverter
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-pattern-VariablesNotEmptyReplacementConverter]
+== notEmpty
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-AbstractScript]
+== `AbstractScript`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-Script]
+== Script
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-ScriptFile]
+== ScriptFile
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-script-ScriptRef]
+== ScriptRef
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-StringLayout]
+== `StringLayout`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-util-AbstractWatcher]
+== `AbstractWatcher`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-util-Builder]
+== `Builder`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-util-KeyValuePair]
+== KeyValuePair
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-util-Watcher]
+== `Watcher`
+[#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-Level]
+== `Level`
+[#org-apache-logging-log4j_log4j-core-test_org-apache-logging-log4j-core-test-appender-AlwaysFailAppender]
+== AlwaysFail
+[#org-apache-logging-log4j_log4j-core-test_org-apache-logging-log4j-core-test-appender-BlockingAppender]
+== Block
+[#org-apache-logging-log4j_log4j-core-test_org-apache-logging-log4j-core-test-appender-FailOnceAppender]
+== FailOnce
+[#org-apache-logging-log4j_log4j-core-test_org-apache-logging-log4j-core-test-appender-ListAppender]
+== List
+[#org-apache-logging-log4j_log4j-core-test_org-apache-logging-log4j-core-test-ExtendedLevels]
+== ExtendedLevel
+[#org-apache-logging-log4j_log4j-core-test_org-apache-logging-log4j-core-test-junit-TestPropertyLookup]
+== test
+[#org-apache-logging-log4j_log4j-couchdb_org-apache-logging-log4j-core-appender-nosql-NoSqlProvider]
+== `NoSqlProvider`
+[#org-apache-logging-log4j_log4j-couchdb_org-apache-logging-log4j-couchdb-CouchDbProvider]
+== CouchDB
+[#org-apache-logging-log4j_log4j-docker_org-apache-logging-log4j-docker-DockerLookup]
+== docker
+[#org-apache-logging-log4j_log4j-flume-ng_org-apache-logging-log4j-flume-appender-Agent]
+== Agent
+[#org-apache-logging-log4j_log4j-flume-ng_org-apache-logging-log4j-flume-appender-FlumeAppender]
+== Flume
+[#org-apache-logging-log4j_log4j-flume-ng_org-apache-logging-log4j-flume-appender-FlumeEventFactory]
+== `FlumeEventFactory`
+[#org-apache-logging-log4j_log4j-jakarta-web_org-apache-logging-log4j-web-appender-ServletAppender]
+== Servlet
+[#org-apache-logging-log4j_log4j-jakarta-web_org-apache-logging-log4j-web-WebLookup]
+== web
+[#org-apache-logging-log4j_log4j-jdbc-dbcp2_org-apache-logging-log4j-core-appender-db-jdbc-PoolableConnectionFactoryConfig]
+== PoolableConnectionFactory
+[#org-apache-logging-log4j_log4j-jdbc-dbcp2_org-apache-logging-log4j-core-appender-db-jdbc-PoolingDriverConnectionSource]
+== PoolingDriver
+[#org-apache-logging-log4j_log4j-jpa_org-apache-logging-log4j-core-appender-db-jpa-JpaAppender]
+== JPA
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-JsonTemplateLayout]
+== JsonTemplateLayout
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-JsonTemplateLayout-EventTemplateAdditionalField]
+== EventTemplateAdditionalField
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-JsonTemplateLayout-EventTemplateAdditionalField-Format]
+== `Format`
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-CaseConverterResolverFactory]
+== CaseConverterResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-CounterResolverFactory]
+== CounterResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-EndOfBatchResolverFactory]
+== EndOfBatchResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-EventAdditionalFieldInterceptor]
+== EventAdditionalFieldInterceptor
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-EventResolverFactory]
+== `EventResolverFactory`
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-EventResolverInterceptor]
+== `EventResolverInterceptor`
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-EventRootObjectKeyInterceptor]
+== EventRootObjectKeyInterceptor
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-ExceptionResolverFactory]
+== ExceptionResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-ExceptionRootCauseResolverFactory]
+== ExceptionRootCauseResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-LevelResolverFactory]
+== LevelResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-LoggerResolverFactory]
+== LoggerResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-MainMapResolverFactory]
+== MainMapResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-MapResolverFactory]
+== MapResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-MarkerResolverFactory]
+== MarkerResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-MessageParameterResolverFactory]
+== MessageParameterResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-MessageResolverFactory]
+== MessageResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-PatternResolverFactory]
+== PatternResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-SourceResolverFactory]
+== SourceResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-TemplateResolverFactory]
+== `TemplateResolverFactory`
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-TemplateResolverInterceptor]
+== `TemplateResolverInterceptor`
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-ThreadContextDataResolverFactory]
+== ThreadContextDataResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-ThreadContextStackResolverFactory]
+== ThreadContextStackResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-ThreadResolverFactory]
+== ThreadResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-resolver-TimestampResolverFactory]
+== TimestampResolverFactory
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-util-RecyclerFactory]
+== `RecyclerFactory`
+[#org-apache-logging-log4j_log4j-layout-template-json_org-apache-logging-log4j-layout-template-json-util-RecyclerFactoryConverter]
+== RecyclerFactoryConverter
+[#org-apache-logging-log4j_log4j-mongodb4_org-apache-logging-log4j-mongodb4-MongoDb4Provider]
+== MongoDb4
+[#org-apache-logging-log4j_log4j-mongodb_org-apache-logging-log4j-mongodb-MongoDbProvider]
+== MongoDb
+[#org-apache-logging-log4j_log4j-spring-boot_org-apache-logging-log4j-core-config-LoggerContextAware]
+== `LoggerContextAware`
+[#org-apache-logging-log4j_log4j-spring-boot_org-apache-logging-log4j-spring-boot-SpringLookup]
+== spring
+[#org-apache-logging-log4j_log4j-spring-boot_org-apache-logging-log4j-spring-boot-SpringProfileArbiter]
+== SpringProfile
diff --git a/src/site/antora/modules/ROOT/partials/configuration-file-format-deps.adoc b/src/site/antora/modules/ROOT/partials/configuration-file-format-deps.adoc
index 9b5e4c2ad5..58c281fb68 100644
--- a/src/site/antora/modules/ROOT/partials/configuration-file-format-deps.adoc
+++ b/src/site/antora/modules/ROOT/partials/configuration-file-format-deps.adoc
@@ -25,35 +25,40 @@ Maven::
log4j2.xml::
+
-No dependency required.
-
-log4j2.json::
+JPMS users need to add:
+
-[source,xml,subs="+attributes"]
+[source,java]
----
-<dependency>
- <groupId>com.fasterxml.jackson.core</groupId>
- <artifactId>jackson-databind</artifactId>
- <version>{jackson-version}</version>
- <scope>runtime</scope>
-</dependency>
+module foo.bar {
+ requires java.xml;
+}
----
++
+to their `module-info.java` descriptor.
+
+log4j2.json::
++
+No dependency required.
log4j2.yaml::
+
-[source,xml,subs="+attributes"]
+[source,xml]
----
<dependency>
- <groupId>com.fasterxml.jackson.dataformat</groupId>
- <artifactId>jackson-dataformat-yaml</artifactId>
- <version>{jackson-version}</version>
- <scope>runtime</scope>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-config-yaml</artifactId>
</dependency>
----
log4j2.properties::
+
-No dependency required.
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-config-properties</artifactId>
+</dependency>
+----
=====
@@ -64,25 +69,34 @@ Gradle::
log4j2.xml::
+
-No dependency required.
-
-log4j2.json::
+JPMS users need to add:
+
-[source,groovy,subs="+attributes"]
+[source,java]
----
-runtimeOnly 'com.fasterxml.jackson.core:jackson-databind:{jackson-version}'
+module foo.bar {
+ requires java.xml;
+}
----
++
+to their `module-info.java` descriptor.
+
+log4j2.json::
++
+No dependency required.
log4j2.yaml::
+
-[source,groovy,subs="+attributes"]
+[source,groovy]
----
-runtimeOnly 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:{jackson-version}'
+runtimeOnly 'org.apache.logging.log4j:log4j-config-yaml'
----
log4j2.properties::
+
-No dependency required.
+[source,groovy]
+----
+runtimeOnly 'org.apache.logging.log4j:log4j-config-properties'
+----
=====
-====
\ No newline at end of file
+====