You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by gi...@apache.org on 2024/07/03 08:14:42 UTC
(logging-log4j2) branch 2.x-site-stg-out updated: Add website content generated from `466ac597590278a087e70d176679a68c4f096a2e`
This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch 2.x-site-stg-out
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/2.x-site-stg-out by this push:
new 39df95a00b Add website content generated from `466ac597590278a087e70d176679a68c4f096a2e`
39df95a00b is described below
commit 39df95a00be3ebbfc1a518a9b7b53280c975aea7
Author: ASF Logging Services RM <pr...@logging.apache.org>
AuthorDate: Wed Jul 3 08:14:36 2024 +0000
Add website content generated from `466ac597590278a087e70d176679a68c4f096a2e`
---
.htaccess | 41 -
_images/Log4jClasses.jpg | Bin 31443 -> 0 bytes
...ag-01168003b98f120d2f0736e5172de8e1218f189e.svg | 1 +
...ag-1a68f90761e6350de59d964e3f2cfeb22b591a02.svg | 1 +
...ag-232cdf1d44336897239fa03f6521cc730f38f32d.svg | 1 +
...ag-2dc8fe44284ab476198b745bd5308956e31b6352.svg | 1 +
...ag-3179a6738d88762b267e7c0bf55d9407cd45c450.svg | 1 +
...ag-58c484caf8cd616db4f1c7ed31b51c123b5859d4.svg | 1 +
...ag-77a13b00749af95e3ed0eefd605a73f25d70973c.svg | 1 +
...ag-7a08e5a79432e9299cc0d9671bd39677be5618e8.svg | 1 +
...ag-892fd9dbd9ea6bece55c1d4078ae1de2edd5c689.svg | 1 +
...ag-96b353807a86d1e31f8907713d4f2b7fe5a59ce6.svg | 1 +
...ag-ce9936638b62ac5c763a2a3b54dbda70bb0144ff.svg | 1 +
...ag-d0e5615e7f18a6e132c1d6809c9813be92de6923.svg | 1 +
development.html | 2 +-
download.html | 2 +-
faq.html | 2 +-
hibernate.html | 2 +-
index.html | 2 +-
javadoc.html | 2 +-
log4j-appserver.html | 2 +-
log4j-cassandra.html | 2 +-
log4j-couchdb.html | 2 +-
log4j-docker.html | 2 +-
log4j-flume-ng.html | 2 +-
log4j-iostreams.html | 2 +-
log4j-jakarta-web.html | 2 +-
log4j-jul.html | 2 +-
log4j-spring-boot.html | 2 +-
log4j-spring-cloud-config-client.html | 2 +-
log4j-spring-cloud-config.html | 2 +-
log4j-taglib.html | 2 +-
log4j-to-jul.html | 2 +-
log4j-web.html | 2 +-
manual/api.html | 16 +-
manual/appenders.html | 387 ++++----
manual/architecture.html | 1015 ++++++++------------
manual/async.html | 2 +-
manual/cloud.html | 2 +-
manual/compatibility.html | 2 +-
manual/config-intro.html | 27 +-
manual/configuration.html | 487 ++++++----
manual/customconfig.html | 758 ++++++++-------
manual/customloglevels.html | 4 +-
manual/eventlogging.html | 2 +-
manual/extending.html | 661 ++++---------
manual/filters.html | 152 ++-
manual/flowtracing.html | 2 +-
manual/garbagefree.html | 4 +-
manual/getting-started.html | 2 +-
manual/index.html | 2 +-
manual/installation.html | 50 +-
manual/jmx.html | 2 +-
manual/json-template-layout.html | 4 +-
manual/layouts.html | 19 +-
manual/logbuilder.html | 2 +-
manual/logsep.html | 2 +-
manual/lookups.html | 193 ++--
manual/markers.html | 6 +-
manual/messages.html | 2 +-
manual/migration.html | 4 +-
manual/pattern-layout.html | 8 +-
manual/performance.html | 2 +-
manual/plugins.html | 407 ++++++--
manual/resource-logger.html | 2 +-
manual/scoped-context.html | 2 +-
manual/scripts.html | 2 +-
manual/simple-logger.html | 2 +-
manual/status-logger.html | 2 +-
manual/systemproperties.html | 2 +-
manual/thread-context.html | 2 +-
manual/webapp.html | 2 +-
migrate-from-logback.html | 2 +-
migrate-from-slf4j.html | 2 +-
plugin-reference.html | 14 +-
release-notes.html | 2 +-
sitemap.xml | 124 +--
77 files changed, 2259 insertions(+), 2220 deletions(-)
diff --git a/.htaccess b/.htaccess
index 308ff31b1c..ad47945d85 100644
--- a/.htaccess
+++ b/.htaccess
@@ -44,47 +44,6 @@ RewriteRule "^log4j-mongodb3(/index)?\.html$" "manual/appenders.html#NoSQLAppend
RewriteRule "^log4j-mongodb4(/index)?\.html$" "manual/appenders.html#log4j-mongodb4" [R=permanent,NE]
RewriteRule "^log4j-slf4j2?-impl(/index)?\.html$" "manual/installation.html#impl-core-bridge-slf4j" [R=permanent,NE]
RewriteRule "^manual/api-separation\.html$" "manual/api.html" [R=permanent]
-RewriteRule "^manual/extending\.html#Layouts$" "manual/layouts.html#extending" [R=permanent]
-RewriteRule "^manual/extending\.html#PatternConverters$" "manual/pattern-layout.html#extending-converters" [R=permanent]
-RewriteRule "^manual/layouts\.html#enable-jansi$" "manual/pattern-layout.html#jansi" [R=permanent]
-RewriteRule "^manual/layouts\.html#EndOfBatch$" "manual/pattern-layout.html#converter-end-of-batch" [R=permanent]
-RewriteRule "^manual/layouts\.html#LevelPatternSelector$" "manual/pattern-layout.html#plugin-element-LevelPatternSelector" [R=permanent]
-RewriteRule "^manual/layouts\.html#MarkerPatternSelector$" "manual/pattern-layout.html#plugin-element-MarkerPatternSelector" [R=permanent]
-RewriteRule "^manual/layouts\.html#(PatternLayout|pattern-layout)$" "manual/pattern-layout.html" [R=permanent]
-RewriteRule "^manual/layouts\.html#Patterns$" "manual/pattern-layout.html#converters" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternClass$" "manual/pattern-layout.html#converter-class" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternDate$" "manual/pattern-layout.html#converter-date" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternException$" "manual/pattern-layout.html#converter-exception" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternExtendedException$" "manual/pattern-layout.html#converter-exception-extended" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternFile$" "manual/pattern-layout.html#converter-file" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternLevel$" "manual/pattern-layout.html#converter-level" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternLine$" "manual/pattern-layout.html#converter-line" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternLocation$" "manual/pattern-layout.html#converter-location" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternLoggerFqcn$" "manual/pattern-layout.html#converter-fqcn" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternMap$" "manual/pattern-layout.html#converter-map" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternMarker(SimpleName)?$" "manual/pattern-layout.html#converter-marker" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternMaxLength$" "manual/pattern-layout.html#converter-max-len" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternMDC$" "manual/pattern-layout.html#converter-thread-context-map" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternMessage$" "manual/pattern-layout.html#converter-message" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternMethod$" "manual/pattern-layout.html#converter-method" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternNDC$" "manual/pattern-layout.html#converter-thread-context-stack" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternPercentLiteral$" "manual/pattern-layout.html#usage" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternRelative$" "manual/pattern-layout.html#converter-relative" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternRepeat$" "manual/pattern-layout.html#converter-repeat" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternReplace$" "manual/pattern-layout.html#converter-replace" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternSelectors$" "manual/pattern-layout.html#plugin-element-PatternSelector" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternSequenceNumber$" "manual/pattern-layout.html#converter-seq" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternStyle$" "manual/pattern-layout.html#converter-style" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternThreadId$" "manual/pattern-layout.html#converter-thread-id" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternThreadName$" "manual/pattern-layout.html#converter-thread-name" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternThreadPriority$" "manual/pattern-layout.html#converter-thread-priority" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternUUID$" "manual/pattern-layout.html#converter-uuid" [R=permanent]
-RewriteRule "^manual/layouts\.html#NanoTime$" "manual/pattern-layout.html#converter-nano" [R=permanent]
-RewriteRule "^manual/layouts\.html#PatternNewLine$" "manual/pattern-layout.html#usage" [R=permanent]
-RewriteRule "^manual/layouts\.html#Process_ID$" "manual/pattern-layout.html#converter-pid" [R=permanent]
-RewriteRule "^manual/layouts\.html#ScriptPatternSelector$" "manual/pattern-layout.html#plugin-element-ScriptPatternSelector" [R=permanent]
-RewriteRule "^manual/layouts\.html#VariablesNotEmpty$" "manual/pattern-layout.html#converter-not-empty" [R=permanent]
-RewriteRule "^manual/plugins\.html#converters$" "manual/pattern-layout.html#extending-converters" [R=permanent]
RewriteRule "^manual/scala-api\.html$" "/log4j/scala/latest/index.html" [R=permanent]
RewriteRule "^manual/usage\.html$" "manual/api.html" [R=permanent]
RewriteRule "^runtime-dependencies\.html$" "manual/installation.html" [R=permanent]
diff --git a/_images/Log4jClasses.jpg b/_images/Log4jClasses.jpg
deleted file mode 100755
index ea16084bd6..0000000000
Binary files a/_images/Log4jClasses.jpg and /dev/null differ
diff --git a/_images/diag-01168003b98f120d2f0736e5172de8e1218f189e.svg b/_images/diag-01168003b98f120d2f0736e5172de8e1218f189e.svg
new file mode 100644
index 0000000000..ee9dca5100
--- /dev/null
+++ b/_images/diag-01168003b98f120d2f0736e5172de8e1218f189e.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="278px" preserveAspectRatio="none" style="width:781px;height:278px;background:#FFFFFF;" version="1.1" viewBox="0 0 781 278" width="781px" zoomAndPan="magnify"><defs/><g><!--cluster LoggerContext--><g id="cluster_LoggerContext"><path d="M8.5,6 L127.5,6 A3.75,3.75 0 0 1 130,8.5 L137,28.2969 L621.5,28.2969 A2.5,2.5 0 0 [...]
\ No newline at end of file
diff --git a/_images/diag-1a68f90761e6350de59d964e3f2cfeb22b591a02.svg b/_images/diag-1a68f90761e6350de59d964e3f2cfeb22b591a02.svg
new file mode 100644
index 0000000000..36ab12457c
--- /dev/null
+++ b/_images/diag-1a68f90761e6350de59d964e3f2cfeb22b591a02.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="489px" preserveAspectRatio="none" style="width:917px;height:489px;background:#FFFFFF;" version="1.1" viewBox="0 0 917 489" width="917px" zoomAndPan="magnify"><defs/><g><!--class LoggerContext--><g id="elem_LoggerContext"><rect codeLine="1" fill="#F1F1F1" height="96.8906" id="LoggerContext" rx="2.5" ry="2.5" style=" [...]
\ No newline at end of file
diff --git a/_images/diag-232cdf1d44336897239fa03f6521cc730f38f32d.svg b/_images/diag-232cdf1d44336897239fa03f6521cc730f38f32d.svg
new file mode 100644
index 0000000000..253990d3c1
--- /dev/null
+++ b/_images/diag-232cdf1d44336897239fa03f6521cc730f38f32d.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="218px" preserveAspectRatio="none" style="width:197px;height:218px;background:#FFFFFF;" version="1.1" viewBox="0 0 197 218" width="197px" zoomAndPan="magnify"><defs/><g><!--class Appender--><g id="elem_Appender"><rect codeLine="1" fill="#F1F1F1" height="80.5938" id="Appender" rx="2.5" ry="2.5" style="stroke:#181818; [...]
\ No newline at end of file
diff --git a/_images/diag-2dc8fe44284ab476198b745bd5308956e31b6352.svg b/_images/diag-2dc8fe44284ab476198b745bd5308956e31b6352.svg
new file mode 100644
index 0000000000..fc48b384db
--- /dev/null
+++ b/_images/diag-2dc8fe44284ab476198b745bd5308956e31b6352.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="507px" preserveAspectRatio="none" style="width:649px;height:507px;background:#FFFFFF;" version="1.1" viewBox="0 0 649 507" width="649px" zoomAndPan="magnify"><defs/><g><!--class Configuration--><g id="elem_Configuration"><rect codeLine="1" fill="#F1F1F1" height="129.4844" id="Configuration" rx="2.5" ry="2.5" style= [...]
\ No newline at end of file
diff --git a/_images/diag-3179a6738d88762b267e7c0bf55d9407cd45c450.svg b/_images/diag-3179a6738d88762b267e7c0bf55d9407cd45c450.svg
new file mode 100644
index 0000000000..ff62a67ca8
--- /dev/null
+++ b/_images/diag-3179a6738d88762b267e7c0bf55d9407cd45c450.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="300px" preserveAspectRatio="none" style="width:649px;height:300px;background:#FFFFFF;" version="1.1" viewBox="0 0 649 300" width="649px" zoomAndPan="magnify"><defs/><g><!--class LoggerContext--><g id="elem_LoggerContext"><rect codeLine="1" fill="#F1F1F1" height="96.8906" id="LoggerContext" rx="2.5" ry="2.5" style=" [...]
\ No newline at end of file
diff --git a/_images/diag-58c484caf8cd616db4f1c7ed31b51c123b5859d4.svg b/_images/diag-58c484caf8cd616db4f1c7ed31b51c123b5859d4.svg
new file mode 100644
index 0000000000..cf669cbdd8
--- /dev/null
+++ b/_images/diag-58c484caf8cd616db4f1c7ed31b51c123b5859d4.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="134px" preserveAspectRatio="none" style="width:615px;height:134px;background:#FFFFFF;" version="1.1" viewBox="0 0 615 134" width="615px" zoomAndPan="magnify"><defs/><g><rect fill="#F1F1F1" height="36.2969" rx="12.5" ry="12.5" style="stroke:#181818;stroke-width:1.5;" width="48" x="10" y="48.1484"/><text fill="#00000 [...]
\ No newline at end of file
diff --git a/_images/diag-77a13b00749af95e3ed0eefd605a73f25d70973c.svg b/_images/diag-77a13b00749af95e3ed0eefd605a73f25d70973c.svg
new file mode 100644
index 0000000000..d9566cac31
--- /dev/null
+++ b/_images/diag-77a13b00749af95e3ed0eefd605a73f25d70973c.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="442px" preserveAspectRatio="none" style="width:298px;height:442px;background:#FFFFFF;" version="1.1" viewBox="0 0 298 442" width="298px" zoomAndPan="magnify"><defs/><g><!--class LoggerContext--><g id="elem_LoggerContext"><rect codeLine="1" fill="#F1F1F1" height="96.8906" id="LoggerContext" rx="2.5" ry="2.5" style=" [...]
\ No newline at end of file
diff --git a/_images/diag-7a08e5a79432e9299cc0d9671bd39677be5618e8.svg b/_images/diag-7a08e5a79432e9299cc0d9671bd39677be5618e8.svg
new file mode 100644
index 0000000000..d6568aec0a
--- /dev/null
+++ b/_images/diag-7a08e5a79432e9299cc0d9671bd39677be5618e8.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="548px" preserveAspectRatio="none" style="width:330px;height:548px;background:#FFFFFF;" version="1.1" viewBox="0 0 330 548" width="330px" zoomAndPan="magnify"><defs/><g><!--class Configuration--><g id="elem_Configuration"><rect codeLine="1" fill="#F1F1F1" height="129.4844" id="Configuration" rx="2.5" ry="2.5" style= [...]
\ No newline at end of file
diff --git a/_images/diag-892fd9dbd9ea6bece55c1d4078ae1de2edd5c689.svg b/_images/diag-892fd9dbd9ea6bece55c1d4078ae1de2edd5c689.svg
new file mode 100644
index 0000000000..cbe9bce8db
--- /dev/null
+++ b/_images/diag-892fd9dbd9ea6bece55c1d4078ae1de2edd5c689.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="134px" preserveAspectRatio="none" style="width:347px;height:134px;background:#FFFFFF;" version="1.1" viewBox="0 0 347 134" width="347px" zoomAndPan="magnify"><defs/><g><rect fill="#F1F1F1" height="36.2969" rx="12.5" ry="12.5" style="stroke:#181818;stroke-width:1.5;" width="48" x="10" y="48.1484"/><text fill="#00000 [...]
\ No newline at end of file
diff --git a/_images/diag-96b353807a86d1e31f8907713d4f2b7fe5a59ce6.svg b/_images/diag-96b353807a86d1e31f8907713d4f2b7fe5a59ce6.svg
new file mode 100644
index 0000000000..e9ea6a9273
--- /dev/null
+++ b/_images/diag-96b353807a86d1e31f8907713d4f2b7fe5a59ce6.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="614px" preserveAspectRatio="none" style="width:551px;height:614px;background:#FFFFFF;" version="1.1" viewBox="0 0 551 614" width="551px" zoomAndPan="magnify"><defs/><g><!--class Configuration--><g id="elem_Configuration"><rect codeLine="1" fill="#F1F1F1" height="129.4844" id="Configuration" rx="2.5" ry="2.5" style= [...]
\ No newline at end of file
diff --git a/_images/diag-ce9936638b62ac5c763a2a3b54dbda70bb0144ff.svg b/_images/diag-ce9936638b62ac5c763a2a3b54dbda70bb0144ff.svg
new file mode 100644
index 0000000000..63ee54500f
--- /dev/null
+++ b/_images/diag-ce9936638b62ac5c763a2a3b54dbda70bb0144ff.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="1022px" preserveAspectRatio="none" style="width:1327px;height:1022px;background:#FFFFFF;" version="1.1" viewBox="0 0 1327 1022" width="1327px" zoomAndPan="magnify"><defs/><g><!--cluster c--><g id="cluster_c"><path d="M8.5,150.89 L116.5,150.89 A3.75,3.75 0 0 1 119,153.39 L126,173.1869 L806.5,173.1869 A2.5,2.5 0 0 1 [...]
\ No newline at end of file
diff --git a/_images/diag-d0e5615e7f18a6e132c1d6809c9813be92de6923.svg b/_images/diag-d0e5615e7f18a6e132c1d6809c9813be92de6923.svg
new file mode 100644
index 0000000000..9097a26767
--- /dev/null
+++ b/_images/diag-d0e5615e7f18a6e132c1d6809c9813be92de6923.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="754px" preserveAspectRatio="none" style="width:549px;height:754px;background:#FFFFFF;" version="1.1" viewBox="0 0 549 754" width="549px" zoomAndPan="magnify"><defs/><g><!--class Configuration--><g id="elem_Configuration"><rect codeLine="1" fill="#F1F1F1" height="129.4844" id="Configuration" rx="2.5" ry="2.5" style= [...]
\ No newline at end of file
diff --git a/development.html b/development.html
index 719659b65c..0ab6c0dfa8 100644
--- a/development.html
+++ b/development.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/download.html b/download.html
index e9a54f844d..2b5bcd0783 100644
--- a/download.html
+++ b/download.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/faq.html b/faq.html
index faeadacee8..3c8b239123 100644
--- a/faq.html
+++ b/faq.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/hibernate.html b/hibernate.html
index 5e32cd4422..eddc103666 100644
--- a/hibernate.html
+++ b/hibernate.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/index.html b/index.html
index 7c685cd996..7a4effc80a 100644
--- a/index.html
+++ b/index.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/javadoc.html b/javadoc.html
index c3750701a3..4ec4e29b79 100644
--- a/javadoc.html
+++ b/javadoc.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-appserver.html b/log4j-appserver.html
index 6e90db9a63..82a7f44bed 100644
--- a/log4j-appserver.html
+++ b/log4j-appserver.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-cassandra.html b/log4j-cassandra.html
index e1e0c634d6..2d23db8eb8 100644
--- a/log4j-cassandra.html
+++ b/log4j-cassandra.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-couchdb.html b/log4j-couchdb.html
index 5db76a2650..e0f1076d4f 100644
--- a/log4j-couchdb.html
+++ b/log4j-couchdb.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-docker.html b/log4j-docker.html
index aa45e7188e..6867516a77 100644
--- a/log4j-docker.html
+++ b/log4j-docker.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-flume-ng.html b/log4j-flume-ng.html
index 680d200f37..e11e450ea6 100644
--- a/log4j-flume-ng.html
+++ b/log4j-flume-ng.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-iostreams.html b/log4j-iostreams.html
index 85d24c84b3..e844b07881 100644
--- a/log4j-iostreams.html
+++ b/log4j-iostreams.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-jakarta-web.html b/log4j-jakarta-web.html
index 2da722baeb..fb72381b76 100644
--- a/log4j-jakarta-web.html
+++ b/log4j-jakarta-web.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-jul.html b/log4j-jul.html
index e7bf7ce9fc..7bec6e0ea0 100644
--- a/log4j-jul.html
+++ b/log4j-jul.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-spring-boot.html b/log4j-spring-boot.html
index e5cc7e9e41..344272dbc8 100644
--- a/log4j-spring-boot.html
+++ b/log4j-spring-boot.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-spring-cloud-config-client.html b/log4j-spring-cloud-config-client.html
index 854917b8ea..b6b1586893 100644
--- a/log4j-spring-cloud-config-client.html
+++ b/log4j-spring-cloud-config-client.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-spring-cloud-config.html b/log4j-spring-cloud-config.html
index 34f85ef93a..ca27cf1941 100644
--- a/log4j-spring-cloud-config.html
+++ b/log4j-spring-cloud-config.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-taglib.html b/log4j-taglib.html
index 9771d01b90..78e9f98e98 100644
--- a/log4j-taglib.html
+++ b/log4j-taglib.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-to-jul.html b/log4j-to-jul.html
index 14287ee31d..e55e3ec478 100644
--- a/log4j-to-jul.html
+++ b/log4j-to-jul.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/log4j-web.html b/log4j-web.html
index a5cb170003..172bd2f40b 100644
--- a/log4j-web.html
+++ b/log4j-web.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/manual/api.html b/manual/api.html
index ce0b35cf24..00d3472eca 100644
--- a/manual/api.html
+++ b/manual/api.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -855,6 +855,20 @@ Consider the following example:</p>
<p><a href="../javadoc/log4j-api/org/apache/logging/log4j/Logger.html"><code>Logger</code></a>s are the primary entry point for logging.
In this section we will introduce you to further details about <code>Logger</code>s.</p>
</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Refer to <a href="architecture.html" class="xref page">Architecture</a> to see where <code>Logger</code>s stand in the big picture.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
<div class="sect2">
<h3 id="logger-names"><a class="anchor" href="#logger-names"></a>Logger names</h3>
<div class="paragraph">
diff --git a/manual/appenders.html b/manual/appenders.html
index f01e87ba7e..683415c64c 100644
--- a/manual/appenders.html
+++ b/manual/appenders.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item is-current-page" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -419,9 +419,15 @@ It does not ensure that the operating system writes the event to the underlying
</div>
</div>
<div class="sect1">
-<h2 id="AsyncAppender"><a class="anchor" href="#AsyncAppender"></a><a id="asyncappender"></a> AsyncAppender</h2>
+<h2 id="collection"><a class="anchor" href="#collection"></a>Collection</h2>
<div class="sectionbody">
<div class="paragraph">
+<p>Log4j bundles several predefined appenders to assist in several common deployment use cases.
+Following sections explain all these in detail.</p>
+</div>
+<div class="sect2">
+<h3 id="AsyncAppender"><a class="anchor" href="#AsyncAppender"></a><a id="asyncappender"></a> AsyncAppender</h3>
+<div class="paragraph">
<p>The AsyncAppender accepts references to other Appenders and causes LogEvents to be written to them on a separate Thread.
Note that exceptions while writing to those Appenders will be hidden from the application.
The AsyncAppender should be configured after the appenders it references to allow it to shut down properly.</p>
@@ -671,10 +677,8 @@ maximum capacity.</p></td>
</tbody>
</table>
</div>
-</div>
-<div class="sect1">
-<h2 id="CassandraAppender"><a class="anchor" href="#CassandraAppender"></a>CassandraAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="CassandraAppender"><a class="anchor" href="#CassandraAppender"></a>CassandraAppender</h3>
<div class="paragraph">
<p>The CassandraAppender writes its output to an <a href="https://cassandra.apache.org/">Apache Cassandra</a>
database.
@@ -841,10 +845,8 @@ TimestampGenerator. By default, this is <code>false</code>.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="consoleappender"><a class="anchor" href="#consoleappender"></a><a id="ConsoleAppender"></a> ConsoleAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="consoleappender"><a class="anchor" href="#consoleappender"></a><a id="ConsoleAppender"></a> ConsoleAppender</h3>
<div class="paragraph">
<p>As one might expect, the ConsoleAppender writes its output to either
<code>System.out</code> or <code>System.err</code> with <code>System.out</code> being the default target.
@@ -941,10 +943,8 @@ Appender in a <a href="#FailoverAppender">FailoverAppender</a>.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="FailoverAppender"><a class="anchor" href="#FailoverAppender"></a>FailoverAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="FailoverAppender"><a class="anchor" href="#FailoverAppender"></a>FailoverAppender</h3>
<div class="paragraph">
<p>The FailoverAppender wraps a set of appenders.
If the primary Appender fails the secondary appenders will be tried in order until one succeeds or there are no more secondaries to try.</p>
@@ -1041,10 +1041,8 @@ caller, instead.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="fileappender"><a class="anchor" href="#fileappender"></a><a id="FileAppender"></a> FileAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="fileappender"><a class="anchor" href="#fileappender"></a><a id="FileAppender"></a> FileAppender</h3>
<div class="paragraph">
<p>The FileAppender is an OutputStreamAppender that writes to the File defined in the <code>fileName</code> parameter.
The FileAppender uses a FileManager (which extends OutputStreamManager) to perform the file I/O.
@@ -1237,10 +1235,8 @@ file attribute view.</p>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="FlumeAppender"><a class="anchor" href="#FlumeAppender"></a>FlumeAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="FlumeAppender"><a class="anchor" href="#FlumeAppender"></a>FlumeAppender</h3>
<div class="paragraph">
<p><em>This is an optional component supplied in a separate jar.</em></p>
</div>
@@ -1570,10 +1566,8 @@ indicate which variation of the Appender is desired.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="JDBCAppender"><a class="anchor" href="#JDBCAppender"></a>JDBCAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="JDBCAppender"><a class="anchor" href="#JDBCAppender"></a>JDBCAppender</h3>
<div class="paragraph">
<p>As of Log4j 2.11.0, JDBC support has moved from the existing module
<code>log4j-core</code> to the new module <code>log4j-jdbc</code>.</p>
@@ -2239,10 +2233,8 @@ table based on a Log4j `MapMessage</code> instead of values from <code>LogEvent<
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="jms-appender"><a class="anchor" href="#jms-appender"></a><a id="JMSAppender"></a>JMS Appender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="jms-appender"><a class="anchor" href="#jms-appender"></a><a id="JMSAppender"></a>JMS Appender</h3>
<div class="paragraph">
<p>The JMS Appender sends the formatted log event to a JMS Destination.</p>
</div>
@@ -2407,10 +2399,8 @@ However, configurations written for 2.0 that use the <code><JMSQueue/></co
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="JPAAppender"><a class="anchor" href="#JPAAppender"></a>JPAAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="JPAAppender"><a class="anchor" href="#JPAAppender"></a>JPAAppender</h3>
<div class="paragraph">
<p>As of Log4j 2.11.0, JPA support has moved from the existing module <code>log4j-core</code> to the new module <code>log4j-jpa</code>.</p>
</div>
@@ -2609,10 +2599,8 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="HttpAppender"><a class="anchor" href="#HttpAppender"></a>HttpAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="HttpAppender"><a class="anchor" href="#HttpAppender"></a>HttpAppender</h3>
<div class="paragraph">
<p>The HttpAppender sends log events over HTTP.
A Layout must be provided to format the LogEvent.</p>
@@ -2735,10 +2723,8 @@ Appender in a <a href="#FailoverAppender">FailoverAppender</a>.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="KafkaAppender"><a class="anchor" href="#KafkaAppender"></a>KafkaAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="KafkaAppender"><a class="anchor" href="#KafkaAppender"></a>KafkaAppender</h3>
<div class="paragraph">
<p>The KafkaAppender logs events to an <a href="https://kafka.apache.org/">Apache Kafka</a> topic.
Each log event is sent as a Kafka record.</p>
@@ -2846,10 +2832,8 @@ Note that you need to use a version of the Kafka client library matching the Kaf
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="MemoryMappedFileAppender"><a class="anchor" href="#MemoryMappedFileAppender"></a>MemoryMappedFileAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="MemoryMappedFileAppender"><a class="anchor" href="#MemoryMappedFileAppender"></a>MemoryMappedFileAppender</h3>
<div class="paragraph">
<p><em>New since 2.1. Be aware that this is a new addition, and although it has been tested on several platforms, it does not have as much track record as the other file appenders.</em></p>
</div>
@@ -2982,10 +2966,8 @@ Appender in a <a href="#FailoverAppender">FailoverAppender</a>.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="NoSQLAppender"><a class="anchor" href="#NoSQLAppender"></a>NoSQLAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="NoSQLAppender"><a class="anchor" href="#NoSQLAppender"></a>NoSQLAppender</h3>
<div class="paragraph">
<p>The NoSQLAppender writes log events to a NoSQL database using an internal lightweight provider interface.
Provider implementations currently exist for MongoDB, and writing a custom provider is quite simple.</p>
@@ -3104,10 +3086,10 @@ We recommend you review the source code for the MongoDB providers as a guide for
}</code></pre>
</div>
</div>
-<div class="sect2">
-<h3 id="NoSQLAppenderMongoDB"><a class="anchor" href="#NoSQLAppenderMongoDB"></a>NoSQL providers for MongoDB</h3>
<div class="sect3">
-<h4 id="mongo-installation"><a class="anchor" href="#mongo-installation"></a>Installation</h4>
+<h4 id="NoSQLAppenderMongoDB"><a class="anchor" href="#NoSQLAppenderMongoDB"></a>NoSQL providers for MongoDB</h4>
+<div class="sect4">
+<h5 id="mongo-installation"><a class="anchor" href="#mongo-installation"></a>Installation</h5>
<div class="paragraph">
<p>Starting with version 2.11.0, Log4j supplies providers for the
<a href="https://www.mongodb.com/">MongoDB</a>
@@ -3235,8 +3217,8 @@ for more information.</p>
</table>
</div>
</div>
-<div class="sect3">
-<h4 id="log4j-mongodb"><a class="anchor" href="#log4j-mongodb"></a>NoSQL provider for MongoDB (current)</h4>
+<div class="sect4">
+<h5 id="log4j-mongodb"><a class="anchor" href="#log4j-mongodb"></a>NoSQL provider for MongoDB (current)</h5>
<div class="paragraph">
<p>This section details specializations of the
<a href="#NoSQLAppender">NoSQLAppender</a> provider for MongoDB using the current MongoDB driver (version 5).
@@ -3349,8 +3331,8 @@ collection documentation linked above for more information.</p></td>
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="log4j-mongodb4"><a class="anchor" href="#log4j-mongodb4"></a><a id="NoSQLAppenderMongoDB4"></a> NoSQL provider for MongoDB 4 (deprecated)</h4>
+<div class="sect4">
+<h5 id="log4j-mongodb4"><a class="anchor" href="#log4j-mongodb4"></a><a id="NoSQLAppenderMongoDB4"></a> NoSQL provider for MongoDB 4 (deprecated)</h5>
<div class="paragraph">
<p>The <code>log4j-mongodb4</code> module is deprecated in favor of <a href="#log4j-mongodb">NoSQL provider for MongoDB</a>.</p>
</div>
@@ -3467,10 +3449,8 @@ collection documentation linked above for more information.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="NoSQLAppenderApacheCouchDB"><a class="anchor" href="#NoSQLAppenderApacheCouchDB"></a>NoSQLAppender for Apache CouchDB</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="NoSQLAppenderApacheCouchDB"><a class="anchor" href="#NoSQLAppenderApacheCouchDB"></a>NoSQLAppender for Apache CouchDB</h3>
<div class="paragraph">
<p>This section details specializations of the <a href="#NoSQLAppender">NoSQLAppender</a> provider for CouchDB.
The NoSQLAppender writes log events to a NoSQL database using an internal lightweight provider interface.</p>
@@ -3553,10 +3533,8 @@ The NoSQLAppender writes log events to a NoSQL database using an internal lightw
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="OutputStreamAppender"><a class="anchor" href="#OutputStreamAppender"></a>OutputStreamAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="OutputStreamAppender"><a class="anchor" href="#OutputStreamAppender"></a>OutputStreamAppender</h3>
<div class="paragraph">
<p>The OutputStreamAppender provides the base for many of the other Appenders such as the File and Socket appenders that write the event to an Output Stream.
It cannot be directly configured.
@@ -3564,10 +3542,8 @@ Support for immediateFlush and buffering is provided by the OutputStreamAppender
The OutputStreamAppender uses an OutputStreamManager to handle the actual I/O, allowing the stream to be shared by Appenders in multiple configurations.</p>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="RandomAccessFileAppender"><a class="anchor" href="#RandomAccessFileAppender"></a>RandomAccessFileAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="RandomAccessFileAppender"><a class="anchor" href="#RandomAccessFileAppender"></a>RandomAccessFileAppender</h3>
<div class="paragraph">
<p>The RandomAccessFileAppender is similar to the standard
<a href="#FileAppender">[FileAppender]</a> except it is always buffered (this cannot be switched off) and internally it uses a
@@ -3687,10 +3663,8 @@ Appender in a <a href="#FailoverAppender">FailoverAppender</a>.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="RewriteAppender"><a class="anchor" href="#RewriteAppender"></a>RewriteAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="RewriteAppender"><a class="anchor" href="#RewriteAppender"></a>RewriteAppender</h3>
<div class="paragraph">
<p>The RewriteAppender allows the LogEvent to be manipulated before it is processed by another Appender.
This can be used to mask sensitive information such as passwords or to inject information into each event.
@@ -3748,15 +3722,15 @@ Appender in a <a href="#FailoverAppender">FailoverAppender</a>.</p></td>
</tr>
</tbody>
</table>
-<div class="sect2">
-<h3 id="RewritePolicy"><a class="anchor" href="#RewritePolicy"></a>RewritePolicy</h3>
+<div class="sect3">
+<h4 id="RewritePolicy"><a class="anchor" href="#RewritePolicy"></a>RewritePolicy</h4>
<div class="paragraph">
<p>RewritePolicy is an interface that allows implementations to inspect and possibly modify LogEvents before they are passed to Appender.
RewritePolicy declares a single method named rewrite that must be implemented.
The method is passed the LogEvent and can return the same event or create a new one.</p>
</div>
-<div class="sect3">
-<h4 id="_maprewritepolicy"><a class="anchor" href="#_maprewritepolicy"></a>MapRewritePolicy</h4>
+<div class="sect4">
+<h5 id="_maprewritepolicy"><a class="anchor" href="#_maprewritepolicy"></a>MapRewritePolicy</h5>
<div class="paragraph">
<p>MapRewritePolicy will evaluate LogEvents that contain a MapMessage and will add or update elements of the Map.</p>
</div>
@@ -3813,8 +3787,8 @@ The method is passed the LogEvent and can return the same event or create a new
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_propertiesrewritepolicy"><a class="anchor" href="#_propertiesrewritepolicy"></a>PropertiesRewritePolicy</h4>
+<div class="sect4">
+<h5 id="_propertiesrewritepolicy"><a class="anchor" href="#_propertiesrewritepolicy"></a>PropertiesRewritePolicy</h5>
<div class="paragraph">
<p>PropertiesRewritePolicy will add properties configured on the policy to the ThreadContext Map being logged.
The properties will not be added to the actual ThreadContext Map.
@@ -3870,8 +3844,8 @@ keys and values to be added to the ThreadContext Map.</p></td>
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_loggernamelevelrewritepolicy"><a class="anchor" href="#_loggernamelevelrewritepolicy"></a>LoggerNameLevelRewritePolicy</h4>
+<div class="sect4">
+<h5 id="_loggernamelevelrewritepolicy"><a class="anchor" href="#_loggernamelevelrewritepolicy"></a>LoggerNameLevelRewritePolicy</h5>
<div class="paragraph">
<p>You can use this policy to make loggers in third-party code less chatty by changing event levels.
The LoggerNameLevelRewritePolicy will rewrite log event levels for a given logger name prefix.
@@ -3935,10 +3909,8 @@ is a source level, each value a target level.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="rollingfileappender"><a class="anchor" href="#rollingfileappender"></a><a id="RollingFileAppender"></a> RollingFileAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="rollingfileappender"><a class="anchor" href="#rollingfileappender"></a><a id="RollingFileAppender"></a> RollingFileAppender</h3>
<div class="paragraph">
<p>The RollingFileAppender is an OutputStreamAppender that writes to the file named in the fileName parameter and rolls the file over according to the <code>TriggeringPolicy</code> and the <code>RolloverPolicy</code>.
The <code>RollingFileAppender</code>
@@ -4143,12 +4115,10 @@ file attribute view.</p>
</tbody>
</table>
</div>
-</div>
-<div class="sect1">
-<h2 id="TriggeringPolicies"><a class="anchor" href="#TriggeringPolicies"></a>TriggeringPolicies</h2>
-<div class="sectionbody">
<div class="sect2">
-<h3 id="_composite_triggering_policy"><a class="anchor" href="#_composite_triggering_policy"></a>Composite Triggering Policy</h3>
+<h3 id="TriggeringPolicies"><a class="anchor" href="#TriggeringPolicies"></a>TriggeringPolicies</h3>
+<div class="sect3">
+<h4 id="_composite_triggering_policy"><a class="anchor" href="#_composite_triggering_policy"></a>Composite Triggering Policy</h4>
<div class="paragraph">
<p>The <code>CompositeTriggeringPolicy</code> combines multiple triggering policies and returns true if any of the configured policies return true.
The
@@ -4167,8 +4137,8 @@ The
</div>
</div>
</div>
-<div class="sect2">
-<h3 id="_cron_triggering_policy"><a class="anchor" href="#_cron_triggering_policy"></a>Cron Triggering Policy</h3>
+<div class="sect3">
+<h4 id="_cron_triggering_policy"><a class="anchor" href="#_cron_triggering_policy"></a>Cron Triggering Policy</h4>
<div class="paragraph">
<p>The <code>CronTriggeringPolicy</code> triggers rollover based on a cron expression.
This policy is controlled by a timer and is asynchronous in processing log events, so it is possible that log events from the previous or next period may appear at the beginning or end of the log file.
@@ -4208,8 +4178,8 @@ and the current time the file will be immediately rolled over.</p></td>
</tbody>
</table>
</div>
-<div class="sect2">
-<h3 id="_onstartup_triggering_policy"><a class="anchor" href="#_onstartup_triggering_policy"></a>OnStartup Triggering Policy</h3>
+<div class="sect3">
+<h4 id="_onstartup_triggering_policy"><a class="anchor" href="#_onstartup_triggering_policy"></a>OnStartup Triggering Policy</h4>
<div class="paragraph">
<p>The <code>OnStartupTriggeringPolicy</code> policy causes a rollover if the log file is older than the current JVM’s start time and the minimum file size is met or exceeded.</p>
</div>
@@ -4245,8 +4215,8 @@ When running in Google App Engine, the OnStartup policy causes a rollover if the
and falls back to Log4J initialization time instead.)</p>
</div>
</div>
-<div class="sect2">
-<h3 id="sizebased-triggering-policy"><a class="anchor" href="#sizebased-triggering-policy"></a>SizeBased Triggering Policy</h3>
+<div class="sect3">
+<h4 id="sizebased-triggering-policy"><a class="anchor" href="#sizebased-triggering-policy"></a>SizeBased Triggering Policy</h4>
<div class="paragraph">
<p>The <code>SizeBasedTriggeringPolicy</code> causes a rollover once the file has reached the specified size.
The size can be specified in bytes, with the suffix KB, MB, GB, or TB for example <code>20MB</code>.
@@ -4258,8 +4228,8 @@ Otherwise, the target file will be overwritten on every rollover as the SizeBase
When used without a time-based triggering policy the SizeBased Triggering Policy will cause the timestamp value to change.</p>
</div>
</div>
-<div class="sect2">
-<h3 id="timebased-triggering-policy"><a class="anchor" href="#timebased-triggering-policy"></a>TimeBased Triggering Policy</h3>
+<div class="sect3">
+<h4 id="timebased-triggering-policy"><a class="anchor" href="#timebased-triggering-policy"></a>TimeBased Triggering Policy</h4>
<div class="paragraph">
<p>The <code>TimeBasedTriggeringPolicy</code> causes a rollover once the date/time pattern no longer applies to the active file.
This policy accepts an
@@ -4310,12 +4280,10 @@ load of doing so across time.</p></td>
</table>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="RolloverStrategies"><a class="anchor" href="#RolloverStrategies"></a>RolloverStrategies</h2>
-<div class="sectionbody">
<div class="sect2">
-<h3 id="DefaultRolloverStrategy"><a class="anchor" href="#DefaultRolloverStrategy"></a>DefaultRolloverStrategy</h3>
+<h3 id="RolloverStrategies"><a class="anchor" href="#RolloverStrategies"></a>RolloverStrategies</h3>
+<div class="sect3">
+<h4 id="DefaultRolloverStrategy"><a class="anchor" href="#DefaultRolloverStrategy"></a>DefaultRolloverStrategy</h4>
<div class="paragraph">
<p>Default Rollover Strategy</p>
</div>
@@ -4506,8 +4474,8 @@ archived log file during compression.</p></td>
</tbody>
</table>
</div>
-<div class="sect2">
-<h3 id="DirectWriteRolloverStrategy"><a class="anchor" href="#DirectWriteRolloverStrategy"></a>DirectWriteRolloverStrategy</h3>
+<div class="sect3">
+<h4 id="DirectWriteRolloverStrategy"><a class="anchor" href="#DirectWriteRolloverStrategy"></a>DirectWriteRolloverStrategy</h4>
<div class="paragraph">
<p>DirectWrite Rollover Strategy</p>
</div>
@@ -4696,8 +4664,8 @@ The cron trigger causes a rollover every hour while the file size is limited to
</div>
</div>
</div>
-<div class="sect2">
-<h3 id="CustomDeleteOnRollover"><a class="anchor" href="#CustomDeleteOnRollover"></a>CustomDeleteOnRollover</h3>
+<div class="sect3">
+<h4 id="CustomDeleteOnRollover"><a class="anchor" href="#CustomDeleteOnRollover"></a>CustomDeleteOnRollover</h4>
<div class="paragraph">
<p>Log Archive Retention Policy: Delete on Rollover</p>
</div>
@@ -4842,10 +4810,8 @@ and must return a list with the paths to delete.</p>
</table>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="DeleteIfFileName"><a class="anchor" href="#DeleteIfFileName"></a>DeleteIfFileName</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="DeleteIfFileName"><a class="anchor" href="#DeleteIfFileName"></a>DeleteIfFileName</h3>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 32. IfFileName Condition Parameters</caption>
<colgroup>
@@ -4891,10 +4857,8 @@ the path name matches).</p></td>
</tbody>
</table>
</div>
-</div>
-<div class="sect1">
-<h2 id="DeleteIfLastModified"><a class="anchor" href="#DeleteIfLastModified"></a>DeleteIfLastModified</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="DeleteIfLastModified"><a class="anchor" href="#DeleteIfLastModified"></a>DeleteIfLastModified</h3>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 33. IfLastModified Condition Parameters</caption>
<colgroup>
@@ -4930,10 +4894,8 @@ the file is old enough).</p></td>
</tbody>
</table>
</div>
-</div>
-<div class="sect1">
-<h2 id="DeleteIfAccumulatedFileCount"><a class="anchor" href="#DeleteIfAccumulatedFileCount"></a>DeleteIfAccumulatedFileCount</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="DeleteIfAccumulatedFileCount"><a class="anchor" href="#DeleteIfAccumulatedFileCount"></a>DeleteIfAccumulatedFileCount</h3>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 34. IfAccumulatedFileCount Condition Parameters</caption>
<colgroup>
@@ -4967,10 +4929,8 @@ the threshold count has been exceeded).</p></td>
</tbody>
</table>
</div>
-</div>
-<div class="sect1">
-<h2 id="DeleteIfAccumulatedFileSize"><a class="anchor" href="#DeleteIfAccumulatedFileSize"></a>DeleteIfAccumulatedFileSize</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="DeleteIfAccumulatedFileSize"><a class="anchor" href="#DeleteIfAccumulatedFileSize"></a>DeleteIfAccumulatedFileSize</h3>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 35. IfAccumulatedFileSize Condition Parameters</caption>
<colgroup>
@@ -5083,10 +5043,8 @@ During every rollover, this configuration will delete files that match "<strong>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="ScriptCondition"><a class="anchor" href="#ScriptCondition"></a>ScriptCondition</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="ScriptCondition"><a class="anchor" href="#ScriptCondition"></a>ScriptCondition</h3>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 36. ScriptCondition Parameters</caption>
<colgroup>
@@ -5115,10 +5073,8 @@ how ScriptFiles and ScriptRefs can be configured.</p></td>
</tbody>
</table>
</div>
-</div>
-<div class="sect1">
-<h2 id="ScriptParameters"><a class="anchor" href="#ScriptParameters"></a>ScriptParameters</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="ScriptParameters"><a class="anchor" href="#ScriptParameters"></a>ScriptParameters</h3>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 37. Script Parameters</caption>
<colgroup>
@@ -5238,10 +5194,8 @@ The Delete action will delete all files returned by the script.</p>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="CustomPosixViewAttributeOnRollover"><a class="anchor" href="#CustomPosixViewAttributeOnRollover"></a>CustomPosixViewAttributeOnRollover</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="CustomPosixViewAttributeOnRollover"><a class="anchor" href="#CustomPosixViewAttributeOnRollover"></a>CustomPosixViewAttributeOnRollover</h3>
<div class="paragraph">
<p>Log Archive File Attribute View Policy: Custom file attribute on Rollover</p>
</div>
@@ -5374,10 +5328,8 @@ file attribute view.</p>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="RollingRandomAccessFileAppender"><a class="anchor" href="#RollingRandomAccessFileAppender"></a>RollingRandomAccessFileAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="RollingRandomAccessFileAppender"><a class="anchor" href="#RollingRandomAccessFileAppender"></a>RollingRandomAccessFileAppender</h3>
<div class="paragraph">
<p>The RollingRandomAccessFileAppender is similar to the standard
<a href="#RollingFileAppender">[RollingFileAppender]</a> except it is always buffered (this cannot be switched off) and internally it uses a
@@ -5554,14 +5506,14 @@ file attribute view.</p>
</tr>
</tbody>
</table>
-<div class="sect2">
-<h3 id="_triggering_policies"><a class="anchor" href="#_triggering_policies"></a>Triggering Policies</h3>
+<div class="sect3">
+<h4 id="_triggering_policies"><a class="anchor" href="#_triggering_policies"></a>Triggering Policies</h4>
<div class="paragraph">
<p>See <a href="#TriggeringPolicies">RollingFileAppender Triggering Policies</a>.</p>
</div>
</div>
-<div class="sect2">
-<h3 id="_rollover_strategies"><a class="anchor" href="#_rollover_strategies"></a>Rollover Strategies</h3>
+<div class="sect3">
+<h4 id="_rollover_strategies"><a class="anchor" href="#_rollover_strategies"></a>Rollover Strategies</h4>
<div class="paragraph">
<p>See <a href="#RolloverStrategies"><code>RollingFileAppender</code> rollover strategies</a>.</p>
</div>
@@ -5649,10 +5601,8 @@ file attribute view.</p>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="RoutingAppender"><a class="anchor" href="#RoutingAppender"></a>RoutingAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="RoutingAppender"><a class="anchor" href="#RoutingAppender"></a>RoutingAppender</h3>
<div class="paragraph">
<p>The <code>RoutingAppender</code> evaluates LogEvents and then routes them to a subordinate Appender.
The target Appender may be an appender previously configured and may be referenced by its name or the Appender can be dynamically created as needed.
@@ -5769,8 +5719,8 @@ Note that the List Appender is one of our test appenders, any appender can be us
</Configuration></code></pre>
</div>
</div>
-<div class="sect2">
-<h3 id="Routes"><a class="anchor" href="#Routes"></a>Routes</h3>
+<div class="sect3">
+<h4 id="Routes"><a class="anchor" href="#Routes"></a>Routes</h4>
<div class="paragraph">
<p>The <code>Routes</code> element accepts a single attribute named "pattern".
The pattern is evaluated against all the registered Lookups and the result is used to select a <code>Route</code>.
@@ -5881,8 +5831,8 @@ Script.</p></td>
</div>
</div>
</div>
-<div class="sect2">
-<h3 id="Purge"><a class="anchor" href="#Purge"></a>Purge Policy</h3>
+<div class="sect3">
+<h4 id="Purge"><a class="anchor" href="#Purge"></a>Purge Policy</h4>
<div class="paragraph">
<p>The RoutingAppender can be configured with a PurgePolicy whose purpose is to stop and remove dormant Appenders that have been dynamically created by the RoutingAppender.
Log4j currently provides the IdlePurgePolicy is the only PurgePolicy available for cleaning up the Appenders.
@@ -5928,10 +5878,8 @@ Note that the AuditAppender was predefined while the RollingFileAppenders are cr
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="SMTPAppender"><a class="anchor" href="#SMTPAppender"></a>SMTPAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="SMTPAppender"><a class="anchor" href="#SMTPAppender"></a>SMTPAppender</h3>
<div class="paragraph">
<p>Sends an e-mail when a specific logging event occurs, typically on errors or fatal errors.</p>
</div>
@@ -6071,10 +6019,8 @@ As with other Appenders, the formatting can be controlled by specifying a Layout
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="ScriptAppenderSelector"><a class="anchor" href="#ScriptAppenderSelector"></a>ScriptAppenderSelector</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="ScriptAppenderSelector"><a class="anchor" href="#ScriptAppenderSelector"></a>ScriptAppenderSelector</h3>
<div class="paragraph">
<p>When the configuration is built, the <code>ScriptAppenderSelector</code> appender calls a <code>ScriptPlugin</code> to compute an appender name.
Log4j then creates one of the appender named listed under <code>AppenderSet</code> using the name of the
@@ -6111,10 +6057,8 @@ The appender name is recorded under the name of the
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="SocketAppender"><a class="anchor" href="#SocketAppender"></a>SocketAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="SocketAppender"><a class="anchor" href="#SocketAppender"></a>SocketAppender</h3>
<div class="paragraph">
<p>The <code>SocketAppender</code> is an OutputStreamAppender that writes its output to a remote destination specified by a host and port.
The data can be sent over either TCP or UDP and can be sent in any format.
@@ -6280,10 +6224,8 @@ Appender in a <a href="#FailoverAppender">FailoverAppender</a>.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="SSL"><a class="anchor" href="#SSL"></a>SSL</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="SSL"><a class="anchor" href="#SSL"></a>SSL</h3>
<div class="paragraph">
<p>Several appenders can be configured to use either a plain network connection or a Secure Socket Layer (SSL) connection.
This section documents the parameters available for SSL configuration.</p>
@@ -6326,8 +6268,8 @@ counterparty. Determines whether the remote authentication credentials
</tr>
</tbody>
</table>
-<div class="sect2">
-<h3 id="KeyStore"><a class="anchor" href="#KeyStore"></a>KeyStore</h3>
+<div class="sect3">
+<h4 id="KeyStore"><a class="anchor" href="#KeyStore"></a>KeyStore</h4>
<div class="paragraph">
<p>The Keystore is meant to contain your private keys and certificates, and determines which authentication credentials to send to the remote host.</p>
</div>
@@ -6390,8 +6332,8 @@ algorithms</a>.</p></td>
</tbody>
</table>
</div>
-<div class="sect2">
-<h3 id="TrustStore"><a class="anchor" href="#TrustStore"></a>TrustStore</h3>
+<div class="sect3">
+<h4 id="TrustStore"><a class="anchor" href="#TrustStore"></a>TrustStore</h4>
<div class="paragraph">
<p>The trust store is meant to contain the CA certificates you are willing to trust when a remote party presents its certificate.
Determines whether the remote authentication credentials (and thus the connection) should be trusted.</p>
@@ -6458,8 +6400,8 @@ algorithms</a>.</p></td>
</tbody>
</table>
</div>
-<div class="sect2">
-<h3 id="Example"><a class="anchor" href="#Example"></a>Example</h3>
+<div class="sect3">
+<h4 id="Example"><a class="anchor" href="#Example"></a>Example</h4>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><SSL>
@@ -6470,10 +6412,8 @@ algorithms</a>.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="SyslogAppender"><a class="anchor" href="#SyslogAppender"></a>SyslogAppender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="SyslogAppender"><a class="anchor" href="#SyslogAppender"></a>SyslogAppender</h3>
<div class="paragraph">
<p>The <code>SyslogAppender</code> is a <code>SocketAppender</code> that writes its output to a remote destination specified by a host and port in a format that conforms with either the BSD Syslog format or the RFC 5424 format.
The data can be sent over either TCP or UDP.</p>
@@ -6734,10 +6674,8 @@ application if <code>ignoreExceptions</code> is set to <code>false</code>).</p><
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="JeroMQAppender"><a class="anchor" href="#JeroMQAppender"></a>ZeroMQ/JeroMQ Appender</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="JeroMQAppender"><a class="anchor" href="#JeroMQAppender"></a>ZeroMQ/JeroMQ Appender</h3>
<div class="paragraph">
<p>The ZeroMQ appender uses the <a href="https://github.com/zeromq/jeromq">JeroMQ</a> library to send log events to one or more ZeroMQ endpoints.</p>
</div>
@@ -6909,6 +6847,93 @@ Please consult the JeroMQ and ZeroMQ documentation for details.</p>
</table>
</div>
</div>
+</div>
+<div class="sect1">
+<h2 id="extending"><a class="anchor" href="#extending"></a>Extending</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Appenders are <a href="plugins.html" class="xref page">plugins</a> implementing <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/Appender.html">the <code>Appender</code> interface</a>.
+This section will guide you on how to create custom ones.</p>
+</div>
+<div class="admonitionblock warning">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-warning" title="Warning"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p><strong>Implementing a reliable and efficient appender is a difficult task!</strong>
+We strongly advise you to</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>Use existing appenders and/or managers whenever appropriate</p>
+</li>
+<li>
+<p>Share your use case and ask for feedback in a <a href="https://logging.apache.org/support.html">user support channel</a></p>
+</li>
+</ol>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="sect2">
+<h3 id="extending-plugins"><a class="anchor" href="#extending-plugins"></a>Plugin preliminaries</h3>
+<div class="paragraph">
+<p>Log4j plugin system is the de facto extension mechanism embraced by various Log4j components.
+Plugins provide extension points to components, that can be used to implement new features, without modifying the original component.
+It is analogous to a <a href="https://en.wikipedia.org/wiki/Dependency_injection">dependency injection</a> framework, but curated for Log4j-specific needs.</p>
+</div>
+<div class="paragraph">
+<p>In a nutshell, you annotate your classes with <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/Plugin.html"><code>@Plugin</code></a> and their (<code>static</code>) factory methods with <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginFactory.html"><code>@PluginFactory</code></a>.
+Last, you inform the Log4j plugin system to discover these custom classes.
+This is done using running the <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/processor/PluginProcessor.html"><code>PluginProcessor</code></a> annotation processor while building your project.
+Refer to <a href="plugins.html" class="xref page">Plugins</a> for details.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="extending-appenders"><a class="anchor" href="#extending-appenders"></a>Extending appenders</h3>
+<div class="paragraph">
+<p>Appenders are <a href="plugins.html" class="xref page">plugins</a> implementing <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/Appender.html">the <code>Appender</code> interface</a>.
+We recommend users to extend from <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/appender/AbstractAppender.html"><code>AbstractAppender</code></a>, which provides implementation convenience.
+While annotating your appender with <code>@Plugin</code>, you need to make sure that</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>It has a unique <code>name</code> attribute across all available <code>Appender</code> plugins</p>
+</li>
+<li>
+<p>The <code>category</code> attribute is set to <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Node.html#CATEGORY"><code>Node.CATEGORY</code></a></p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Most appender implementation use <strong>managers</strong>, which model an abstraction owning the resources, such as an <code>OutputStream</code> or a socket.
+When a reconfiguration occurs a new appender will be created.
+However, if nothing significant in the previous manager has changed, the new appender will simply reference it instead of creating a new one.
+This ensures that events are not lost while a reconfiguration is taking place without requiring that logging pause while the reconfiguration takes place.
+You are strongly advised to study the manager concept in <a href="#collection">the predefined appenders</a>, and either use an existing manager, or create your own.</p>
+</div>
+<div class="paragraph">
+<p>You can check out following files for examples:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core/src/main/java/org/apache/logging/log4j/core/appender/HttpAppender.java"><code>HttpAppender.java</code></a> – <a href="#HttpAppender">HttpAppender</a> sends log events over HTTP using <code>HttpURLConnectionManager</code></p>
+</li>
+<li>
+<p><a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core/src/main/java/org/apache/logging/log4j/core/appender/ConsoleAppender.java"><code>ConsoleAppender.java</code></a> – <a href="#ConsoleAppender">[ConsoleAppender]</a> writes log events to either <code>System.out</code> or <code>System.err</code> using <code>OutputStreamManager</code></p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
</article>
</div>
</main>
diff --git a/manual/architecture.html b/manual/architecture.html
index 61c5fc45cd..60d20fec27 100644
--- a/manual/architecture.html
+++ b/manual/architecture.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -327,262 +327,212 @@
</aside>
<article class="doc">
<h1 class="page">Architecture</h1>
-<div class="sect1">
-<h2 id="_main_components"><a class="anchor" href="#_main_components"></a>Main Components</h2>
+<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
-<p>Log4j uses the classes shown in the diagram below.</p>
+<p>Log4j Core is the reference implementation of <a href="api.html" class="xref page">Log4j API</a> and composed of several components.
+In this section we will try to explain major pillars its architecture stands on.
+An overview these major classes can be depicted as follows:</p>
</div>
-<div class="paragraph">
-<p><span class="image"><img src="../_images/Log4jClasses.jpg" alt="Log4j 2 Class Relationships" title="Log4j 2 Class Relationships"></span></p>
+<div id="architecture-diagram" class="imageblock kroki">
+<div class="content">
+<img src="../_images/diag-ce9936638b62ac5c763a2a3b54dbda70bb0144ff.svg" alt="An overview of major classes and their relation">
+</div>
+<div class="title">Figure 1. An overview of major classes and their relation</div>
+</div>
+<div class="paragraph">
+<p>At a really high level,</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>A <a href="#LoggerContext"><code>LoggerContext</code></a>, the composition anchor, gets created in combination with a <a href="#Configuration"><code>Configuration</code></a>.
+Both can be created either directly (i.e., programmatically) or indirectly at first interaction with Log4j.</p>
+</li>
+<li>
+<p><code>LoggerContext</code> creates <a href="#Logger"><code>Logger</code></a>s that users interact with for logging purposes.</p>
+</li>
+<li>
+<p><a href="#Appender"><code>Appender</code></a> delivers a <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html"><code>LogEvent</code></a> to a target (file, socket, database, etc.) and typically uses a <a href="#Layout"><code>Layout</code></a> to encode log events and an <a href="#AbstractManager"><code>AbstractManager</code></a> to handle the lifecycle of the target resource.</p>
+</li>
+<li>
+<p><a href="#LoggerConfig"><code>LoggerConfig</code></a> encapsulates configuration for a <code>Logger</code>, as <code>AppenderControl</code> and <code>AppenderRef</code> for <code>Appender</code>s.</p>
+</li>
+<li>
+<p><a href="#Configuration"><code>Configuration</code></a> is equipped with <a href="#StrSubstitutor"><code>StrSubstitutor</code> et al.</a> to allow property substitution in <code>String</code>-typed values.</p>
+</li>
+<li>
+<p>A typical <code>log()</code> call triggers a chain of invocations through classes <code>Logger</code>, <code>LoggerConfig</code>, <code>AppenderControl</code>, <code>Appender</code>, and <code>AbstractManager</code> in order – this is depicted using green arrows in <a href="#architecture-diagram">Figure 1</a>.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>Applications using the Log4j 2 API will request a Logger with a specific
-name from the LogManager. The LogManager will locate the appropriate
-LoggerContext and then obtain the Logger from it. If the Logger must be
-created it will be associated with the LoggerConfig that contains either
-a) the same name as the Logger, b) the name of a parent package, or c)
-the root LoggerConfig. LoggerConfig objects are created from Logger
-declarations in the configuration. The LoggerConfig is associated with
-the Appenders that deliver the LogEvents.</p>
+<p>Following sections examine this interplay in detail.</p>
</div>
-<div class="sect2">
-<h3 id="logger-hierarchy"><a class="anchor" href="#logger-hierarchy"></a>Logger Hierarchy</h3>
-<div class="paragraph">
-<p>The first and foremost advantage of any logging API over plain
-<code>System.out.println()</code> resides in its ability to disable certain log
-statements while allowing others to print unhindered. This capability
-assumes that the logging space, that is, the space of all possible
-logging statements, is categorized according to some developer-chosen
-criteria.</p>
</div>
-<div class="paragraph">
-<p>In Log4j 1.x the Logger Hierarchy was maintained through a relationship
-between Loggers. In Log4j 2 this relationship no longer exists. Instead,
-the hierarchy is maintained in the relationship between LoggerConfig
-objects.</p>
</div>
+<div class="sect1">
+<h2 id="LoggerContext"><a class="anchor" href="#LoggerContext"></a><code>LoggerContext</code></h2>
+<div class="sectionbody">
<div class="paragraph">
-<p>Loggers and LoggerConfigs are named entities. Logger names are
-case-sensitive and they follow the hierarchical naming rule:</p>
-</div>
-<div class="dlist">
-<dl>
-<dt class="hdlist1">Named Hierarchy</dt>
-<dd>
-<p>A LoggerConfig is said to be an <em>ancestor</em> of another LoggerConfig if
-its name followed by a dot is a prefix of the <em>descendant</em> logger
-name. A LoggerConfig is said to be a <em>parent</em> of a <em>child</em>
-LoggerConfig if there are no ancestors between itself and the
-descendant LoggerConfig.</p>
-</dd>
-</dl>
+<p>The <a href="../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContext.html"><code>LoggerContext</code></a> acts as the anchor point for the logging system.
+It is associated with an active <a href="#Configuration"><code>Configuration</code></a> and is primarily responsible for instantiating <a href="#Logger"><code>Logger</code></a>s.</p>
</div>
-<div class="paragraph">
-<p>For example, the LoggerConfig named <code>"com.foo"</code> is a parent of the
-LoggerConfig named <code>"com.foo.Bar"</code>. Similarly, <code>"java"</code> is a parent of
-<code>"java.util"</code> and an ancestor of <code>"java.util.Vector"</code>. This naming
-scheme should be familiar to most developers.</p>
+<div id="LoggerContext-diagram" class="imageblock kroki">
+<div class="content">
+<img src="../_images/diag-3179a6738d88762b267e7c0bf55d9407cd45c450.svg" alt="`LoggerContext` and other directly related classes">
+</div>
+<div class="title">Figure 2. <code>LoggerContext</code> and other directly related classes</div>
</div>
<div class="paragraph">
-<p>The root LoggerConfig resides at the top of the LoggerConfig hierarchy.
-It is exceptional in that it always exists and it is part of every
-hierarchy. A Logger that is directly linked to the root LoggerConfig can
-be obtained as follows:</p>
+<p>In most cases, applications have a single global <code>LoggerContext</code>.
+Though in certain cases (e.g., Java EE applications), Log4j can be configured to accommodate multiple <code>LoggerContext</code>s.
+Refer to <a href="logsep.html" class="xref page">Logging Separation</a> for details.</p>
</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Logger logger = LogManager.getLogger(LogManager.ROOT_LOGGER_NAME);</code></pre>
</div>
</div>
+<div class="sect1">
+<h2 id="Configuration"><a class="anchor" href="#Configuration"></a><code>Configuration</code></h2>
+<div class="sectionbody">
<div class="paragraph">
-<p>Alternatively, and more simply:</p>
+<p>Every <a href="#LoggerContext"><code>LoggerContext</code></a> is associated with an active <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html"><code>Configuration</code></a>.
+It models the configuration of all appenders, layouts, filters, loggers, and contains the reference to <a href="#StrSubstitutor"><code>StrSubstitutor</code> et al.</a>.</p>
</div>
-<div class="listingblock">
+<div id="Configuration-diagram" class="imageblock kroki">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Logger logger = LogManager.getRootLogger();</code></pre>
+<img src="../_images/diag-1a68f90761e6350de59d964e3f2cfeb22b591a02.svg" alt="`Configuration` and other directly related classes">
</div>
+<div class="title">Figure 3. <code>Configuration</code> and other directly related classes</div>
</div>
<div class="paragraph">
-<p>All other Loggers can be retrieved using the
-<a href="../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html#getLogger(java.lang.String)"><code>LogManager.getLogger</code></a>
-static method by passing the name of the desired Logger. Further
-information on the Logging API can be found in the
-<a href="api.html" class="xref page">Log4j API</a>.</p>
-</div>
+<p>Configuration of Log4j Core is typically done at application initialization.
+The preferred way is by reading a <a href="configuration.html" class="xref page">configuration file</a>, but it can also be done <a href="customconfig.html" class="xref page">programmatically</a>.
+This is further discussed in <a href="config-intro.html" class="xref page">Configuration</a>.</p>
</div>
<div class="sect2">
-<h3 id="_loggercontext"><a class="anchor" href="#_loggercontext"></a>LoggerContext</h3>
+<h3 id="reconfiguration"><a class="anchor" href="#reconfiguration"></a>Reconfiguration reliability</h3>
+<div class="paragraph">
+<p>The main motivation for the existing architecture is the reliability to configuration changes.
+When a reconfiguration event occurs, two <code>Configuration</code> instances are active at the same time.
+Threads that already started processing a log event will either:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>continue logging to the old configuration, if execution already reached the <code>LoggerConfig</code> class,</p>
+</li>
+<li>
+<p>or switch to the new configuration.</p>
+</li>
+</ul>
+</div>
<div class="paragraph">
-<p>The
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/LoggerContext.html"><code>LoggerContext</code></a>
-acts as the anchor point for the Logging system. However, it is possible
-to have multiple active LoggerContexts in an application depending on
-the circumstances. More details on the LoggerContext are in the
-<a href="logsep.html" class="xref page">Log Separation</a> section.</p>
+<p>The service that manages the reconfiguration process is called <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/ReliabilityStrategy.html"><code>ReliabilityStrategy</code></a> and it decides:</p>
</div>
+<div class="ulist">
+<ul>
+<li>
+<p>when should <code>Logger</code>s switch to the new configuration,</p>
+</li>
+<li>
+<p>when should the old configuration be stopped.</p>
+</li>
+</ul>
</div>
-<div class="sect2">
-<h3 id="_configuration"><a class="anchor" href="#_configuration"></a>Configuration</h3>
-<div class="paragraph">
-<p>Every LoggerContext has an active
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html"><code>Configuration</code></a>.
-The Configuration contains all the Appenders, context-wide Filters,
-LoggerConfigs and contains the reference to the StrSubstitutor.
-During reconfiguration, two Configuration objects will exist. Once all Loggers
-have been redirected to the new Configuration, the old Configuration
-will be stopped and discarded.</p>
+<div class="imageblock kroki">
+<div class="content">
+<img src="../_images/diag-01168003b98f120d2f0736e5172de8e1218f189e.svg" alt="Overview of the reconfiguration process">
</div>
+<div class="title">Figure 4. Overview of the reconfiguration process</div>
</div>
-<div class="sect2">
-<h3 id="_logger"><a class="anchor" href="#_logger"></a>Logger</h3>
-<div class="paragraph">
-<p>As stated previously, Loggers are created by calling
-<a href="../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html#getLogger(java.lang.String)"><code>LogManager.getLogger</code></a>.
-The Logger itself performs no direct actions. It simply has a name and
-is associated with a LoggerConfig. It extends
-<a href="../javadoc/log4j-api/org/apache/logging/log4j/spi/AbstractLogger.html"><code>AbstractLogger</code></a>
-and implements the required methods. As the configuration is modified
-Loggers may become associated with a different LoggerConfig, thus
-causing their behavior to be modified.</p>
</div>
-<div class="paragraph">
-<p>Retrieving Loggers</p>
</div>
-<div class="paragraph">
-<p>Calling the <code>LogManager.getLogger</code> method with the same name will always
-return a reference to the same Logger object.</p>
</div>
+<div class="sect1">
+<h2 id="Logger"><a class="anchor" href="#Logger"></a><code>Logger</code></h2>
+<div class="sectionbody">
<div class="paragraph">
-<p>For example, in</p>
+<p><a href="../javadoc/log4j-api/org/apache/logging/log4j/Logger.html"><code>Logger</code></a>s are the primary user entry point for logging.
+They are created by calling one of the <code>getLogger()</code> methods of <a href="../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html"><code>LogManager</code></a> – this is further documented in <a href="api.html" class="xref page">Log4j API</a>.
+The <code>Logger</code> itself performs no direct actions.
+It simply has a name and is associated with a <a href="#LoggerConfig"><code>LoggerConfig</code></a>.</p>
</div>
-<div class="listingblock">
+<div id="Logger-diagram" class="imageblock kroki">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Logger x = LogManager.getLogger("wombat");
-Logger y = LogManager.getLogger("wombat");</code></pre>
+<img src="../_images/diag-77a13b00749af95e3ed0eefd605a73f25d70973c.svg" alt="`Logger` and other directly related classes">
</div>
+<div class="title">Figure 5. <code>Logger</code> and other directly related classes</div>
</div>
<div class="paragraph">
-<p><code>x</code> and <code>y</code> refer to <em>exactly</em> the same Logger object.</p>
+<p>The hierarchy between <a href="#LoggerConfig"><code>LoggerConfig</code></a>s, implies the very same hierarchy between <code>Logger</code>s too.
+You can use <code>LogManager.getRootLogger()</code> to get the root logger.
+Note that Log4j API has no assumptions on a <code>Logger</code> hierarchy – this is a feature implemented by Log4j Core.</p>
</div>
<div class="paragraph">
-<p>Configuration of the log4j environment is typically done at application
-initialization. The preferred way is by reading a configuration file.
-This is discussed in <a href="configuration.html" class="xref page">Configuration</a>.</p>
+<p>When the <a href="#Configuration"><code>Configuration</code></a> is modified, <code>Logger</code>s may become associated with a different <code>LoggerConfig</code>, thus causing their behavior to be modified.
+Refer to <a href="configuration.html#configuring-loggers" class="xref page">configuring <code>Logger</code>s</a> for further information.</p>
</div>
-<div class="paragraph">
-<p>Log4j makes it easy to name Loggers by <em>software component</em>. This can be
-accomplished by instantiating a Logger in each class, with the logger
-name equal to the fully qualified name of the class. This is a useful
-and straightforward method of defining loggers. As the log output bears
-the name of the generating Logger, this naming strategy makes it easy to
-identify the origin of a log message. However, this is only one
-possible, albeit common, strategy for naming loggers. Log4j does not
-restrict the possible set of loggers. The developer is free to name the
-loggers as desired.</p>
</div>
-<div class="paragraph">
-<p>Since naming Loggers after their owning class is such a common idiom,
-the convenience method <code>LogManager.getLogger()</code> is provided to
-automatically use the calling class’s fully qualified class name as the
-Logger name.</p>
</div>
+<div class="sect1">
+<h2 id="LoggerConfig"><a class="anchor" href="#LoggerConfig"></a><code>LoggerConfig</code></h2>
+<div class="sectionbody">
<div class="paragraph">
-<p>Nevertheless, naming loggers after the class where they are located
-seems to be the best strategy known so far.</p>
+<p><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/LoggerConfig.html"><code>LoggerConfig</code></a> binds <a href="#Logger"><code>Logger</code></a> definitions to their associated components (appenders, filters, etc.) as declared in the active <a href="#Configuration"><code>Configuration</code></a>.
+The details of mapping a <code>Configuration</code> to <code>LoggerConfig</code>s is explained <a href="configuration.html#configuring-loggers" class="xref page">here</a>.
+<code>Logger</code>s effectively interact with appenders, filters, etc. through corresponding <code>LoggerConfig</code>s.
+A <code>LoggerConfig</code> essentially contains</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>A reference to its parent (except if it is the root logger)</p>
+</li>
+<li>
+<p>A <a href="customloglevels.html" class="xref page">level</a> denoting the severity of messages that are accepted (defaults to <code>ERROR</code>)</p>
+</li>
+<li>
+<p><a href="#Filter"><code>Filter</code></a>s that must allow the <code>LogEvent</code> to pass before it will be passed to any <a href="#Appender"><code>Appender</code></a>s</p>
+</li>
+<li>
+<p>References to <a href="#Appender"><code>Appender</code></a>s that should be used to process the event</p>
+</li>
+</ul>
+</div>
+<div id="LoggerConfig-diagram" class="imageblock kroki">
+<div class="content">
+<img src="../_images/diag-2dc8fe44284ab476198b745bd5308956e31b6352.svg" alt="`LoggerConfig` and other directly related classes">
</div>
+<div class="title">Figure 6. <code>LoggerConfig</code> and other directly related classes</div>
</div>
<div class="sect2">
-<h3 id="loggerconfig"><a class="anchor" href="#loggerconfig"></a>LoggerConfig</h3>
+<h3 id="logger-hiearchy"><a class="anchor" href="#logger-hiearchy"></a>Logger hierarchy</h3>
<div class="paragraph">
-<p><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/LoggerConfig.html"><code>LoggerConfig</code></a>
-objects are created when Loggers are declared in the logging
-configuration. The LoggerConfig contains a set of Filters that must
-allow the LogEvent to pass before it will be passed to any Appenders. It
-contains references to the set of Appenders that should be used to
-process the event.</p>
-</div>
-<div class="sect3">
-<h4 id="_log_levels"><a class="anchor" href="#_log_levels"></a>Log Levels</h4>
-<div class="paragraph">
-<p>LoggerConfigs will be assigned a Log
-<a href="../javadoc/log4j-api/org/apache/logging/log4j/Level.html"><code>Level</code></a>.
-The set of built-in levels includes ALL, TRACE, DEBUG, INFO, WARN, ERROR,
-FATAL, and OFF. Log4j 2 also supports <a href="customloglevels.html" class="xref page">custom log
-levels</a>. Another mechanism for getting more granularity is to use
-<a href="markers.html" class="xref page">markers</a> instead. The OFF and ALL
-levels are not intended to be used on calls to the logging API.
-Specifying OFF in the configuration implies no logging events should
-match while specifying ALL would mean all events match, including custom
-events. However, OFF can be used on logging API calls in special cases
-where the event should always be logged regardless of the configuration.
-However, it is generally recommended that a Marker with a corresponding
-global Marker Filter be used instead.</p>
+<p>Log4j Core has a <strong>hierarchical</strong> model of <code>LoggerConfig</code>s, and hence <code>Logger</code>s.
+A <code>LoggerConfig</code> called <code>child</code> is said to be parented by <code>parent</code>, if <code>parent</code> has the <em>longest prefix match</em> on name.
+This match is case-sensitive and performed after tokenizing the name by splitting it from <code>.</code> (dot) characters.
+For a positive name match, tokens must match exhaustively.
+See <a href="#logger-hiearchy-diagram">Figure 7</a> for an example.</p>
</div>
-<div class="paragraph">
-<p><a href="https://logging.apache.org/log4j/1.x/manual.html">Log4j 1</a> and
-<a href="https://logback.qos.ch/manual/architecture.html#effectiveLevel">Logback</a>
-both have the concept of "Level Inheritance". In Log4j 2, Loggers and
-LoggerConfigs are two different objects so this concept is implemented
-differently. Each Logger references the appropriate LoggerConfig which
-in turn can reference its parent, thus achieving the same effect.</p>
+<div id="logger-hiearchy-diagram" class="imageblock kroki">
+<div class="content">
+<img src="../_images/diag-892fd9dbd9ea6bece55c1d4078ae1de2edd5c689.svg" alt="Example hierarchy of loggers named `X`, `X.Y`, `X.Y.Z`, and `X.YZ`">
+</div>
+<div class="title">Figure 7. Example hierarchy of loggers named <code>X</code>, <code>X.Y</code>, <code>X.Y.Z</code>, and <code>X.YZ</code></div>
</div>
<div class="paragraph">
-<p>Below are five tables with various assigned level values and the
-resulting levels that will be associated with each Logger. Note that in
-all these cases if the root LoggerConfig is not configured a default
-Level will be assigned to it.</p>
+<p>If a <code>LoggerConfig</code> is not provided an explicit level, it will be inherited from its parent.
+Similarly, if a user programmatically requests a <code>Logger</code> with a name that doesn’t have a directly corresponding <code>LoggerConfig</code> configuration entry with its name, the <code>LoggerConfig</code> of the parent will be used.</p>
</div>
-<table class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 1. Example 1</caption>
-<colgroup>
-<col style="width: 25%;">
-<col style="width: 25%;">
-<col style="width: 25%;">
-<col style="width: 25%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">Logger Name</th>
-<th class="tableblock halign-left valign-top">Assigned LoggerConfig</th>
-<th class="tableblock halign-left valign-top">LoggerConfig Level</th>
-<th class="tableblock halign-left valign-top">Logger Level</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y.Z</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
-</tr>
-</tbody>
-</table>
+<details>
+<summary class="title">Click for examples on <code>LoggerConfig</code> hierarchy</summary>
+<div class="content">
<div class="paragraph">
-<p>In example 1 above, only the root logger is configured and has a Log
-Level. All the other Loggers reference the root LoggerConfig and use its
-Level.</p>
+<p>Below we demonstrate the <code>LoggerConfig</code> hierarchy by means of <em>level inheritance</em>.
+That is, we will examine the effective level of a <code>Logger</code> in various <code>LoggerConfig</code> settings.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 2. Example 2</caption>
+<caption class="title">Table 1. Only the root logger is configured with a level, and it is <code>DEBUG</code></caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
@@ -591,45 +541,41 @@ Level.</p>
</colgroup>
<thead>
<tr>
-<th class="tableblock halign-left valign-top">Logger Name</th>
-<th class="tableblock halign-left valign-top">Assigned LoggerConfig</th>
-<th class="tableblock halign-left valign-top">LoggerConfig Level</th>
-<th class="tableblock halign-left valign-top">Level</th>
+<th class="tableblock halign-left valign-top">Logger name</th>
+<th class="tableblock halign-left valign-top">Assigned <code>LoggerConfig</code> name</th>
+<th class="tableblock halign-left valign-top">Configured level</th>
+<th class="tableblock halign-left valign-top">Effective level</th>
</tr>
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">INFO</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">INFO</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.Y</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y.Z</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y.Z</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">WARN</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">WARN</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.Y.Z</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>In example 2, all loggers have a configured LoggerConfig and obtain
-their Level from it.</p>
-</div>
<table class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 3. Example 3</caption>
+<caption class="title">Table 2. All loggers are configured with a level</caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
@@ -638,48 +584,41 @@ their Level from it.</p>
</colgroup>
<thead>
<tr>
-<th class="tableblock halign-left valign-top">Logger Name</th>
-<th class="tableblock halign-left valign-top">Assigned LoggerConfig</th>
-<th class="tableblock halign-left valign-top">LoggerConfig Level</th>
-<th class="tableblock halign-left valign-top">Level</th>
+<th class="tableblock halign-left valign-top">Logger name</th>
+<th class="tableblock halign-left valign-top">Assigned <code>LoggerConfig</code></th>
+<th class="tableblock halign-left valign-top">Configured level</th>
+<th class="tableblock halign-left valign-top">Effective level</th>
</tr>
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.Y</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.Y</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>INFO</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>INFO</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y.Z</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y.Z</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">WARN</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">WARN</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.Y.Z</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.Y.Z</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>WARN</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>WARN</code></p></td>
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>In example 3, the loggers`root`, <code>X</code> and <code>X.Y.Z</code> each have a configured
-LoggerConfig with the same name. The Logger <code>X.Y</code> does not have a
-configured LoggerConfig with a matching name so uses the configuration
-of LoggerConfig <code>X</code> since that is the LoggerConfig whose name has the
-the longest match to the start of the Logger’s name.</p>
-</div>
<table class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 4. Example 4</caption>
+<caption class="title">Table 3. All loggers are configured with a level, except the logger <code>X.Y</code></caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
@@ -688,48 +627,41 @@ the longest match to the start of the Logger’s name.</p>
</colgroup>
<thead>
<tr>
-<th class="tableblock halign-left valign-top">Logger Name</th>
-<th class="tableblock halign-left valign-top">Assigned LoggerConfig</th>
-<th class="tableblock halign-left valign-top">LoggerConfig Level</th>
-<th class="tableblock halign-left valign-top">level</th>
+<th class="tableblock halign-left valign-top">Logger name</th>
+<th class="tableblock halign-left valign-top">Assigned <code>LoggerConfig</code></th>
+<th class="tableblock halign-left valign-top">Configured level</th>
+<th class="tableblock halign-left valign-top">Effective level</th>
</tr>
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.Y</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X</code></p></td>
+<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y.Z</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.Y.Z</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.Y.Z</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>WARN</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>WARN</code></p></td>
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>In example 4, the loggers <code>root</code> and <code>X</code> each have a Configured
-LoggerConfig with the same name. The loggers <code>X.Y</code> and <code>X.Y.Z</code> do not
-have configured LoggerConfigs and so get their Level from the
-LoggerConfig assigned to them, <code>X</code>, since it is the LoggerConfig whose
-name has the longest match to the start of the Logger’s name.</p>
-</div>
<table class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 5. Example 5</caption>
+<caption class="title">Table 4. All loggers are configured with a level, except loggers <code>X.Y</code> and <code>X.Y.Z</code></caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
@@ -738,49 +670,41 @@ name has the longest match to the start of the Logger’s name.</p>
</colgroup>
<thead>
<tr>
-<th class="tableblock halign-left valign-top">Logger Name</th>
-<th class="tableblock halign-left valign-top">Assigned LoggerConfig</th>
-<th class="tableblock halign-left valign-top">LoggerConfig Level</th>
-<th class="tableblock halign-left valign-top">level</th>
+<th class="tableblock halign-left valign-top">Logger name</th>
+<th class="tableblock halign-left valign-top">Assigned <code>LoggerConfig</code></th>
+<th class="tableblock halign-left valign-top">Configured level</th>
+<th class="tableblock halign-left valign-top">Effective level</th>
</tr>
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">INFO</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">INFO</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.Y</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X</code></p></td>
+<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.YZ</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.Y.Z</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X</code></p></td>
+<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
</tr>
</tbody>
</table>
-<div class="paragraph">
-<p>In example 5, the loggers <code>root</code>.<code>X</code>, and <code>X.Y</code> each has a configured
-LoggerConfig with the same name. The logger <code>X.YZ</code> does not have
-configured LoggerConfig and so gets its Level from the LoggerConfig
-assigned to it, <code>X</code>, since it is the LoggerConfig whose name has the
-longest match to the start of the Logger’s name. It is not associated
-with LoggerConfig <code>X.Y</code> since tokens after periods must match exactly.</p>
-</div>
<table class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 6. Example 6</caption>
+<caption class="title">Table 5. All loggers are configured with a level, except the logger <code>X.YZ</code></caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
@@ -789,381 +713,268 @@ with LoggerConfig <code>X.Y</code> since tokens after periods must match exactly
</colgroup>
<thead>
<tr>
-<th class="tableblock halign-left valign-top">Logger Name</th>
-<th class="tableblock halign-left valign-top">Assigned LoggerConfig</th>
-<th class="tableblock halign-left valign-top">LoggerConfig Level</th>
-<th class="tableblock halign-left valign-top">Level</th>
+<th class="tableblock halign-left valign-top">Logger name</th>
+<th class="tableblock halign-left valign-top">Assigned <code>LoggerConfig</code></th>
+<th class="tableblock halign-left valign-top">Configured level</th>
+<th class="tableblock halign-left valign-top">Effective level</th>
</tr>
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">DEBUG</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y</p></td>
-<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.Y</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.Y</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>INFO</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>INFO</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y.Z</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">X.Y</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X.YZ</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>X</code></p></td>
<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">ERROR</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
</tr>
</tbody>
</table>
+</div>
+</details>
+<div class="paragraph">
+<p>For further information on log levels and using them for filtering purposes in a configuration, see <a href="customloglevels.html" class="xref page">Levels</a>.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="Filter"><a class="anchor" href="#Filter"></a><code>Filter</code></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>In addition to <a href="#LoggerConfig">the level-based filtering facilitated by <code>LoggerConfig</code></a>, Log4j provides <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/Filter.html"><code>Filter</code></a>s to evaluate the parameters of a logging call (i.e., context-wide filter) or a log event, and decide if it should be processed further in the pipeline.</p>
+</div>
+<div id="Filter-diagram" class="imageblock kroki">
+<div class="content">
+<img src="../_images/diag-96b353807a86d1e31f8907713d4f2b7fe5a59ce6.svg" alt="`Filter` and other directly related classes">
+</div>
+<div class="title">Figure 8. <code>Filter</code> and other directly related classes</div>
+</div>
<div class="paragraph">
-<p>In example 6, LoggerConfig X.Y has no configured level so it inherits
-its level from LoggerConfig X. Logger X.Y.Z uses LoggerConfig X.Y since
-it doesn’t have a LoggerConfig with a name that exactly matches. It too
-inherits its logging level from LoggerConfig X.</p>
+<p>Refer to <a href="filters.html" class="xref page">Filters</a> for further information.</p>
</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="Appender"><a class="anchor" href="#Appender"></a><code>Appender</code></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/Appender.html"><code>Appender</code></a>s are responsible for delivering a <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html"><code>LogEvent</code></a> to a certain target; console, file, database, etc.
+While doing so, they typically use <a href="#Layout"><code>Layout</code></a>s to encode the log event.
+See <a href="appenders.html" class="xref page">Appenders</a> for the complete guide.</p>
+</div>
+<div id="Appender-diagram" class="imageblock kroki">
+<div class="content">
+<img src="../_images/diag-d0e5615e7f18a6e132c1d6809c9813be92de6923.svg" alt="`Appender` and other directly related classes">
+</div>
+<div class="title">Figure 9. <code>Appender</code> and other directly related classes</div>
+</div>
+<div class="paragraph">
+<p>An <code>Appender</code> can be added to a <a href="#Logger"><code>Logger</code></a> by calling the <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html#addLoggerAppender(org.apache.logging.log4j.core.Logger,%20org.apache.logging.log4j.core.Appender)"><code>addLoggerAppender()</code></a> method of the current <a href="#Configuration"><code>Configuration</code></a>.
+If a <a href="#LoggerConfig"><code>LoggerConfig</code></a> matching the name of the <code>Logger</code> does not exist, one will be created, and the <code>Appender</code> will be attached to it, and then all <code>Logger</code>s will be notified to update their <code>LoggerConfig</code> references.</p>
+</div>
+<div class="sect2">
+<h3 id="appender-additivity"><a class="anchor" href="#appender-additivity"></a>Appender additivity</h3>
<div class="paragraph">
-<p>The table below illustrates how Level filtering works. In the table,
-the vertical header shows the Level of the LogEvent, while the horizontal
-header shows the Level associated with the appropriate LoggerConfig. The
-intersection identifies whether the LogEvent would be allowed to pass
-for further processing (Yes) or discarded (No).</p>
+<p>Each enabled logging request for a given logger will be forwarded to all the appenders in the corresponding <code>Logger</code>'s <code>LoggerConfig</code>, as well as to the <code>Appender</code>s of the <code>LoggerConfig</code>'s parents.
+In other words, <code>Appender</code>s are inherited <strong>additively</strong> from the <code>LoggerConfig</code> hierarchy.
+For example, if a console appender is added to the root logger, then all enabled logging requests will at least print on the console.
+If in addition a file appender is added to a <code>LoggerConfig</code>, say <code>LC</code>, then enabled logging requests for <code>LC</code> and <code>LC</code>'s children will print in a file <em>and</em> on the console.
+It is possible to override this default behavior so that appender accumulation is no longer additive by setting <code>additivity</code> attribute to <code>false</code> on <a href="configuration.html#configuring-loggers" class="xref page">the <code>Logger</code> declaration in the configuration file</a>.</p>
+</div>
+<div class="paragraph">
+<p>The output of a log statement of <code>Logger</code> <code>L</code> will go to all the appenders in the <code>LoggerConfig</code> associated with <code>L</code> and the ancestors of that <code>LoggerConfig</code>.
+However, if an ancestor of the <code>LoggerConfig</code> associated with <code>Logger</code>
+<code>L</code>, say <code>P</code>, has the additivity flag set to <code>false</code>, then <code>L</code>'s output will be directed to all the appenders in <code>L</code>'s <code>LoggerConfig</code> and it’s ancestors up to and including <code>P</code> but not the appenders in any of the ancestors of <code>P</code>.</p>
+</div>
+<details>
+<summary class="title">Click for an example on appender additivity</summary>
+<div class="content">
+<div id="appender-additivity-diagram" class="imageblock kroki">
+<div class="content">
+<img src="../_images/diag-58c484caf8cd616db4f1c7ed31b51c123b5859d4.svg" alt="Example hierarchy of logger configurations to demonstrate appender additivity">
+</div>
+<div class="title">Figure 10. Example hierarchy of logger configurations to demonstrate appender additivity</div>
+</div>
+<div class="paragraph">
+<p>In <a href="#appender-additivity-diagram">Figure 10</a>, the effective appenders for each logger configuration are as follows:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
+<caption class="title">Table 6. Effective appenders of logger configurations in <a href="#appender-additivity-diagram">Figure 10</a></caption>
<colgroup>
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
+<col style="width: 14.2857%;">
+<col style="width: 14.2857%;">
+<col style="width: 14.2857%;">
+<col style="width: 14.2857%;">
+<col style="width: 14.2857%;">
+<col style="width: 14.2857%;">
+<col style="width: 14.2858%;">
</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">Event Level</th>
-<th class="tableblock halign-left valign-top" colspan="7">LoggerConfig Level</th>
-</tr>
-</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>TRACE</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>INFO</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>WARN</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>FATAL</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>OFF</code></p></td>
+<th class="tableblock halign-center valign-middle" rowspan="2"><p class="tableblock">Appender</p></th>
+<th class="tableblock halign-center valign-top" colspan="6"><p class="tableblock">Logger configuration</p></th>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ALL</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>A</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>A.B1</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>A.B1.C</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>A.B1.C.D</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>A.B2.C</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>A.B2.C.D</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>TRACE</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>root</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>DEBUG</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>INFO</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>A</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>WARN</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>A.B1</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ERROR</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>A.B1.C</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>FATAL</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>A.B1.C.D</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>A.B2.C</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>OFF</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>A.B2.C.D</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td>
</tr>
</tbody>
</table>
</div>
+</details>
</div>
<div class="sect2">
-<h3 id="_filter"><a class="anchor" href="#_filter"></a>Filter</h3>
+<h3 id="AbstractManager"><a class="anchor" href="#AbstractManager"></a><code>AbstractManager</code></h3>
<div class="paragraph">
-<p>In addition to the automatic log Level filtering that takes place as
-described in the previous section, Log4j provides
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/Filter.html"><code>Filter</code></a>s
-that can be applied before control is passed to any LoggerConfig, after
-control is passed to a LoggerConfig but before calling any Appenders,
-after control is passed to a LoggerConfig but before calling a specific
-Appender, and on each Appender. In a manner very similar to firewall
-filters, each Filter can return one of three results, <code>Accept</code>, <code>Deny</code>
-or <code>Neutral</code>. A response of <code>Accept</code> means that no other Filters should
-be called and the event should progress. A response of <code>Deny</code> means the
-event should be immediately ignored and control should be returned to
-the caller. A response of <code>Neutral</code> indicates the event should be passed
-to other Filters. If there are no other Filters the event will be
-processed.</p>
+<p>To multiplex the access to external resources (files, network connections, etc.), most appenders are split into an
+<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/appender/AbstractManager.html"><code>AbstractManager</code></a>
+that handles the low-level access to the external resource and an <code>Appender</code> that transforms log events into a format that the manager can handle.</p>
</div>
<div class="paragraph">
-<p>Although an event may be accepted by a Filter the event still might not
-be logged. This can happen when the event is accepted by the
-pre-LoggerConfig Filter but is then denied by a LoggerConfig filter or
-is denied by all Appenders.</p>
+<p>Managers that share the same resource are shared between appenders regardless of the <code>Configuration</code> or <code>LoggerContext</code> of the appenders.
+For example
+<a href="appenders.html#FileAppender" class="xref page"><code>FileAppender</code></a>s
+with the same <code>fileName</code> attribute all share the same
+<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/appender/FileManager.html"><code>FileManager</code></a>.</p>
</div>
-</div>
-<div class="sect2">
-<h3 id="_appender"><a class="anchor" href="#_appender"></a>Appender</h3>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
<div class="paragraph">
-<p>The ability to selectively enable or disable logging requests based on
-their logger is only part of the picture. Log4j allows logging requests
-to print to multiple destinations. In log4j speak, an output destination
-is called an
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/Appender.html"><code>Appender</code></a>.
-Currently, appenders exist for the console, files, remote socket
-servers, Apache Flume, remote UNIX Syslog daemons, and various
-database APIs. See the section on <a href="appenders.html" class="xref page">Appenders</a> for
-more details on the various types available. More than one Appender can
-be attached to a Logger.</p>
+<p>Due to the manager-sharing feature of many Log4j appenders, it is not possible to configure multiple appenders for the same resource that only differ in the way the underlying resource is configured.</p>
</div>
<div class="paragraph">
-<p>An Appender can be added to a Logger by calling the
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html#addLoggerAppender(org.apache.logging.log4j.core.Logger,%20org.apache.logging.log4j.core.Appender)"><code>addLoggerAppender</code></a>
-method of the current Configuration. If a LoggerConfig matching the name
-of the Logger does not exist, one will be created, and the Appender will be
-attached to it and then all Loggers will be notified to update their
-LoggerConfig references.</p>
+<p>For example, it is not possible to have two file appenders (even in different logger contexts) that use the same file, but a different value of the <code>append</code> option.
+Since during a <a href="#reconfiguration">reconfiguration event</a> multiple instances of the same appender exists, it is also not possible to toggle the value of the <code>append</code> option through reconfiguration.</p>
</div>
-<div class="paragraph">
-<p><strong>Each enabled logging request for a given logger will be forwarded to
-all the appenders in that Logger’s LoggerConfig as well as the Appenders
-of the LoggerConfig’s parents.</strong> In other words, Appenders are inherited
-additively from the LoggerConfig hierarchy. For example, if a console
-appender is added to the root logger, then all enabled logging requests
-will at least print on the console. If in addition a file appender is
-added to a LoggerConfig, say <em>C</em>, then enabled logging requests for <em>C</em>
-and <em>C</em>'s children will print in a file <em>and</em> on the console. It is
-possible to override this default behavior so that Appender accumulation
-is no longer additive by setting <code>additivity="false"</code> on the Logger
-declaration in the configuration file.</p>
+</td>
+</tr>
+</table>
</div>
-<div class="paragraph">
-<p>The rules governing appender additivity are summarized below.</p>
-</div>
-<div class="dlist">
-<dl>
-<dt class="hdlist1">Appender Additivity</dt>
-<dd>
-<p>The output of a log statement of Logger <em>L</em> will go to all the
-Appenders in the LoggerConfig associated with <em>L</em> and the ancestors of
-that LoggerConfig. This is the meaning of the term "appender
-additivity".</p>
-<div class="paragraph">
-<p>However, if an ancestor of the LoggerConfig associated with Logger
-<em>L</em>, say <em>P</em>, has the additivity flag set to <code>false</code>, then <em>L</em>'s
-output will be directed to all the appenders in <em>L</em>'s LoggerConfig and
-it’s ancestors up to and including <em>P</em> but not the Appenders in any of
-the ancestors of <em>P</em>.</p>
</div>
-<div class="paragraph">
-<p>Loggers have their additivity flag set to <code>true</code> by default.</p>
</div>
-</dd>
-</dl>
</div>
+<div class="sect1">
+<h2 id="Layout"><a class="anchor" href="#Layout"></a><code>Layout</code></h2>
+<div class="sectionbody">
<div class="paragraph">
-<p>The table below shows an example:</p>
+<p>An <a href="#Appender"><code>Appender</code></a> uses a <strong>layout</strong> to encode a <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html"><code>LogEvent</code></a> into a form that meets the needs of whatever will be consuming the log event.</p>
</div>
-<table class="tableblock frame-all grid-all stretch">
-<colgroup>
-<col style="width: 20%;">
-<col style="width: 20%;">
-<col style="width: 20%;">
-<col style="width: 20%;">
-<col style="width: 20%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">Logger Name</th>
-<th class="tableblock halign-left valign-top">Added Appenders</th>
-<th class="tableblock halign-left valign-top">Additivity Flag</th>
-<th class="tableblock halign-left valign-top">Output Targets</th>
-<th class="tableblock halign-left valign-top">Comment</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">root</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">A1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">not applicable</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">A1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">The root logger has no parent so additivity does not apply to it.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">x</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">A-x1, A-x2</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">A1, A-x1, A-x2</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Appenders of "x" and root.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">x.y</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">A1, A-x1, A-x2</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Appenders of "x" and root. It would not be typical to configure a Logger with no Appenders.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">x.y.z</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">A-xyz1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">A1, A-x1, A-x2, A-xyz1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Appenders in "x.y.z", "x" and root.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">security</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">A-sec</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">A-sec</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">No appender accumulation since the additivity flag is set to <code>false</code>.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">security.access</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">A-sec</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Only appenders of "security" because the additivity flag in "security" is set to <code>false</code>.</p></td>
-</tr>
-</tbody>
-</table>
+<div id="Layout-diagram" class="imageblock kroki">
+<div class="content">
+<img src="../_images/diag-232cdf1d44336897239fa03f6521cc730f38f32d.svg" alt="`Layout` and other directly related classes">
</div>
-<div class="sect2">
-<h3 id="_layout"><a class="anchor" href="#_layout"></a>Layout</h3>
-<div class="paragraph">
-<p>More often than not, users wish to customize not only the output
-destination but also the output format. This is accomplished by
-associating a
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/Layout.html"><code>Layout</code></a>
-with an Appender. The Layout is responsible for formatting the LogEvent
-according to the user’s wishes, whereas an appender takes care of
-sending the formatted output to its destination. The
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternLayout.html"><code>PatternLayout</code></a>,
-part of the standard log4j distribution, lets the user specify the
-output format according to conversion patterns similar to the C language
-<code>printf()</code> function.</p>
+<div class="title">Figure 11. <code>Layout</code> and other directly related classes</div>
</div>
<div class="paragraph">
-<p>For example, the PatternLayout with the conversion pattern "%r [%t] %-5p
-%c - %m%n" will output something akin to:</p>
+<p>Refer to <a href="layouts.html" class="xref page">Layouts</a> for details.</p>
</div>
-<div class="literalblock">
-<div class="content">
-<pre>176 [main] INFO org.foo.Bar - Located nearest gas station.</pre>
</div>
</div>
+<div class="sect1">
+<h2 id="StrSubstitutor"><a class="anchor" href="#StrSubstitutor"></a><code>StrSubstitutor</code> et al.</h2>
+<div class="sectionbody">
<div class="paragraph">
-<p>The first field is the number of milliseconds elapsed since the start of
-the program. The second field is the thread making the log request. The
-third field is the level of the log statement. The fourth field is the
-name of the logger associated with the log request. The text after the
-'-' is the message of the statement.</p>
-</div>
-<div class="paragraph">
-<p>Log4j comes with many different <a href="layouts.html" class="xref page">Layouts</a> for various
-use cases such as JSON, XML, HTML, and Syslog (including the new RFC
-5424 version). Other appenders such as the database connectors fill in
-specified fields instead of a particular textual layout.</p>
+<p><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrSubstitutor.html"><code>StrSubstitutor</code></a> is a <code>String</code> interpolation tool that can be used in both configurations and components (e.g., appenders, layouts).
+It accepts an <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/Interpolator.html"><code>Interpolator</code></a> to determine if a key maps to a certain value.
+<code>Interpolator</code> is essentially a facade delegating to multiple <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html"><code>StrLookup</code></a> (aka. <em>lookup</em>) implementations.</p>
</div>
-<div class="paragraph">
-<p>Just as importantly, log4j will render the content of the log message
-according to user-specified criteria. For example, if you frequently
-need to log <code>Oranges</code>, an object type used in your current project, then
-you can create an OrangeMessage that accepts an Orange instance and pass
-that to Log4j so that the Orange object can be formatted into an
-appropriate byte array when required.</p>
+<div id="StrSubstitutor-diagram" class="imageblock kroki">
+<div class="content">
+<img src="../_images/diag-7a08e5a79432e9299cc0d9671bd39677be5618e8.svg" alt="`StrSubstitutor` et al. and other directly related classes">
</div>
+<div class="title">Figure 12. <code>StrSubstitutor</code> et al. and other directly related classes</div>
</div>
-<div class="sect2">
-<h3 id="_strsubstitutor_and_strlookup"><a class="anchor" href="#_strsubstitutor_and_strlookup"></a>StrSubstitutor and StrLookup</h3>
<div class="paragraph">
-<p>The
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrSubstitutor.html"><code>StrSubstitutor</code></a>
-class and
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html"><code>StrLookup</code></a>
-interface was borrowed from
-<a href="https://commons.apache.org/proper/commons-lang/">Apache Commons Lang</a> and
-then modified to support evaluating LogEvents. In addition the
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/Interpolator.html"><code>Interpolator</code></a>
-class was borrowed from Apache Commons Configuration to allow the
-StrSubstitutor to evaluate variables from multiple StrLookups. It
-too was modified to support evaluating LogEvents. Together these provide
-a mechanism to allow the configuration to reference variables coming
-from System Properties, the configuration file, the ThreadContext Map,
-StructuredData in the LogEvent. The variables can either be resolved
-when the configuration is processed or as each event is processed if
-the component is capable of handling it. See <a href="lookups.html" class="xref page">Lookups</a>
-for more information.</p>
-</div>
+<p>See <a href="configuration.html#property-substitution" class="xref page">how property substitution works</a> and <a href="lookups.html" class="xref page">the predefined lookups</a> for further information.</p>
</div>
</div>
</div>
diff --git a/manual/async.html b/manual/async.html
index 0db18fdf83..49bc3cf6ad 100644
--- a/manual/async.html
+++ b/manual/async.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/cloud.html b/manual/cloud.html
index c2afa32141..a0f1a60298 100644
--- a/manual/cloud.html
+++ b/manual/cloud.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/compatibility.html b/manual/compatibility.html
index e5974f9f4a..e341bb0d16 100644
--- a/manual/compatibility.html
+++ b/manual/compatibility.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/config-intro.html b/manual/config-intro.html
index 9de949bd8a..1b9b80dbc1 100644
--- a/manual/config-intro.html
+++ b/manual/config-intro.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -328,36 +328,21 @@
<article class="doc">
<h1 class="page">Configuration</h1>
<div class="paragraph">
-<p>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.</p>
-</div>
-<div class="paragraph">
-<p>To decide which of these statements will be logged and where, users need to configure Log4j Core in one of two ways:</p>
+<p>Even moderately sized applications can contain thousands of logging statements.
+To decide which of these statements will be logged and where, users need to configure Log4j Core in one of following ways:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>through a <a href="configuration.html" class="xref page">Configuration file</a>.
-Since version 2.0, the configuration file format has been considered part of the public API and has remained stable across significant version upgrades.</p>
+<p>Through a <a href="configuration.html" class="xref page">configuration file</a></p>
</li>
<li>
-<p>through <a href="customconfig.html" class="xref page">Programmatic Configuration</a>, which provides a larger spectrum of possible customizations but might require code changes during version upgrades.</p>
+<p>Through <a href="customconfig.html" class="xref page">programmatic configuration</a></p>
</li>
</ul>
</div>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
<div class="paragraph">
-<p>To prevent a chicken-and-egg problem, users can only supply some configuration options (e.g., the configuration file location) through <a href="systemproperties.html" class="xref page">configuration properties</a>.</p>
-</div>
-</td>
-</tr>
-</table>
+<p>Some meta-configuration options (e.g., the configuration file location) are only available through <a href="systemproperties.html" class="xref page">system properties</a>.</p>
</div>
</article>
</div>
diff --git a/manual/configuration.html b/manual/configuration.html
index 0467b6069d..edefe2ef49 100644
--- a/manual/configuration.html
+++ b/manual/configuration.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -331,11 +331,149 @@
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
-<p>Users can configure Log4j Core using different file formats.
-The <code>log4j-core</code> artifact includes XML, JSON, YAML, and Java properties formats factories.</p>
+<p>Using a configuration file is the most popular and recommended approach for configuring Log4j Core.
+In this page we will examine the composition of a configuration file and how Log4j Core uses it.</p>
</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>If you are looking for a quick start on using Log4j in your application or library, please refer to <a href="getting-started.html" class="xref page">Getting started</a> instead.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="automatic-configuration"><a class="anchor" href="#automatic-configuration"></a><a id="AutomaticConfiguration"></a> Configuration file location</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Upon initialization of a new <a href="architecture.html#LoggerContext" class="xref page">logger context, the anchor of the logging implementation</a>, Log4j Core assigns it a context name and scans the following <strong>classpath</strong> locations for a configuration file in following order:</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>Files named <code>log4j2-test<contextName>.<extension></code></p>
+</li>
+<li>
+<p>Files named <code>log4j2-test.<extension></code></p>
+</li>
+<li>
+<p>Files named <code>log4j2<contextName>.<extension></code></p>
+</li>
+<li>
+<p>Files named <code>log4j2.<extension></code></p>
+</li>
+</ol>
+</div>
+<div class="paragraph">
+<p>The <code><contextName></code> and <code><extension></code> placeholders above have the following meaning</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><contextName></dt>
+<dd>
+<p>A name derived from the runtime environment:</p>
+<div class="ulist">
+<ul>
+<li>
+<p>For standalone Java SE applications, it is a random identifier.</p>
+</li>
+<li>
+<p>For web applications, it is an identifier derived from the application descriptor.
+See <a href="webapp.html#configuration" class="xref page">Log4j Web application configuration</a> for details.</p>
+</li>
+</ul>
+</div>
+</dd>
+<dt class="hdlist1"><extension></dt>
+<dd>
+<p>A file extension supported by a <code>ConfigurationFactory</code>.
+The order in which an extension will be searched for first depends on the order of the associated <code>ConfigurationFactory</code>.
+See <a href="#configuration-factories">Predefined <code>ConfigurationFactory</code> plugins</a> for details.</p>
+</dd>
+</dl>
+</div>
+<div class="paragraph">
+<p>If no configuration file is found, Log4j Core uses the <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/DefaultConfiguration.html"><code>DefaultConfiguration</code></a> and the <a href="status-logger.html" class="xref page">status logger</a> prints a warning.
+The default configuration prints all messages less specific than <a href="systemproperties.html#log4j2.level" class="xref page"><code>log4j2.level</code></a> to the console.</p>
+</div>
+<div class="paragraph">
+<p>You can override the location of the configuration file using the <a href="systemproperties.html#log4j2.configurationFile" class="xref page">the <code>log4j2.configurationFile</code> system property</a>.
+In such a case, Log4j Core will guess the configuration file format from the provided file name, or use the default configuration factory if the extension is unknown.</p>
+</div>
+<div class="paragraph">
+<p>There are certain <strong>best-practices</strong> we strongly recommend you to adapt in your Log4j configuration:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Files prefixed by <code>log4j2-test</code> should only be used on the test classpath.</p>
+</li>
+<li>
+<p>If you are developing an application, don’t use multiple Log4j configuration files with same name, but different extensions.
+That is, don’t provide both <code>log4j2.xml</code> and <code>log4j2.json</code> files.</p>
+</li>
+<li>
+<p>If you are developing a library, only add configuration files to your test classpath.</p>
+</li>
+</ul>
+</div>
+<div class="sect2">
+<h3 id="configuration-factories"><a class="anchor" href="#configuration-factories"></a>Predefined <code>ConfigurationFactory</code> plugins</h3>
<div class="paragraph">
-<p>As detailed in the table below, some configuration formats require additional dependencies on the classpath.</p>
+<p>Log4j Core uses plugins extending from <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory.html"><code>ConfigurationFactory</code></a> to determine which configuration file extensions are supported, in which order, and how to read them.
+How this works under the hood and how you can introduce your custom implementations is explained in <a href="#ConfigurationFactory">Extending <code>ConfigurationFactory</code> plugins</a>.</p>
+</div>
+<table class="tableblock frame-all grid-all stretch">
+<caption class="title">Table 1. Supported configuration file formats by predefined <code>ConfigurationFactory</code> plugins</caption>
+<colgroup>
+<col style="width: 33.3333%;">
+<col style="width: 33.3333%;">
+<col style="width: 33.3334%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">File format</th>
+<th class="tableblock halign-left valign-top">Extension</th>
+<th class="tableblock halign-left valign-top">Order</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">XML</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xml</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">JSON</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>json, jsn</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">YAML</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>yaml, yml</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">7</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Properties</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>properties</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">8</p></td>
+</tr>
+</tbody>
+</table>
+<div class="paragraph">
+<p>Note that <code>ConfigurationFactory</code> plugins will be employed in descending order.
+That is, for instance, XML file format will be checked last, as a fallback.</p>
+</div>
+<div class="paragraph">
+<p>Some <code>ConfigurationFactory</code> plugins require additional dependencies on the classpath:</p>
</div>
<div id="_tabs_1" class="openblock tabs is-sync is-loading">
<div class="content">
@@ -354,26 +492,26 @@ The <code>log4j-core</code> artifact includes XML, JSON, YAML, and Java properti
<div class="content">
<div class="ulist tablist">
<ul>
-<li id="_tabs_2_log4j2_xml" class="tab">
-<p>log4j2.xml</p>
+<li id="_tabs_2_xml" class="tab">
+<p>XML</p>
</li>
-<li id="_tabs_2_log4j2_json" class="tab">
-<p>log4j2.json</p>
+<li id="_tabs_2_json" class="tab">
+<p>JSON</p>
</li>
-<li id="_tabs_2_log4j2_yaml" class="tab">
-<p>log4j2.yaml</p>
+<li id="_tabs_2_yaml" class="tab">
+<p>YAML</p>
</li>
-<li id="_tabs_2_log4j2_properties" class="tab">
-<p>log4j2.properties</p>
+<li id="_tabs_2_properties" class="tab">
+<p>Properties</p>
</li>
</ul>
</div>
-<div id="_tabs_2_log4j2_xml--panel" class="tabpanel" aria-labelledby="_tabs_2_log4j2_xml">
+<div id="_tabs_2_xml--panel" class="tabpanel" aria-labelledby="_tabs_2_xml">
<div class="paragraph">
<p>No dependency required.</p>
</div>
</div>
-<div id="_tabs_2_log4j2_json--panel" class="tabpanel" aria-labelledby="_tabs_2_log4j2_json">
+<div id="_tabs_2_json--panel" class="tabpanel" aria-labelledby="_tabs_2_json">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><dependency>
@@ -385,7 +523,7 @@ The <code>log4j-core</code> artifact includes XML, JSON, YAML, and Java properti
</div>
</div>
</div>
-<div id="_tabs_2_log4j2_yaml--panel" class="tabpanel" aria-labelledby="_tabs_2_log4j2_yaml">
+<div id="_tabs_2_yaml--panel" class="tabpanel" aria-labelledby="_tabs_2_yaml">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><dependency>
@@ -397,7 +535,7 @@ The <code>log4j-core</code> artifact includes XML, JSON, YAML, and Java properti
</div>
</div>
</div>
-<div id="_tabs_2_log4j2_properties--panel" class="tabpanel" aria-labelledby="_tabs_2_log4j2_properties">
+<div id="_tabs_2_properties--panel" class="tabpanel" aria-labelledby="_tabs_2_properties">
<div class="paragraph">
<p>No dependency required.</p>
</div>
@@ -410,40 +548,40 @@ The <code>log4j-core</code> artifact includes XML, JSON, YAML, and Java properti
<div class="content">
<div class="ulist tablist">
<ul>
-<li id="_tabs_3_log4j2_xml" class="tab">
-<p>log4j2.xml</p>
+<li id="_tabs_3_xml" class="tab">
+<p>XML</p>
</li>
-<li id="_tabs_3_log4j2_json" class="tab">
-<p>log4j2.json</p>
+<li id="_tabs_3_json" class="tab">
+<p>JSON</p>
</li>
-<li id="_tabs_3_log4j2_yaml" class="tab">
-<p>log4j2.yaml</p>
+<li id="_tabs_3_yaml" class="tab">
+<p>YAML</p>
</li>
-<li id="_tabs_3_log4j2_properties" class="tab">
-<p>log4j2.properties</p>
+<li id="_tabs_3_properties" class="tab">
+<p>Properties</p>
</li>
</ul>
</div>
-<div id="_tabs_3_log4j2_xml--panel" class="tabpanel" aria-labelledby="_tabs_3_log4j2_xml">
+<div id="_tabs_3_xml--panel" class="tabpanel" aria-labelledby="_tabs_3_xml">
<div class="paragraph">
<p>No dependency required.</p>
</div>
</div>
-<div id="_tabs_3_log4j2_json--panel" class="tabpanel" aria-labelledby="_tabs_3_log4j2_json">
+<div id="_tabs_3_json--panel" class="tabpanel" aria-labelledby="_tabs_3_json">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">runtimeOnly 'com.fasterxml.jackson.core:jackson-databind:2.17.1'</code></pre>
</div>
</div>
</div>
-<div id="_tabs_3_log4j2_yaml--panel" class="tabpanel" aria-labelledby="_tabs_3_log4j2_yaml">
+<div id="_tabs_3_yaml--panel" class="tabpanel" aria-labelledby="_tabs_3_yaml">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">runtimeOnly 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.17.1'</code></pre>
</div>
</div>
</div>
-<div id="_tabs_3_log4j2_properties--panel" class="tabpanel" aria-labelledby="_tabs_3_log4j2_properties">
+<div id="_tabs_3_properties--panel" class="tabpanel" aria-labelledby="_tabs_3_properties">
<div class="paragraph">
<p>No dependency required.</p>
</div>
@@ -453,180 +591,49 @@ The <code>log4j-core</code> artifact includes XML, JSON, YAML, and Java properti
</div>
</div>
</div>
-<div class="admonitionblock warning">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-warning" title="Warning"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>The format of the configuration file changed between Log4j 1 and Log4j 2.
-Files in the Log4j 1 format are ignored by default.</p>
-</div>
-<div class="paragraph">
-<p>To enable partial support for old configuration formats, see <a href="migration.html#ConfigurationCompatibility" class="xref page">configuration compatibility</a>.</p>
-</div>
-</td>
-</tr>
-</table>
</div>
</div>
</div>
<div class="sect1">
-<h2 id="automatic-configuration"><a class="anchor" href="#automatic-configuration"></a><a id="AutomaticConfiguration"></a> Configuration file location</h2>
+<h2 id="configuration-syntax"><a class="anchor" href="#configuration-syntax"></a><a id="ConfigurationSyntax"></a> Syntax</h2>
<div class="sectionbody">
-<div class="paragraph">
-<p>Upon initialization of a new logger context, Log4j assigns it a context name and scans the following <strong>classpath</strong> locations for a configuration file:</p>
-</div>
-<div class="olist arabic">
-<ol class="arabic">
-<li>
-<p>Files named <code>log4j2-test<contextName>.<extension></code></p>
-</li>
-<li>
-<p>Files named <code>log4j2-test.<extension></code>,</p>
-</li>
-<li>
-<p>Files named <code>log4j2<contextName>.<extension></code></p>
-</li>
-<li>
-<p>Files named <code>log4j2.<extension></code>,</p>
-</li>
-<li>
-<p>If no configuration file is found, Log4j uses the
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/DefaultConfiguration.html"><code>DefaultConfiguration</code></a>
-and the <a href="status-logger.html" class="xref page">status logger</a> prints a warning.
-The default configuration prints all messages less specific than
-<a href="systemproperties.html#log4j2.level" class="xref page"><code>log4j2.level</code></a>
-to the console.</p>
-</li>
-</ol>
-</div>
-<div class="admonitionblock warning">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-warning" title="Warning"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
-<p>The configuration files prefixed by <code>log4j2-test</code> should only be used on the test classpath.</p>
-</div>
-<div class="paragraph">
-<p>If multiple configuration files in the same category are found, Log4j uses a deterministic order to choose one of them (see
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Order.html"><code>@Order</code></a>).</p>
-</div>
-<div class="paragraph">
-<p>Nevertheless:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>If you’re developing an app, don’t use config files with different extensions.</p>
-</li>
-<li>
-<p>If you’re developing a library, only add config files to your test classpath.</p>
-</li>
-</ul>
+<p>Starting with Log4j 2, the configuration file syntax has been considered part of the public API and has remained stable across significant version upgrades.</p>
</div>
</td>
</tr>
</table>
</div>
-<div class="paragraph">
-<p>The <code><contextName></code> and <code><extension></code> placeholders above have the following meaning</p>
-</div>
-<div class="dlist">
-<dl>
-<dt class="hdlist1"><contextName></dt>
-<dd>
-<p>depends on the runtime environment in which Log4j runs:</p>
-<div class="ulist">
-<ul>
-<li>
-<p>for standalone Java SE applications, it is a random identifier,</p>
-</li>
-<li>
-<p>for web applications, it is derived from the application descriptor.
-See <a href="webapp.html#configuration" class="xref page">Log4j
- Web application configuration</a> for more details.</p>
-</li>
-</ul>
-</div>
-</dd>
-<dt class="hdlist1"><extension></dt>
-<dd>
-<p>must be one of the file extensions assigned to a configuration file format:</p>
-<table class="tableblock frame-all grid-all stretch">
-<colgroup>
-<col style="width: 50%;">
-<col style="width: 50%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">Configuration file format</th>
-<th class="tableblock halign-left valign-top">Extension</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">XML</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>xml</code></p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">JSON</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>json</code> or <code>jsn</code></p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">YAML</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>yaml</code> or <code>yml</code></p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Java properties</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>properties</code></p></td>
-</tr>
-</tbody>
-</table>
-</dd>
-</dl>
-</div>
-<div class="admonitionblock note">
+<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
-<i class="fa icon-note" title="Note"></i>
+<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
<div class="paragraph">
-<p>It is also possible to override the location of the configuration file using the
-<a href="systemproperties.html#log4j2.configurationFile" class="xref page"><code>log4j2.configurationFile</code></a>
-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.</p>
-</div>
-<div class="paragraph">
-<p>See <a href="systemproperties.html#log4j2.configurationFile" class="xref page"><code>log4j2.configurationFile</code></a> for details.</p>
+<p>The syntax of the configuration file changed between Log4j 1 and Log4j 2.
+Files in the Log4j 1 syntax are ignored by default.
+To enable partial support for old configuration syntax, see <a href="migration.html#ConfigurationCompatibility" class="xref page">configuration compatibility</a>.</p>
</div>
</td>
</tr>
</table>
</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="configuration-syntax"><a class="anchor" href="#configuration-syntax"></a><a id="ConfigurationSyntax"></a> Syntax</h2>
-<div class="sectionbody">
<div class="paragraph">
<p>The Log4j runtime is composed of <a href="plugins.html" class="xref page">plugins</a>, which are like beans in the Spring Framework and Java EE.
Appenders, layouts, filters, configuration loaders, and similar components are all accessed as plugins.</p>
</div>
<div class="paragraph">
-<p>All configuration files are represented internally as a tree of
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Node.html"><code>Node</code></a>s,
-which is translated into a tree of Log4j plugins.
-The tree’s root creates a
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html"><code>Configuration</code></a>
-object.</p>
+<p>All configuration files are represented internally as a tree of <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Node.html"><code>Node</code></a>s, which is translated into a tree of Log4j plugins.
+The tree’s root creates a <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html"><code>Configuration</code></a> object.</p>
</div>
<div class="paragraph">
<p>A node is a relatively simple structure representing a single Log4j plugin (see <a href="../plugin-reference.html" class="xref page">Plugin reference</a> for a complete list), such as an appender, layout, or logger configuration.</p>
@@ -1325,12 +1332,6 @@ Between the two operations log events might be lost.</p>
</table>
</div>
</div>
-<div class="sect2">
-<h3 id="configuration-elements-filters"><a class="anchor" href="#configuration-elements-filters"></a>Filters</h3>
-<div class="paragraph">
-<p>See <a href="filters.html#filters" class="xref page">Filters</a> for additional filtering capabilities that can be applied to the global configuration object.</p>
-</div>
-</div>
</div>
</div>
<div class="sect1">
@@ -1379,7 +1380,7 @@ Other logger configurations are optional.</p>
<p>Every
<a href="../javadoc/log4j-api/org/apache/logging/log4j/Logger.html"><code>Logger</code></a>
in your application is assigned to one of these logger configurations (see
-<a href="architecture.html#loggerconfig" class="xref page">architecture</a>), which determines the events that will be logged and those that won’t.</p>
+<a href="architecture.html#LoggerConfig" class="xref page">architecture</a>), which determines the events that will be logged and those that won’t.</p>
</div>
<div class="paragraph">
<p>Let’s start with an example of logger configuration:</p>
@@ -1517,7 +1518,7 @@ will be printed, and which appenders will be used.
The table below summarizes the effects of each logger configuration:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 1. Logger configurations</caption>
+<caption class="title">Table 2. Logger configurations</caption>
<colgroup>
<col style="width: 7.1428%;">
<col style="width: 14.2857%;">
@@ -2806,56 +2807,68 @@ appender.0.select.1.layout.type = JsonTemplateLayout</code></pre>
</div>
</div>
<div class="sect1">
-<h2 id="CompositeConfiguration"><a class="anchor" href="#CompositeConfiguration"></a>Composite Configuration</h2>
+<h2 id="CompositeConfiguration"><a class="anchor" href="#CompositeConfiguration"></a>Composite configuration</h2>
<div class="sectionbody">
<div class="paragraph">
-<p>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
-<a href="systemproperties.html#log4j2.configurationFile" class="xref page"><code>log4j2.configurationFile</code></a>
-configuration property.</p>
+<p>There are occasions where multiple configurations might need to be combined.
+For instance,</p>
</div>
-<div class="paragraph">
-<p>These configuration files are merged into a single configuration file using
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy.html"><code>MergeStrategy</code></a>
-service that can be customized using the
-<a href="systemproperties.html#log4j2.mergeStrategy" class="xref page"><code>log4j2.mergeStrategy</code></a>
-configuration property.</p>
+<div class="ulist">
+<ul>
+<li>
+<p>You have a common Log4j Core configuration that should always be present, and an environment-specific one that extends the common one depending on the environment (test, production, etc.) the application is running on.</p>
+</li>
+<li>
+<p>You develop a framework, and it contains a predefined Log4j Core configuration.
+Yet you want to allow users to extend it whenever necessary.</p>
+</li>
+<li>
+<p>You collect Log4j Core configurations from multiple sources.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>The default merge strategy will merge the files using the following rules:</p>
+<p>You can provide a list of comma-separated file paths or URLs in <a href="systemproperties.html#log4j2.configurationFile" class="xref page">the <code>log4j2.configurationFile</code> configuration property</a>, where each resource will get read into a <code>Configuration</code>, and then eventually combined into a single one using <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/CompositeConfiguration.html"><code>CompositeConfiguration</code></a>.</p>
</div>
-<div class="olist arabic">
-<ol class="arabic">
-<li>
-<p><a href="#global-configuration-attributes">Global configuration attributes</a> in later configurations replace those in previous configurations.</p>
+<details>
+<summary class="title">How does <code>CompositeConfiguration</code> work?</summary>
+<div class="content">
<div class="paragraph">
-<p>The exception is the <code>monitorInterval</code> attribute: the lowest positive value from all the configuration files will be used.</p>
+<p><code>CompositeConfiguration</code> merges multiple configurations into a single one using a <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy.html"><code>MergeStrategy</code></a>, which can be customized using <a href="systemproperties.html#log4j2.mergeStrategy" class="xref page">the <code>log4j2.mergeStrategy</code> configuration property</a>.
+The default merge strategy works as follows:</p>
</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="#global-configuration-attributes">Global configuration attributes</a> in later configurations replace those in previous configurations.
+The only exception is the <code>monitorInterval</code> attribute: the lowest positive value from all the configuration files will be used.</p>
</li>
<li>
-<p><a href="#property-substitution">Properties</a> from all configurations are aggregated.
-Duplicate properties replace those in previous configurations.</p>
+<p><a href="#property-substitution">Properties</a> are aggregated.
+Duplicate properties override those in previous configurations.</p>
</li>
<li>
-<p><a href="filters.html" class="xref page">Filters</a> are aggregated under
-<a href="filters.html#CompositeFilter" class="xref page">CompositeFilter</a>, if more than one filter is defined.</p>
+<p><a href="filters.html" class="xref page">Filters</a> are aggregated under <a href="filters.html#CompositeFilter" class="xref page"><code>CompositeFilter</code></a>, if more than one filter is defined.</p>
</li>
<li>
<p><a href="scripts.html" class="xref page">Scripts</a> are aggregated.
-Duplicate definitions replace those in previous configurations.</p>
+Duplicate definitions override those in previous configurations.</p>
</li>
<li>
<p><a href="appenders.html" class="xref page">Appenders</a> are aggregated.
-Appenders with the same name are <strong>replaced</strong> by those in later configurations, including all their elements.</p>
+Appenders with the same name are <strong>overridden</strong> by those in later configurations, including all their elements.</p>
</li>
<li>
-<p><a href="#configuring-loggers">Loggers</a> are all aggregated.
+<p><a href="#configuring-loggers">Loggers</a> are 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.</p>
</li>
-</ol>
+</ul>
</div>
</div>
+</details>
+</div>
</div>
<div class="sect1">
<h2 id="format-specific-notes"><a class="anchor" href="#format-specific-notes"></a>Format specific notes</h2>
@@ -3084,6 +3097,76 @@ rootLogger.appenderRef.0.ref = APPENDER</code></pre>
</div>
</div>
</div>
+<div class="sect1">
+<h2 id="extending"><a class="anchor" href="#extending"></a>Extending</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Log4j Core uses <a href="plugins.html" class="xref page">plugins</a> to inject necessary components while reading a configuration file.
+In this section, we will explore extension points users can hook into to customize the way Log4j Core reads configuration files.</p>
+</div>
+<div class="sect2">
+<h3 id="extending-plugins"><a class="anchor" href="#extending-plugins"></a>Plugin preliminaries</h3>
+<div class="paragraph">
+<p>Log4j plugin system is the de facto extension mechanism embraced by various Log4j components.
+Plugins provide extension points to components, that can be used to implement new features, without modifying the original component.
+It is analogous to a <a href="https://en.wikipedia.org/wiki/Dependency_injection">dependency injection</a> framework, but curated for Log4j-specific needs.</p>
+</div>
+<div class="paragraph">
+<p>In a nutshell, you annotate your classes with <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/Plugin.html"><code>@Plugin</code></a> and their (<code>static</code>) factory methods with <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginFactory.html"><code>@PluginFactory</code></a>.
+Last, you inform the Log4j plugin system to discover these custom classes.
+This is done using running the <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/processor/PluginProcessor.html"><code>PluginProcessor</code></a> annotation processor while building your project.
+Refer to <a href="plugins.html" class="xref page">Plugins</a> for details.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="ConfigurationFactory"><a class="anchor" href="#ConfigurationFactory"></a>Extending <code>ConfigurationFactory</code> plugins</h3>
+<div class="paragraph">
+<p>Under the hood, Log4j Core uses plugins extending from <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory.html"><code>ConfigurationFactory</code></a> to load configuration files.
+This procedure can be summarized as follows:</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>Load plugins which extend from <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory.html"><code>ConfigurationFactory</code></a> and whose plugin <code>category</code> is set to <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory.html#CATEGORY"><code>ConfigurationFactory.CATEGORY</code></a></p>
+</li>
+<li>
+<p>Sort them by <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Order.html"><code>@Order</code></a> annotation (in decreasing value order), if present</p>
+</li>
+<li>
+<p>Feed <a href="#automatic-configuration">found configuration files</a> to <code>ConfigurationFactory</code> instances in order, if the file extension is contained by <code>String[]</code> returned from <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory.html#getSupportedTypes()"><code>ConfigurationFactory#getSupportedTypes()</code></a></p>
+</li>
+</ol>
+</div>
+<div class="paragraph">
+<p>If <a href="systemproperties.html#log4j2.configurationFactory" class="xref page">the <code>log4j2.configurationFactory</code> system property</a> is defined, it will be used before any other factory implementations.</p>
+</div>
+<div class="paragraph">
+<p>For an example, see <a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core/src/main/java/org/apache/logging/log4j/core/config/json/JsonConfigurationFactory.java"><code>JsonConfigurationFactory.java</code></a> on how Log4j Core implements JSON-formatted configuration file read.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Next to introducing new configuration file formats, <code>ConfigurationFactory</code> can be used for <a href="customconfig.html" class="xref page">programmatic configuration</a> too.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect2">
+<h3 id="extending-config-file-plugins"><a class="anchor" href="#extending-config-file-plugins"></a>Plugins represented in a configuration file</h3>
+<div class="paragraph">
+<p>As explained in <a href="#configuration-syntax"> Syntax</a>, a configuration file gets parsed into a tree of plugins.
+If your plugin needs to be represented in a configuration file element, some <a href="plugins.html#core" class="xref page">extra plugin configuration</a> needs to be administered.</p>
+</div>
+</div>
+</div>
+</div>
</article>
</div>
</main>
diff --git a/manual/customconfig.html b/manual/customconfig.html
index bc2c682b02..4e171490a6 100644
--- a/manual/customconfig.html
+++ b/manual/customconfig.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
- <title>Programmatic Configuration :: Apache Log4j</title>
+ <title>Programmatic configuration :: Apache Log4j</title>
<link rel="canonical" href="https://logging.apache.org/log4j/2.x/manual/customconfig.html">
<meta name="generator" content="Antora 3.2.0-alpha.4">
<link rel="stylesheet" href="../_/css/site.css">
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item is-current-page" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -317,7 +317,7 @@
<li><a href="../index.html">Home</a></li>
<li><a href="index.html">Manual</a></li>
<li><a href="config-intro.html">Configuration</a></li>
- <li><a href="customconfig.html">Programmatic Configuration</a></li>
+ <li><a href="customconfig.html">Programmatic configuration</a></li>
</ul>
</nav>
<div class="edit-this-page"><a href="https://github.com/apache/logging-log4j2/edit/2.x/src/site/antora/modules/ROOT/pages/manual/customconfig.adoc">Edit this Page</a></div>
@@ -327,439 +327,525 @@
<div class="toc-menu"></div>
</aside>
<article class="doc">
-<h1 class="page">Programmatic Configuration</h1>
+<h1 class="page">Programmatic configuration</h1>
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
-<p>Log4j 2 provides a few ways for applications to create their own
-programmatic configuration:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Specify a custom <code>ConfigurationFactory</code> to start Log4j with a
-programmatic configuration</p>
-</li>
-<li>
-<p>Use the <code>Configurator</code> to replace the configuration after Log4j started</p>
-</li>
-<li>
-<p>Initialize Log4j with a combination of a configuration file and
-programmatic configuration</p>
-</li>
-<li>
-<p>Modify the current <code>Configuration</code> after initialization</p>
-</li>
-</ul>
+<p>Next to <a href="configuration.html" class="xref page">configuration files</a>, Log4j Core can be configured programmatically too.
+In this page, we will explore utilities helping with programmatic configuration and demonstrate how they can be leveraged for certain use cases.</p>
</div>
</div>
</div>
<div class="sect1">
-<h2 id="ConfigurationBuilder"><a class="anchor" href="#ConfigurationBuilder"></a>The ConfigurationBuilder API</h2>
+<h2 id="prelim"><a class="anchor" href="#prelim"></a>Preliminaries</h2>
<div class="sectionbody">
<div class="paragraph">
-<p>Starting with release 2.4, Log4j provides a <code>ConfigurationBuilder</code> and a
-set of component builders that allow a <code>Configuration</code> to be created
-fairly easily. Actual configuration objects like <code>LoggerConfig</code> or
-<code>Appender</code> can be unwieldy; they require a lot of knowledge about Log4j
-internals which makes them difficult to work with if all you want is to
-create a <code>Configuration</code>.</p>
+<p>To begin with, we strongly encourage you to check out the <a href="architecture.html" class="xref page">Architecture</a> page first.
+Let’s repeat some basic definitions of particular interest:</p>
</div>
-<div class="paragraph">
-<p>The new <code>ConfigurationBuilder</code> API (in the
-<code>org.apache.logging.log4j.core.config.builder.api</code> package) allows users
-to create Configurations in code by constructing component
-<em>definitions</em>. There is no need to work directly with actual
-configuration objects. Component definitions are added to the
-<code>ConfigurationBuilder</code>, and once all the definitions have been collected
-all the actual configuration objects (like Loggers and Appenders) are
-constructed.</p>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><a href="architecture.html#LoggerContext" class="xref page"><code>LoggerContext</code></a></dt>
+<dd>
+<p>It is the anchor of the logging system.
+Generally there is one, statically-accessible, global <code>LoggerContext</code> for most applications.
+But there can be multiple <code>LoggerContext</code>s, for instance, to use in tests, in Java EE web applications, etc.</p>
+</dd>
+<dt class="hdlist1"><a href="architecture.html#Configuration" class="xref page"><code>Configuration</code></a></dt>
+<dd>
+<p>It encapsulates a Log4j Core configuration (properties, appenders, loggers, etc.) and is associated with a <code>LoggerContext</code>.</p>
+</dd>
+</dl>
</div>
-<div class="paragraph">
-<p><code>ConfigurationBuilder</code> has convenience methods for the base components
-that can be configured such as Loggers, Appenders, Filter, Properties,
-etc. However, Log4j 2’s plugin mechanism means that users can create any
-number of custom components. As a trade-off, the <code>ConfigurationBuilder</code>
-API provides only a limited number of "strongly typed" convenience
-methods like <code>newLogger()</code>, <code>newLayout()</code> etc. The generic
-<code>builder.newComponent()</code> method can be used if no convenience method
-exists for the component you want to configure.</p>
</div>
-<div class="paragraph">
-<p>For example, the builder does not know what sub-components can be
-configured on specific components such as the RollingFileAppender vs.
-the RoutingAppender. To specify a triggering policy on a
-RollingFileAppender you would use builder.newComponent().</p>
</div>
+<div class="sect1">
+<h2 id="tooling"><a class="anchor" href="#tooling"></a>Tooling</h2>
+<div class="sectionbody">
<div class="paragraph">
-<p>Examples of using the <code>ConfigurationBuilder</code> API are in the sections that
-follow.</p>
+<p>For programmatic configuration, Log4j Core essentially provides the following tooling:</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><a href="#ConfigurationBuilder"><code>ConfigurationBuilder</code></a></dt>
+<dd>
+<p>for declaratively creating a <code>Configuration</code></p>
+</dd>
+<dt class="hdlist1"><a href="#Configurator"><code>Configurator</code></a></dt>
+<dd>
+<p>for associating a <code>Configuration</code> with a <code>LoggerContext</code></p>
+</dd>
+<dt class="hdlist1"><a href="#ConfigurationFactory"> <code>ConfigurationFactory</code></a></dt>
+<dd>
+<p>for registering a <code>Configuration</code> factory to <a href="configuration.html" class="xref page">the configuration file mechanism</a></p>
+</dd>
+</dl>
</div>
+<div class="paragraph">
+<p>In short, we will create <code>Configuration</code>s using <code>ConfigurationBuilder</code>, and activate them using <code>Configurator</code>.</p>
</div>
+<div class="sect2">
+<h3 id="ConfigurationBuilder"><a class="anchor" href="#ConfigurationBuilder"></a><code>ConfigurationBuilder</code></h3>
+<div class="paragraph">
+<p><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html"><code>ConfigurationBuilder</code></a> interface models a fluent API to programmatically create <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html"><code>Configuration</code></a>s.
+If you have ever created a <a href="configuration.html" class="xref page">Log4j Core configuration file</a>, consider <code>ConfigurationBuilder</code> as a convenience utility to model the very same declarative configuration structure programmatically.</p>
</div>
-<div class="sect1">
-<h2 id="ConfigurationFactory"><a class="anchor" href="#ConfigurationFactory"></a>Understanding ConfigurationFactory</h2>
-<div class="sectionbody">
<div class="paragraph">
-<p>During initialization, Log4j 2 will search for available
-<a href="extending.html#ConfigurationFactory" class="xref page">ConfigurationFactories</a> and
-then select the one to use. The selected <code>ConfigurationFactory</code> creates
-the <code>Configuration</code> that Log4j will use. Here is how Log4j finds the
-available ConfigurationFactories:</p>
-</div>
-<div class="olist arabic">
-<ol class="arabic">
-<li>
-<p>A system property named <code>log4j2.configurationFactory</code> can be set
-with the name of the ConfigurationFactory to be used.</p>
+<p>Let’s show <code>ConfigurationBuilder</code> usage with an example.
+Consider the following Log4j Core configuration file:</p>
+</div>
+<div id="_tabs_1" class="openblock tabs is-sync is-loading">
+<div class="content">
+<div class="ulist tablist">
+<ul>
+<li id="_tabs_1_xml" class="tab">
+<p>XML</p>
</li>
-<li>
-<p><code>ConfigurationFactory.setConfigurationFactory(ConfigurationFactory)</code>
-can be called with the instance of the <code>ConfigurationFactory</code> to be used.
-This must be called before any other calls to Log4j.</p>
+<li id="_tabs_1_json" class="tab">
+<p>JSON</p>
</li>
-<li>
-<p>A <code>ConfigurationFactory</code> implementation can be added to the classpath
-and configured as a plugin in the "ConfigurationFactory" category. The
-<code>@Order</code> annotation can be used to specify the relative priority when
-multiple applicable ConfigurationFactories are found.</p>
+<li id="_tabs_1_yaml" class="tab">
+<p>YAML</p>
</li>
-</ol>
-</div>
-<div class="paragraph">
-<p>ConfigurationFactories have the concept of "supported types", which
-basically maps to the file extension of the configuration file that the
-ConfigurationFactory can handle. If a configuration file location is
-specified, ConfigurationFactories whose supported type does not include
-"*" or the matching file extension will not be used.</p>
+<li id="_tabs_1_properties" class="tab">
+<p>Properties</p>
+</li>
+</ul>
</div>
+<div id="_tabs_1_xml--panel" class="tabpanel" aria-labelledby="_tabs_1_xml">
+<div class="listingblock">
+<div class="title">Snippet from an example <a href="https://github.com/apache/logging-log4j2/tree/2.x/src/site/antora/modules/ROOT/examples/manual/customconfig/ConfigurationBuilder/log4j2.xml"><code>log4j2.xml</code></a></div>
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><Appenders>
+ <Console name="CONSOLE">
+ <JsonTemplateLayout/>
+ </Console>
+</Appenders>
+
+<Loggers>
+ <Root level="WARN">
+ <AppenderRef ref="CONSOLE"/>
+ </Root>
+</Loggers></code></pre>
</div>
</div>
-<div class="sect1">
-<h2 id="Example"><a class="anchor" href="#Example"></a>Initialize Log4j Using ConfigurationBuilder with a Custom ConfigurationFactory</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>One way to programmatically configure Log4j 2 is to create a custom
-<code>ConfigurationFactory</code> that uses the
-<a href="#ConfigurationBuilder"><code>ConfigurationBuilder</code></a> to create a
-Configuration. The below example overrides the <code>getConfiguration()</code>
-method to return a <code>Configuration</code> created by the <code>ConfigurationBuilder</code>.
-This will cause the <code>Configuration</code> to automatically be hooked into Log4j
-when the <code>LoggerContext</code> is created. In the example below, because it
-specifies a supported type of "*" it will override any configuration
-files provided.</p>
</div>
+<div id="_tabs_1_json--panel" class="tabpanel" aria-labelledby="_tabs_1_json">
<div class="listingblock">
+<div class="title">Snippet from an example <a href="https://github.com/apache/logging-log4j2/tree/2.x/src/site/antora/modules/ROOT/examples/manual/customconfig/ConfigurationBuilder/log4j2.json"><code>log4j2.json</code></a></div>
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Namespace(ConfigurationFactory.NAMESPACE)
-@Plugin
-@Order(50)
-public class CustomConfigurationFactory extends ConfigurationFactory {
-
- static Configuration createConfiguration(final String name, ConfigurationBuilder<BuiltConfiguration> builder) {
- builder.setConfigurationName(name);
- builder.setStatusLevel(Level.ERROR);
- builder.add(builder.newFilter("ThresholdFilter", Filter.Result.ACCEPT, Filter.Result.NEUTRAL).
- addAttribute("level", Level.DEBUG));
- AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE").
- addAttribute("target", ConsoleAppender.Target.SYSTEM_OUT);
- appenderBuilder.add(builder.newLayout("PatternLayout").
- addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable"));
- appenderBuilder.add(builder.newFilter("MarkerFilter", Filter.Result.DENY,
- Filter.Result.NEUTRAL).addAttribute("marker", "FLOW"));
- builder.add(appenderBuilder);
- builder.add(builder.newLogger("org.apache.logging.log4j", Level.DEBUG).
- add(builder.newAppenderRef("Stdout")).
- addAttribute("additivity", false));
- builder.add(builder.newRootLogger(Level.ERROR).add(builder.newAppenderRef("Stdout")));
- return builder.build();
- }
-
- @Override
- public Configuration getConfiguration(final LoggerContext loggerContext, final ConfigurationSource source) {
- return getConfiguration(loggerContext, source.toString(), null);
+<pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">"Appenders": {
+ "Console": {
+ "name": "CONSOLE",
+ "JsonTemplateLayout": {}
+ }
+},
+"Loggers": {
+ "Root": {
+ "level": "WARN",
+ "AppenderRef": {
+ "ref": "CONSOLE"
}
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+<div id="_tabs_1_yaml--panel" class="tabpanel" aria-labelledby="_tabs_1_yaml">
+<div class="listingblock">
+<div class="title">Snippet from an example <a href="https://github.com/apache/logging-log4j2/tree/2.x/src/site/antora/modules/ROOT/examples/manual/customconfig/ConfigurationBuilder/log4j2.yaml"><code>log4j2.yaml</code></a></div>
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">Appenders:
+ Console:
+ name: "CONSOLE"
+ JsonTemplateLayout: {}
- @Override
- public Configuration getConfiguration(final LoggerContext loggerContext, final String name, final URI configLocation) {
- ConfigurationBuilder<BuiltConfiguration> builder = newConfigurationBuilder();
- return createConfiguration(name, builder);
- }
+Loggers:
+ Root:
+ level: "WARN"
+ AppenderRef:
+ ref: "CONSOLE"</code></pre>
+</div>
+</div>
+</div>
+<div id="_tabs_1_properties--panel" class="tabpanel" aria-labelledby="_tabs_1_properties">
+<div class="listingblock">
+<div class="title">Snippet from an example <a href="https://github.com/apache/logging-log4j2/tree/2.x/src/site/antora/modules/ROOT/examples/manual/customconfig/ConfigurationBuilder/log4j2.properties"><code>log4j2.properties</code></a></div>
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties">appender.0.type = Console
+appender.0.name = CONSOLE
+appender.0.layout.type = JsonTemplateLayout
- @Override
- protected String[] getSupportedTypes() {
- return new String[] {"*"};
- }
-}</code></pre>
+rootLogger.level = WARN
+rootLogger.appenderRef.0.ref = CONSOLE</code></pre>
+</div>
+</div>
+</div>
</div>
</div>
<div class="paragraph">
-<p>As of version 2.7, the <code>ConfigurationFactory.getConfiguration()</code> methods
-take an additional <code>LoggerContext</code> parameter.</p>
+<p>Above Log4j Core configuration can be programmatically built using <code>ConfigurationBuilder</code> as follows:</p>
</div>
+<div class="listingblock">
+<div class="title">Snippet from an example <a href="https://github.com/apache/logging-log4j2/tree/2.x/src/site/antora/modules/ROOT/examples/manual/customconfig/Usage.java"><code>Usage.java</code></a></div>
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">ConfigurationBuilder<BuiltConfiguration> configBuilder =
+ ConfigurationBuilderFactory.newConfigurationBuilder(); <i class="conum" data-value="1"></i><b>(1)</b>
+Configuration configuration = configBuilder
+ .add(
+ configBuilder <i class="conum" data-value="2"></i><b>(2)</b>
+ .newAppender("CONSOLE", "List")
+ .add(configBuilder.newLayout("JsonTemplateLayout")))
+ .add(
+ configBuilder <i class="conum" data-value="3"></i><b>(3)</b>
+ .newRootLogger(Level.WARN)
+ .add(configBuilder.newAppenderRef("CONSOLE")))
+ .build(false); <i class="conum" data-value="4"></i><b>(4)</b></code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>The default <code>ConfigurationBuilder</code> instance is obtained using <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilderFactory.html#newConfigurationBuilder()"><code>ConfigurationBuilderFactory.newConfigurationBuilder()</code></a> static method</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>Add the appender along with the layout</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="3"></i><b>3</b></td>
+<td>Add the root logger along with a level and appender reference</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="4"></i><b>4</b></td>
+<td>Create the configuration, but <strong>don’t initialize</strong> it
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>It is a good practice to not initialize <code>Configuration</code>s when they are constructed.
+This task should ideally be delegated to <a href="#Configurator"><code>Configurator</code></a>.</p>
</div>
+</td>
+</tr>
+</table>
+</div></td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p><code>ConfigurationBuilder</code> has convenience methods for the base components that can be configured such as loggers, appenders, filters, properties, etc.
+Though there are cases where the provided convenience methods fall short of:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Custom <a href="plugins.html#core" class="xref page">plugins that are declared to be represented in a configuration</a></p>
+</li>
+<li>
+<p>Custom subcomponents (e.g., a <a href="appenders.html#TriggeringPolicies" class="xref page">triggering policy</a> for <a href="appenders.html#RollingFileAppender" class="xref page"><code>RollingFileAppender</code></a>)</p>
+</li>
+</ul>
</div>
-<div class="sect1">
-<h2 id="Configurator"><a class="anchor" href="#Configurator"></a>Reconfigure Log4j Using ConfigurationBuilder with the Configurator</h2>
-<div class="sectionbody">
<div class="paragraph">
-<p>An alternative to a custom <code>ConfigurationFactory</code> is to configure with the
-<code>Configurator</code>. Once a <code>Configuration</code> object has been constructed, it can
-be passed to one of the <code>Configurator.initialize</code> methods to set up the
-Log4j configuration.</p>
+<p>For those, you can use the generic <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/builder/api/ConfigurationBuilder.html#newComponent()"><code>ConfigurationBuilder#newComponent()</code></a> method.</p>
</div>
<div class="paragraph">
-<p>Using the <code>Configurator</code> in this manner allows the application control
-over when Log4j is initialized. However, should any logging be attempted
-before <code>Configurator.initialize()</code> is called then the default
-configuration will be used for those log events.</p>
+<p>See <a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core-test/src/test/java/org/apache/logging/log4j/core/config/Configurator1Test.java"><code>Configurator1Test.java</code></a> for examples on <code>ConfigurationBuilder</code>, <code>newComponent()</code>, etc. usage.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="Configurator"><a class="anchor" href="#Configurator"></a><code>Configurator</code></h3>
+<div class="paragraph">
+<p><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configurator.html"><code>Configurator</code></a> is a programmatic interface to associate a <code>Configuration</code> with either new, or an existing <code>LoggerContext</code>.</p>
+</div>
+<div class="sect3">
+<h4 id="Configurator-initialize"><a class="anchor" href="#Configurator-initialize"></a>Obtaining a <code>LoggerContext</code></h4>
+<div class="paragraph">
+<p>You can use <code>Configurator</code> to obtain a <code>LoggerContext</code>:</p>
</div>
<div class="listingblock">
+<div class="title">Snippet from an example <a href="https://github.com/apache/logging-log4j2/tree/2.x/src/site/antora/modules/ROOT/examples/manual/customconfig/Usage.java"><code>Usage.java</code></a></div>
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">ConfigurationBuilder<BuiltConfiguration> builder = ConfigurationBuilderFactory.newConfigurationBuilder();
-builder.setStatusLevel(Level.ERROR);
-builder.setConfigurationName("BuilderTest");
-builder.add(builder.newFilter("ThresholdFilter", Filter.Result.ACCEPT, Filter.Result.NEUTRAL)
- .addAttribute("level", Level.DEBUG));
-AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE").addAttribute("target",
- ConsoleAppender.Target.SYSTEM_OUT);
-appenderBuilder.add(builder.newLayout("PatternLayout")
- .addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable"));
-appenderBuilder.add(builder.newFilter("MarkerFilter", Filter.Result.DENY, Filter.Result.NEUTRAL)
- .addAttribute("marker", "FLOW"));
-builder.add(appenderBuilder);
-builder.add(builder.newLogger("org.apache.logging.log4j", Level.DEBUG)
- .add(builder.newAppenderRef("Stdout")).addAttribute("additivity", false));
-builder.add(builder.newRootLogger(Level.ERROR).add(builder.newAppenderRef("Stdout")));
-ctx = Configurator.initialize(builder.build());</code></pre>
+<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Configuration configuration = createConfiguration();
+try (LoggerContext loggerContext = Configurator.initialize(configuration)) {
+ // Use `LoggerContext`...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p><code>initialize()</code> will either return the <code>LoggerContext</code> currently associated with the caller, or create a new one.
+This is a convenient way to create isolated <code>LoggerContext</code>s for tests, etc.</p>
</div>
</div>
+<div class="sect3">
+<h4 id="Configurator-reconfigure"><a class="anchor" href="#Configurator-reconfigure"></a>Reconfiguring the active <code>LoggerContext</code></h4>
<div class="paragraph">
-<p>This example shows how to create a configuration that includes a
-RollingFileAppender.</p>
+<p>You can use <code>Configurator</code> to reconfigure the active <code>LoggerContext</code> as follows:</p>
</div>
<div class="listingblock">
+<div class="title">Snippet from an example <a href="https://github.com/apache/logging-log4j2/tree/2.x/src/site/antora/modules/ROOT/examples/manual/customconfig/Usage.java"><code>Usage.java</code></a></div>
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">ConfigurationBuilder<BuiltConfiguration> builder = ConfigurationBuilderFactory.newConfigurationBuilder();
-
-builder.setStatusLevel(Level.ERROR);
-builder.setConfigurationName("RollingBuilder");
-// create a console appender
-AppenderComponentBuilder appenderBuilder = builder.newAppender("Stdout", "CONSOLE").addAttribute("target",
- ConsoleAppender.Target.SYSTEM_OUT);
-appenderBuilder.add(builder.newLayout("PatternLayout")
- .addAttribute("pattern", "%d [%t] %-5level: %msg%n%throwable"));
-builder.add(appenderBuilder);
-// create a rolling file appender
-LayoutComponentBuilder layoutBuilder = builder.newLayout("PatternLayout")
- .addAttribute("pattern", "%d [%t] %-5level: %msg%n");
-ComponentBuilder triggeringPolicy = builder.newComponent("Policies")
- .addComponent(builder.newComponent("CronTriggeringPolicy").addAttribute("schedule", "0 0 0 * * ?"))
- .addComponent(builder.newComponent("SizeBasedTriggeringPolicy").addAttribute("size", "100M"));
-appenderBuilder = builder.newAppender("rolling", "RollingFile")
- .addAttribute("fileName", "target/rolling.log")
- .addAttribute("filePattern", "target/archive/rolling-%d{MM-dd-yy}.log.gz")
- .add(layoutBuilder)
- .addComponent(triggeringPolicy);
-builder.add(appenderBuilder);
-
-// create the new logger
-builder.add(builder.newLogger("TestLogger", Level.DEBUG)
- .add(builder.newAppenderRef("rolling"))
- .addAttribute("additivity", false));
-
-builder.add(builder.newRootLogger(Level.DEBUG)
- .add(builder.newAppenderRef("rolling")));
-LoggerContext ctx = Configurator.initialize(builder.build());</code></pre>
+<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Configuration configuration = createConfiguration();
+Configurator.reconfigure(configuration);</code></pre>
</div>
</div>
+<div class="paragraph">
+<p>Using the <code>Configurator</code> in this manner allows the application control over when Log4j is initialized.
+However, should any logging be attempted before <code>Configurator.initialize()</code> is called then the default configuration will be used for those log events.</p>
</div>
</div>
-<div class="sect1">
-<h2 id="Hybrid"><a class="anchor" href="#Hybrid"></a>Initialize Log4j by Combining Configuration File with Programmatic Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>Sometimes you want to configure with a configuration file but do some
-additional programmatic configuration. A possible use case might be that
-you want to allow for a flexible configuration using XML but at the same
-time make sure there are a few configuration elements that are always
-present that can’t be removed.</p>
</div>
+<div class="sect2">
+<h3 id="ConfigurationFactory"><a class="anchor" href="#ConfigurationFactory"></a><a id="Example"></a> <code>ConfigurationFactory</code></h3>
<div class="paragraph">
-<p>The easiest way to achieve this is to extend one of the standard
-<code>Configuration</code> classes (<code>XMLConfiguration</code>, <code>JSONConfiguration</code>) and then
-create a new <code>ConfigurationFactory</code> for the extended class. After the
-standard configuration completes the custom configuration can be added
-to it.</p>
+<p><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory.html"><code>ConfigurationFactory</code></a> interface, which is mainly used by <a href="configuration.html#automatic-configuration" class="xref page">the configuration file mechanism</a> to load a <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html"><code>Configuration</code></a>, can be leveraged to inject a custom <code>Configuration</code>.
+You need to</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="configuration.html#ConfigurationFactory" class="xref page">Create a custom <code>ConfigurationFactory</code> plugin</a></p>
+</li>
+<li>
+<p>Assign it a higher priority (i.e., higher <code>@Order</code> value)</p>
+</li>
+<li>
+<p>Support all configuration file types (i.e. return <code>*</code> from <code>getSupportedTypes()</code>)</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>The example below shows how to extend <code>XMLConfiguration</code> to manually add
-an <code>Appender</code> and a <code>LoggerConfig</code> to the configuration.</p>
+<p>Consider the example below:</p>
</div>
<div class="listingblock">
+<div class="title">Snippet from an example <a href="https://github.com/apache/logging-log4j2/tree/2.x/src/site/antora/modules/ROOT/examples/manual/customconfig/ExampleConfigurationFactory.java"><code>ExampleConfigurationFactory.java</code></a></div>
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Namespace("ConfigurationFactory")
-@Plugin("MyXMLConfigurationFactory")
-@Order(10)
-public class MyXMLConfigurationFactory extends ConfigurationFactory {
-
- /**
- * Valid file extensions for XML files.
- */
- public static final String[] SUFFIXES = new String[] {".xml", "*"};
+<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Order(100)
+@Plugin(name = "ExampleConfigurationFactory", category = ConfigurationFactory.CATEGORY)
+public class ExampleConfigurationFactory extends ConfigurationFactory {
- /**
- * Return the Configuration.
- * @param source The InputSource.
- * @return The Configuration.
- */
- public Configuration getConfiguration(InputSource source) {
- return new MyXMLConfiguration(source, configFile);
- }
-
- /**
- * Returns the file suffixes for XML files.
- * @return An array of File extensions.
- */
- public String[] getSupportedTypes() {
- return SUFFIXES;
+ @Override
+ public Configuration getConfiguration(LoggerContext loggerContext, ConfigurationSource source) { <i class="conum" data-value="1"></i><b>(1)</b>
+ // Return a `Configuration`...
}
-}
-public class MyXMLConfiguration extends XMLConfiguration {
- public MyXMLConfiguration(final ConfigurationFactory.ConfigurationSource configSource) {
- super(configSource);
+ @Override
+ public Configuration getConfiguration(LoggerContext loggerContext, String name, URI configLocation) {
+ // Return a `Configuration`...
}
@Override
- protected void doConfigure() {
- super.doConfigure();
- final LoggerContext ctx = (LoggerContext) LogManager.getContext(false);
- final Layout layout = PatternLayout.createDefaultLayout(config);
- final Appender appender = FileAppender.createAppender("target/test.log", "false", "false", "File", "true",
- "false", "false", "4000", layout, null, "false", null, config);
- appender.start();
- addAppender(appender);
- LoggerConfig loggerConfig = LoggerConfig.createLogger("false", "info", "org.apache.logging.log4j",
- "true", refs, null, config, null );
- loggerConfig.addAppender(appender, null, null);
- addLogger("org.apache.logging.log4j", loggerConfig);
+ public String[] getSupportedTypes() {
+ return new String[] {"*"};
}
}</code></pre>
</div>
</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td><code>getConfiguration(LoggerContext, ConfigurationSource)</code> is only called if <code>ConfigurationSource</code> is not null.
+This is possible if the <code>Configuration</code> is provided programmatically.
+Hence, you are encouraged to implement <code>getConfiguration(LoggerContext, String, URI)</code> overload too.</td>
+</tr>
+</table>
+</div>
+</div>
</div>
</div>
<div class="sect1">
-<h2 id="AddingToCurrent"><a class="anchor" href="#AddingToCurrent"></a>Programmatically Modifying the Current Configuration after Initialization</h2>
+<h2 id="guides"><a class="anchor" href="#guides"></a>How-to guides</h2>
<div class="sectionbody">
<div class="paragraph">
-<p>Applications sometimes have the need to customize logging separate from
-the actual configuration. Log4j allows this although it suffers from a
-few limitations:</p>
+<p>In this section we will share guides on programmatically configuring Log4j Core for certain use cases.</p>
+</div>
+<div class="sect2">
+<h3 id="load-config-file"><a class="anchor" href="#load-config-file"></a>Loading a configuration file</h3>
+<div class="paragraph">
+<p><a href="#ConfigurationFactory"> <code>ConfigurationFactory</code></a> provides the <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory.html#getInstance()"><code>getInstance()</code></a> method returning a meta-<code>ConfigurationFactory</code> that combines the behaviour of all available <code>ConfigurationFactory</code> implementations, including <a href="configuration.html#configuration-factories" class="xref page">the predefined ones</a>; <code [...]
+You can use this <code>getInstance()</code> method to load a configuration file programmatically, granted that the input file format is supported by at least one of the available <code>ConfigurationFactory</code> plugins:</p>
+</div>
+<div class="listingblock">
+<div class="title">Snippet from an example <a href="https://github.com/apache/logging-log4j2/tree/2.x/src/site/antora/modules/ROOT/examples/manual/customconfig/Usage.java"><code>Usage.java</code></a></div>
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">ConfigurationFactory.getInstance()
+ .getConfiguration(
+ null, <i class="conum" data-value="1"></i><b>(1)</b>
+ null, <i class="conum" data-value="2"></i><b>(2)</b>
+ URI.create("uri://to/my/log4j2.xml")); <i class="conum" data-value="3"></i><b>(3)</b></code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>Passing the <code>LoggerContext</code> argument as null, since this is the first time we are instantiating this <code>Configuration</code>, and it is not associated with a <code>LoggerContext</code> yet</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>Passing the configuration name argument as null, since it is not used when the configuration source location is provided</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="3"></i><b>3</b></td>
+<td>URI pointing to the configuration file; <code><a href="file://path/to/log4j2.xml" class="bare">file://path/to/log4j2.xml</a></code>, <code>classpath:log4j2.xml</code>, etc.</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect2">
+<h3 id="CompositeConfiguration"><a class="anchor" href="#CompositeConfiguration"></a>Combining multiple configurations</h3>
+<div class="paragraph">
+<p>There are occasions where multiple configurations might need to be combined.
+For instance,</p>
</div>
-<div class="olist arabic">
-<ol class="arabic">
+<div class="ulist">
+<ul>
<li>
-<p>If the configuration file is changed the configuration will be
-reloaded and the manual changes will be lost.</p>
+<p>You have a common Log4j Core configuration that should always be present, and an environment-specific one that extends the common one depending on the environment (test, production, etc.) the application is running on.</p>
</li>
<li>
-<p>Modification to the running configuration requires that all the
-methods being called (addAppender and addLogger) be synchronized.</p>
+<p>You develop a framework, and it contains a predefined Log4j Core configuration.
+Yet you want to allow users to extend it whenever necessary.</p>
</li>
-</ol>
-</div>
-<div class="paragraph">
-<p>As such, the recommended approach for customizing a configuration is to
-extend one of the standard Configuration classes, override the setup
-method to first do super.setup() and then add the custom Appenders,
-Filters and LoggerConfigs to the configuration before it is registered
-for use.</p>
+<li>
+<p>You collect Log4j Core configurations from multiple sources.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>The following example adds an Appender and a new LoggerConfig using that
-Appender to the current configuration.</p>
+<p>You can programmatically combine multiple configurations into a single one using <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/CompositeConfiguration.html"><code>CompositeConfiguration</code></a>:</p>
</div>
<div class="listingblock">
+<div class="title">Snippet from an example <a href="https://github.com/apache/logging-log4j2/tree/2.x/src/site/antora/modules/ROOT/examples/manual/customconfig/Usage.java"><code>Usage.java</code></a></div>
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java"> final LoggerContext ctx = (LoggerContext) LogManager.getContext(false);
- final Configuration config = ctx.getConfiguration();
- Layout layout = PatternLayout.createDefaultLayout(config);
- Appender appender = FileAppender.createAppender("target/test.log", "false", "false", "File", "true",
- "false", "false", "4000", layout, null, "false", null, config);
- appender.start();
- config.addAppender(appender);
- AppenderRef ref = AppenderRef.createAppenderRef("File", null, null);
- AppenderRef[] refs = new AppenderRef[] {ref};
- LoggerConfig loggerConfig = LoggerConfig.createLogger("false", "info", "org.apache.logging.log4j",
- "true", refs, null, config, null );
- loggerConfig.addAppender(appender, null, null);
- config.addLogger("org.apache.logging.log4j", loggerConfig);
- ctx.updateLoggers();
-}</code></pre>
+<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">ConfigurationFactory configFactory = ConfigurationFactory.getInstance();
+AbstractConfiguration commonConfig = (AbstractConfiguration) <i class="conum" data-value="2"></i><b>(2)</b>
+ configFactory.getConfiguration(null, null, URI.create("classpath:log4j2-common.xml")); <i class="conum" data-value="1"></i><b>(1)</b>
+AbstractConfiguration appConfig = (AbstractConfiguration) <i class="conum" data-value="2"></i><b>(2)</b>
+ configFactory.getConfiguration(null, null, URI.create("classpath:log4j2-app.xml")); <i class="conum" data-value="1"></i><b>(1)</b>
+AbstractConfiguration runtimeConfig = ConfigurationBuilderFactory.newConfigurationBuilder()
+ // ...
+ .build(false); <i class="conum" data-value="3"></i><b>(3)</b>
+return new CompositeConfiguration(Arrays.asList(commonConfig, appConfig, runtimeConfig)); <i class="conum" data-value="4"></i><b>(4)</b></code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>Loading a common, and an application-specific configuration from file</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>Casting them to <code>AbstractConfiguration</code>, the type required by <code>CompositeConfiguration</code></td>
+</tr>
+<tr>
+<td><i class="conum" data-value="3"></i><b>3</b></td>
+<td>Programmatically creating an uninitialized configuration.
+Note that no casting is needed.</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="4"></i><b>4</b></td>
+<td>Creating a <code>CompositeConfiguration</code> using all three configurations created.
+Note that passed configuration order matters!</td>
+</tr>
+</table>
+</div>
+<details>
+<summary class="title">How does <code>CompositeConfiguration</code> work?</summary>
+<div class="content">
+<div class="paragraph">
+<p><code>CompositeConfiguration</code> merges multiple configurations into a single one using a <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy.html"><code>MergeStrategy</code></a>, which can be customized using <a href="systemproperties.html#log4j2.mergeStrategy" class="xref page">the <code>log4j2.mergeStrategy</code> configuration property</a>.
+The default merge strategy works as follows:</p>
</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="configuration.html#global-configuration-attributes" class="xref page">Global configuration attributes</a> in later configurations replace those in previous configurations.
+The only exception is the <code>monitorInterval</code> attribute: the lowest positive value from all the configuration files will be used.</p>
+</li>
+<li>
+<p><a href="configuration.html#property-substitution" class="xref page">Properties</a> are aggregated.
+Duplicate properties override those in previous configurations.</p>
+</li>
+<li>
+<p><a href="filters.html" class="xref page">Filters</a> are aggregated under <a href="filters.html#CompositeFilter" class="xref page"><code>CompositeFilter</code></a>, if more than one filter is defined.</p>
+</li>
+<li>
+<p><a href="scripts.html" class="xref page">Scripts</a> are aggregated.
+Duplicate definitions override those in previous configurations.</p>
+</li>
+<li>
+<p><a href="appenders.html" class="xref page">Appenders</a> are aggregated.
+Appenders with the same name are <strong>overridden</strong> by those in later configurations, including all their elements.</p>
+</li>
+<li>
+<p><a href="configuration.html#configuring-loggers" class="xref page">Loggers</a> are 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.</p>
+</li>
+</ul>
</div>
</div>
+</details>
</div>
-<div class="sect1">
-<h2 id="AppendingToWritersAndOutputStreams"><a class="anchor" href="#AppendingToWritersAndOutputStreams"></a>Appending Log Events to Writers and OutputStreams Programmatically</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="Hybrid"><a class="anchor" href="#Hybrid"></a><a id="AddingToCurrent"></a> <a id="AppendingToWritersAndOutputStreams"></a> Modifying configuration components</h3>
+<div class="admonitionblock warning">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-warning" title="Warning"></i>
+</td>
+<td class="content">
<div class="paragraph">
-<p>Log4j 2.5 provides facilities to append log events to Writers and
-OutputStreams. For example, this provides simple integration for JDBC
-Driver implementors that use Log4j internally and still want to support
-the JDBC APIs <code>CommonDataSource.setLogWriter(PrintWriter)</code>,
-<code>java.sql.DriverManager.setLogWriter(PrintWriter)</code>, and
-<code>java.sql.DriverManager.setLogStream(PrintStream)</code>.</p>
+<p><strong>We strongly advise against programmatically modifying components of a configuration!</strong>
+This section will explain what it is, and why you should avoid it.</p>
+</div>
+</td>
+</tr>
+</table>
</div>
<div class="paragraph">
-<p>Given any <code>Writer</code>, like a <code>PrintWriter</code>, you tell Log4j to append
-events to that writer by creating a <code>WriterAppender</code> and updating the
-Log4j configuration:</p>
+<p>It is unfortunately common that users modify components (appenders, filters, etc.) of a configuration programmatically as follows:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">void addAppender(final Writer writer, final String writerName) {
- final LoggerContext context = LoggerContext.getContext(false);
- final Configuration config = context.getConfiguration();
- final PatternLayout layout = PatternLayout.createDefaultLayout(config);
- final Appender appender = WriterAppender.createAppender(layout, null, writer, writerName, false, true);
- appender.start();
- config.addAppender(appender);
- updateLoggers(appender, config);
-}
-
-private void updateLoggers(final Appender appender, final Configuration config) {
- final Level level = null;
- final Filter filter = null;
- for (final LoggerConfig loggerConfig : config.getLoggers().values()) {
- loggerConfig.addAppender(appender, level, filter);
- }
- config.getRootLogger().addAppender(appender, level, filter);
-}</code></pre>
+<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">LoggerContext context = LoggerContext.getContext(false);
+Configuration config = context.getConfiguration();
+PatternLayout layout = PatternLayout.createDefaultLayout(config);
+Appender appender = createCustomAppender();
+appender.start();
+config.addAppender(appender);
+updateLoggers(appender, config);</code></pre>
</div>
</div>
<div class="paragraph">
-<p>You can achieve the same effect with an <code>OutputStream</code>, like a
-<code>PrintStream</code>:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">void addAppender(final OutputStream outputStream, final String outputStreamName) {
- final LoggerContext context = LoggerContext.getContext(false);
- final Configuration config = context.getConfiguration();
- final PatternLayout layout = PatternLayout.createDefaultLayout(config);
- final Appender appender = OutputStreamAppender.createAppender(layout, null, outputStream, outputStreamName, false, true);
- appender.start();
- config.addAppender(appender);
- updateLoggers(appender, config);
-}</code></pre>
+<p>This approach is prone several problems:</p>
</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Your code relies on Log4j Core internals which don’t have any backward compatibility guarantees.
+You not only risk breaking your build at a minor Log4j Core version upgrade, but also make the life of Log4j maintainers trying to evolve the project extremely difficult.</p>
+</li>
+<li>
+<p>You move out from the safety zone, where Log4j Core takes care of components' life cycle (initialization, reconfiguration, etc.), and step into a minefield seriously undermining the reliability of your logging setup.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>The difference is the use of <code>OutputStreamAppender</code> instead of
-<code>WriterAppender</code>.</p>
+<p>If you happen to have code programmatically modifying components of a configuration, we advise you to migrate to other declarative approaches shared in this page.
+In case of need, feel free to ask for help in <a href="https://logging.apache.org/support.html#discussions-user">user support channels</a>.</p>
+</div>
</div>
</div>
</div>
diff --git a/manual/customloglevels.html b/manual/customloglevels.html
index 32749b5ce3..28e7d72e2d 100644
--- a/manual/customloglevels.html
+++ b/manual/customloglevels.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -397,7 +397,7 @@ Using levels, you can filter out less important logs and focus on the most criti
<p>The <code>OFF</code> and <code>ALL</code> levels are special: they should not be used to fish-tag log events.</p>
</div>
<div class="paragraph">
-<p>Log4j implementations, such as Log4j Core, can use <code>OFF</code> in their configuration files to disable all log statements and <code>ALL</code> to enabled them all.</p>
+<p>Log4j API implementations, such as Log4j Core, can use <code>OFF</code> in their configuration files to disable all log statements and <code>ALL</code> to enabled them all.</p>
</div>
</td>
</tr>
diff --git a/manual/eventlogging.html b/manual/eventlogging.html
index 11552b533b..3a4e514053 100644
--- a/manual/eventlogging.html
+++ b/manual/eventlogging.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/extending.html b/manual/extending.html
index effb21b73a..cecc6b6a16 100644
--- a/manual/extending.html
+++ b/manual/extending.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
- <title>Extending Log4j :: Apache Log4j</title>
+ <title>Extending :: Apache Log4j</title>
<link rel="canonical" href="https://logging.apache.org/log4j/2.x/manual/extending.html">
<meta name="generator" content="Antora 3.2.0-alpha.4">
<link rel="stylesheet" href="../_/css/site.css">
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -326,590 +326,263 @@
<div class="toc-menu"></div>
</aside>
<article class="doc">
-<h1 class="page">Extending Log4j</h1>
+<h1 class="page">Extending</h1>
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
-<p>Log4j provides numerous ways that it can be manipulated and extended.
-This section includes an overview of the various ways that are directly
-supported by the Log4j 3 implementation.</p>
+<p>Log4j provides numerous extension points to adapt it for custom needs.
+Several of such extension points are covered in the page of the associated component:</p>
</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="LoggerContextFactory"><a class="anchor" href="#LoggerContextFactory"></a>LoggerContextFactory</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The <code>LoggerContextFactory</code> binds the Log4j API to its implementation.
-The Log4j <code>LogManager</code> locates a <code>LoggerContextFactory</code> by using
-<code>java.util.ServiceLoader</code> to locate all instances of
-<code>org.apache.logging.log4j.spi.Provider</code>. Each implementation must
-provide a class that extends <code>org.apache.logging.log4j.spi.Provider</code> and
-should have a no-arg constructor that delegates to Provider’s
-constructor passing the Priority, the API versions it is compatible
-with, and the class that implements
-<code>org.apache.logging.log4j.spi.LoggerContextFactory</code>. Log4j will compare
-the current API version and if it is compatible the implementation
-will be added to the list of providers. The API version in
-<code>org.apache.logging.log4j.LogManager</code> is only changed when a feature is
-added to the API that implementations need to be aware of. If more than
-one valid implementation is located the value for the Priority will be
-used to identify the factory with the highest priority. Finally, the
-class that implements
-<code>org.apache.logging.log4j.spi.LoggerContextFactory</code> will be instantiated
-and bound to the LogManager. In Log4j 2 this is provided by
-<code>Log4jContextFactory</code>.</p>
-</div>
-<div class="paragraph">
-<p>Applications may change the LoggerContextFactory that will be used by</p>
-</div>
-<div class="olist arabic">
-<ol class="arabic">
+<div class="ulist">
+<ul>
<li>
-<p>Create a binding to the logging implementation.</p>
-<div class="olist loweralpha">
-<ol class="loweralpha" type="a">
+<p>Log4j API</p>
+<div class="ulist">
+<ul>
<li>
-<p>Implement a new <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/impl/Log4jContextFactory.html"><code>LoggerContextFactory</code></a>.</p>
+<p><a href="customloglevels.html" class="xref page">Extending levels</a></p>
</li>
<li>
-<p>Implement a class that extends
-<a href="../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider.html"><code>org.apache.logging.log4j.spi.Provider</code></a>
-with a no-arg constructor that calls super-class’s constructor with the
-Priority, the API version(s), <code>LoggerContextFactory</code> class, and
-optionally, a
-<a href="../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap.html"><code>ThreadContextMap</code></a>
-implementation class.</p>
+<p><a href="markers.html" class="xref page">Extending markers</a></p>
</li>
<li>
-<p>Create a <code>META-INF/services/org.apache.logging.spi.Provider</code> file
-that contains the name of the class that implements
-<code>org.apache.logging.spi.Provider</code>.</p>
+<p><a href="messages.html#extending" class="xref page">Extending messages</a></p>
</li>
-</ol>
+<li>
+<p><a href="thread-context.html#extending" class="xref page">Extending thread context</a></p>
+</li>
+</ul>
</div>
</li>
<li>
-<p>Setting the system property "log4j2.loggerContextFactory" to the name
-of the <code>LoggerContextFactory</code> class to use.</p>
+<p>Log4j Core</p>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="appenders.html#extending" class="xref page">Extending appenders</a></p>
</li>
<li>
-<p>Setting the property "log4j2.loggerContextFactory" in a properties
-file named "log4j2.LogManager.properties" to the name of the
-LoggerContextFactory class to use. The properties file must be on the
-classpath.</p>
+<p><a href="filters.html#extending" class="xref page">Extending filters</a></p>
</li>
-</ol>
-</div>
+<li>
+<p><a href="layouts.html#extending" class="xref page">Extending layouts</a></p>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="json-template-layout.html#extending" class="xref page">Extending JSON Template Layout</a></p>
+</li>
+<li>
+<p><a href="pattern-layout.html#extending" class="xref page">Extending Pattern Layout</a></p>
+</li>
+</ul>
</div>
+</li>
+<li>
+<p><a href="lookups.html#extending" class="xref page">Extending lookups</a></p>
+</li>
+</ul>
</div>
-<div class="sect1">
-<h2 id="ContextSelector"><a class="anchor" href="#ContextSelector"></a>ContextSelector</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>ContextSelectors are called by the
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/impl/Log4jContextFactory.html">Log4j <code>LoggerContext</code> factory</a>. They perform the actual work of locating or
-creating a LoggerContext, which is the anchor for Loggers and their
-configuration. ContextSelectors are free to implement any mechanism they
-desire to manage LoggerContexts. The default Log4jContextFactory checks
-for the presence of an <code>Injector</code> binding for <code>ContextSelector</code>.
-If none are defined, the System Property named "Log4jContextSelector" is checked.
-If found, the property is expected to contain the name of the Class that implements the ContextSelector to be used.
-This class is then used for creating <code>ContextSelector</code> instances.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>Log4j provides five ContextSelectors:</p>
-</div>
-<div class="dlist">
-<dl>
-<dt class="hdlist1"><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector.html"><code>BasicContextSelector</code></a></dt>
-<dd>
-<p>Uses either a LoggerContext that has been stored in a ThreadLocal or a
-common LoggerContext.</p>
-</dd>
-<dt class="hdlist1"><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector.html"><code>ClassLoaderContextSelector</code></a></dt>
-<dd>
-<p>Associates LoggerContexts with the ClassLoader that created the caller
-of the getLogger(…​) call. This is the default ContextSelector.</p>
-</dd>
-<dt class="hdlist1"><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector.html"><code>JndiContextSelector</code></a></dt>
-<dd>
-<p>Locates the LoggerContext by querying JNDI.</p>
-</dd>
-<dt class="hdlist1"><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector.html"><code>AsyncLoggerContextSelector</code></a></dt>
-<dd>
-<p>Creates a LoggerContext that ensures that all loggers are
-AsyncLoggers.</p>
-</dd>
-<dt class="hdlist1"><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector.html"><code>BundleContextSelector</code></a></dt>
-<dd>
-<p>Associates LoggerContexts with the ClassLoader of the bundle that
-created the caller of the getLogger call. This is enabled by default
-in OSGi environments.</p>
-</dd>
-</dl>
+<p>This section guides you on the rest of the Log4j extension points.</p>
</div>
</div>
</div>
<div class="sect1">
-<h2 id="ConfigurationFactory"><a class="anchor" href="#ConfigurationFactory"></a>ConfigurationFactory</h2>
+<h2 id="mechanisms"><a class="anchor" href="#mechanisms"></a>Extension mechanisms</h2>
<div class="sectionbody">
<div class="paragraph">
-<p>Modifying the way in which logging can be configured is usually one of
-the areas with the most interest. The primary method for doing that is
-by implementing or extending a
-<a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory.html"><code>ConfigurationFactory</code></a>.
-Log4j provides two ways of adding new ConfigurationFactories. The first
-is by defining the system property named "log4j.configurationFactory" to
-the name of the class that should be searched first for a configuration.
-The second method is by defining the <code>ConfigurationFactory</code> as a <code>Plugin</code>.</p>
+<p>Log4j allows extensions primarily using following mechanisms:</p>
</div>
+<div class="sect2">
+<h3 id="Custom_Plugins"><a class="anchor" href="#Custom_Plugins"></a>Plugins</h3>
<div class="paragraph">
-<p>All the ConfigurationFactories are then processed in order. Each factory
-is called on its <code>getSupportedTypes()</code> method to determine the file
-extensions it supports. If a configuration file is located with one of
-the specified file extensions then control is passed to that
-<code>ConfigurationFactory</code> to load the configuration and create the <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html"><code>Configuration</code></a> object.</p>
+<p>Log4j plugin system is the de facto extension mechanism embraced by various Log4j components.
+Plugins provide extension points to components, that can be used to implement new features, without modifying the original component.
+It is analogous to a <a href="https://en.wikipedia.org/wiki/Dependency_injection">dependency injection</a> framework, but curated for Log4j-specific needs.</p>
</div>
<div class="paragraph">
-<p>Most <code>Configuration</code> extend the <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/AbstractConfiguration.html"><code>AbstractConfiguration</code></a> class. This class expects that the subclass will process the configuration file and create
-a hierarchy of <code>Node</code> objects. Each <code>Node</code> is fairly simple in that it
-consists of the name of the node, the name/value pairs associated with
-the node, The <code>PluginType</code> of the node and a List of all of its child
-Nodes. <code>Configuration</code> will then be passed the <code>Node</code> tree and
-instantiate the configuration objects from that.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Namespace("ConfigurationFactory")
-@Plugin("XMLConfigurationFactory")
-@Order(5)
-public class XMLConfigurationFactory extends ConfigurationFactory {
-
- /**
- * Valid file extensions for XML files.
- */
- public static final String[] SUFFIXES = new String[] {".xml", "*"};
-
- /**
- * Returns the Configuration.
- * @param loggerContext The logger context.
- * @param source The InputSource.
- * @return The Configuration.
- */
- @Override
- public Configuration getConfiguration(final LoggerContext loggerContext, final ConfigurationSource source) {
- return new XmlConfiguration(loggerContext, source);
- }
-
- /**
- * Returns the file suffixes for XML files.
- * @return An array of File extensions.
- */
- public String[] getSupportedTypes() {
- return SUFFIXES;
- }
-}</code></pre>
-</div>
-</div>
+<p>In a nutshell, you annotate your classes with <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/Plugin.html"><code>@Plugin</code></a> and their (<code>static</code>) factory methods with <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginFactory.html"><code>@PluginFactory</code></a>.
+Last, you inform the Log4j plugin system to discover these custom classes.
+This is done using running the <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/processor/PluginProcessor.html"><code>PluginProcessor</code></a> annotation processor while building your project.
+Refer to <a href="plugins.html" class="xref page">Plugins</a> for details.</p>
</div>
</div>
-<div class="sect1">
-<h2 id="LoggerConfig"><a class="anchor" href="#LoggerConfig"></a>LoggerConfig</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="service-loader"><a class="anchor" href="#service-loader"></a><code>ServiceLoader</code>s</h3>
<div class="paragraph">
-<p><code>LoggerConfig</code> objects are where Loggers created by applications tie into
-the configuration. The Log4j implementation requires that all
-LoggerConfigs are based on the LoggerConfig class, so applications
-wishing to make changes must do so by extending the <code>LoggerConfig</code> class.
-To declare the new <code>LoggerConfig</code>, declare it as a Plugin of type "Core"
-and providing the name that applications should specify as the element
-name in the configuration. The <code>LoggerConfig</code> should also define a
-PluginFactory that will create an instance of the <code>LoggerConfig</code>.</p>
-</div>
-<div class="paragraph">
-<p>The following example shows how the root <code>LoggerConfig</code> simply extends a
-generic <code>LoggerConfig</code>.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Configurable(printObject = true)
-@Plugin("root")
-public static class RootLogger extends LoggerConfig {
-
- @PluginFactory
- public static LoggerConfig createLogger(@PluginAttribute(defaultBooleanValue = true) boolean additivity,
- @PluginAttribute(defaultStringValue = "ERROR") Level level,
- @PluginElement AppenderRef[] refs,
- @PluginElement Filter filter) {
- List<AppenderRef> appenderRefs = Arrays.asList(refs);
- return new LoggerConfig(LogManager.ROOT_LOGGER_NAME, appenderRefs, filter, level, additivity);
- }
-}</code></pre>
+<p><a href="https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html"><code>ServiceLoader</code></a> is a simple service-provider loading facility baked into the Java platform itself.
+Log4j uses <code>ServiceLoader</code>s for extending places where</p>
</div>
+<div class="ulist">
+<ul>
+<li>
+<p>The service needs to be implementation agnostic.
+As a result, <a href="#Custom_Plugins">the Log4j plugin system</a> cannot be used, since it is provided by the logging implementation, i.e., Log4j Core.
+For instance, this is why <a href="thread-context.html#extending" class="xref page">extending Thread Context</a>, which is a Log4j API component, works using <code>ServiceLoader</code>s.</p>
+</li>
+<li>
+<p>The service needs to be loaded before <a href="#Custom_Plugins">the Log4j plugin system</a>.
+For instance, this is why <a href="#Provider">extending <code>Provider</code></a> works using <code>ServiceLoader</code>s.</p>
+</li>
+</ul>
</div>
+<div class="paragraph">
+<p>Refer to <a href="https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html">the <code>ServiceLoader</code> documentation</a> for details.</p>
</div>
</div>
-<div class="sect1">
-<h2 id="LogEventFactory"><a class="anchor" href="#LogEventFactory"></a>LogEventFactory</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="system-properties"><a class="anchor" href="#system-properties"></a>System properties</h3>
<div class="paragraph">
-<p>A LogEventFactory is used to generate LogEvents. Applications may replace the standard LogEventFactory by setting the value of the system property Log4jLogEventFactory to the name of the custom LogEventFactory class.</p>
-</div>
+<p>Log4j uses system properties to determine the fully-qualified class name (FQCN) to load for extending a certain functionality.
+For instance, <a href="#MessageFactory">extending <code>MessageFactory2</code></a> works using system properties.</p>
+</div>
+<div class="admonitionblock warning">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-warning" title="Warning"></i>
+</td>
+<td class="content">
<div class="paragraph">
-<p>Note: When log4j is configured to have <a href="async.html#AllAsync" class="xref page">all
-loggers asynchronous</a>, log events are pre-allocated in a ring buffer and
-the <code>LogEventFactory</code> is not used.</p>
+<p>Loading a class using <em>only</em> its FQCN can result in unexpected behaviour when there are multiple class loaders.</p>
</div>
+</td>
+</tr>
+</table>
</div>
</div>
-<div class="sect1">
-<h2 id="MessageFactory"><a class="anchor" href="#MessageFactory"></a>MessageFactory</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>A <code>MessageFactory</code> is used to generate <code>Message</code> objects. Applications may
-replace the standard <code>ReusableMessageFactory</code> by setting the value of the
-system property <code>log4j2.messageFactory</code> to the name of the custom
-<code>MessageFactory</code> class.</p>
-</div>
-<div class="paragraph">
-<p>Flow messages for the <code>Logger.entry()</code> and <code>Logger.exit()</code> methods have
-a separate <code>FlowMessageFactory</code>. Applications may replace the
-<code>DefaultFlowMessageFactory</code> by setting the value of the system property
-<code>log4j2.flowMessageFactory</code> to the name of the custom <code>FlowMessageFactory</code>
-class.</p>
-</div>
</div>
</div>
<div class="sect1">
-<h2 id="Lookups"><a class="anchor" href="#Lookups"></a>Lookups</h2>
+<h2 id="points"><a class="anchor" href="#points"></a>Extension points</h2>
<div class="sectionbody">
<div class="paragraph">
-<p>Lookups are the means in which parameter substitution is performed.
-During Configuration initialization an "Interpolator" is created that
-locates all the Lookups and registers them for use when a variable needs
-to be resolved. The interpolator matches the "prefix" portion of the
-variable name to a registered Lookup and passes control to it to resolve
-the variable.</p>
+<p>In this section we will guide you on certain Log4j extension points that are not covered elsewhere.</p>
</div>
+<div class="sect2">
+<h3 id="Provider"><a class="anchor" href="#Provider"></a><code>Provider</code></h3>
<div class="paragraph">
-<p>A Lookup must be declared using a <code>@Plugin @Lookup</code> annotation. The <code>value</code> specified on the <code>@Plugin</code> annotation will be used to
-match the prefix. The example below shows a Lookup that will return
-the value of a System Property.</p>
+<p><a href="../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider.html"><code>Provider</code></a> is the anchor contract binding Log4j API to an implementation.
+For instance, it has been implemented by Log4j Core, Log4j-to-JUL bridge, and Log4j-to-SLF4J bridge modules.</p>
</div>
<div class="paragraph">
-<p>The provided Lookups are documented here: <a href="lookups.html" class="xref page">Lookups</a></p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Lookup
-@Plugin("sys")
-public class SystemPropertiesLookup implements StrLookup {
-
- /**
- * Lookup the value for the key.
- * @param key the key to be looked up, may be null
- * @return The value for the key.
- */
- public String lookup(String key) {
- return System.getProperty(key);
- }
-
- /**
- * Lookup the value for the key using the data in the LogEvent.
- * @param event The current LogEvent.
- * @param key the key to be looked up, may be null
- * @return The value associated with the key.
- */
- public String lookup(LogEvent event, String key) {
- return System.getProperty(key);
- }
-}</code></pre>
-</div>
+<p>Under the hood, <a href="../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html"><code>LogManager</code></a> locates a <code>Provider</code> implementation using <a href="#service-loader">the <code>ServiceLoader</code> mechanism</a>, and delegates invocations to it.
+Hence, you can extend it by providing a <code>org.apache.logging.log4j.spi.Provider</code> implementation in the form of a <code>ServiceLoader</code>.</p>
</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="Filters"><a class="anchor" href="#Filters"></a>Filters</h2>
-<div class="sectionbody">
<div class="paragraph">
-<p>As might be expected, Filters are used to reject or accept log
-events as they pass through the logging system. A Filter is declared
-using a <code>@Configurable</code> annotation with an <code>elementType</code> of "filter".
-The <code>value</code> attribute on the <code>@Plugin</code> annotation is used to specify the name
-of the element users should use to enable the Filter. Specifying the
-<code>printObject</code> attribute with a value of "true" indicates that a call to
-<code>toString</code> will format the arguments to the filter as the configuration is
-being processed. The Filter must also specify a <code>@PluginFactory</code> method
-or <code>@PluginFactoryBuilder</code> builder class and method
-that will be called to create the Filter.</p>
+<p>Having multiple <code>Provider</code>s in the classpath is strongly discouraged.
+Yet when this happens, you can use <a href="systemproperties.html#log4j2.provider" class="xref page">the <code>log4j2.provider</code> property</a> to explicitly select one.</p>
+</div>
</div>
+<div class="sect2">
+<h3 id="LoggerContextFactory"><a class="anchor" href="#LoggerContextFactory"></a><code>LoggerContextFactory</code></h3>
<div class="paragraph">
-<p>The example below shows a Filter used to reject LogEvents based upon
-their logging level. Notice the typical pattern where all the filter
-methods resolve to a single filter method.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Plugin(name = "ThresholdFilter", category = "Core", elementType = "filter", printObject = true)
-public final class ThresholdFilter extends AbstractFilter {
-
- private final Level level;
-
- private ThresholdFilter(Level level, Result onMatch, Result onMismatch) {
- super(onMatch, onMismatch);
- this.level = level;
- }
-
- public Result filter(Logger logger, Level level, Marker marker, String msg, Object[] params) {
- return filter(level);
- }
-
- public Result filter(Logger logger, Level level, Marker marker, Object msg, Throwable t) {
- return filter(level);
- }
-
- public Result filter(Logger logger, Level level, Marker marker, Message msg, Throwable t) {
- return filter(level);
- }
-
- @Override
- public Result filter(LogEvent event) {
- return filter(event.getLevel());
- }
-
- private Result filter(Level level) {
- return level.isAtLeastAsSpecificAs(this.level) ? onMatch : onMismatch;
- }
-
- @Override
- public String toString() {
- return level.toString();
- }
-
- /**
- * Create a ThresholdFilter.
- * @param level The log Level.
- * @param onMatch The action to take on a match.
- * @param onMismatch The action to take on a mismatch.
- * @return The created ThresholdFilter.
- */
- @PluginFactory
- public static ThresholdFilter createFilter(@PluginAttribute(defaultStringValue = "ERROR") Level level,
- @PluginAttribute(defaultStringValue = "NEUTRAL") Result onMatch,
- @PluginAttribute(defaultStringValue = "DENY") Result onMismatch) {
- return new ThresholdFilter(level, onMatch, onMismatch);
- }
-}</code></pre>
+<p><a href="../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory.html"><code>LoggerContextFactory</code></a> is the factory class used by Log4j API implementations to create <a href="architecture.html#LoggerContext" class="xref page"><code>LoggerContext</code></a>s.
+If you are using Log4j Core, you can use <a href="#ContextSelector"><code>ContextSelector</code></a>s to influence the way its <code>LoggerContextFactory</code> implementation works.
+If you are creating a new Log4j API implementation, you should <a href="#Provider">provide a custom <code>Provider</code></a> to introduce your custom <code>LoggerContextFactory</code> implementation.</p>
</div>
</div>
+<div class="sect2">
+<h3 id="ContextSelector"><a class="anchor" href="#ContextSelector"></a><code>ContextSelector</code></h3>
+<div class="paragraph">
+<p><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/impl/Log4jContextFactory.html"><code>Log4jContextFactory</code></a>, the Log4j Core implementation of <a href="#LoggerContextFactory"><code>LoggerContextFactory</code></a>, delegates the actual work to a <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector.html"><code>ContextSelector</code></a>.
+It can be configured using <a href="systemproperties.html#log4j2.contextSelector" class="xref page">the <code>log4j2.contextSelector</code> property</a>.</p>
</div>
</div>
-<div class="sect1">
-<h2 id="Appenders"><a class="anchor" href="#Appenders"></a>Appenders</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="ConfigurationFactory"><a class="anchor" href="#ConfigurationFactory"></a><code>ConfigurationFactory</code></h3>
<div class="paragraph">
-<p>Appenders are passed an event, (usually) invoke a Layout to format the
-event, and then "publish" the event in whatever manner is desired.
-Appenders are declared as <code>@Configurable</code> with an
-<code>elementType</code> of "appender". The <code>value</code> attribute on the <code>@Plugin</code> annotation
-specifies the name of the element users must provide in their
-configuration to use the Appender. Appenders should specify <code>printObject</code>
-as "true" if the toString method renders the values of the attributes
-passed to the Appender.</p>
+<p><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory.html"><code>ConfigurationFactory</code></a> is the factory class used by Log4j Core to create <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html"><code>Configuration</code></a> instances given a <a href="architecture.html#LoggerContext" class="xref page"><code>LoggerContext</code></a> and a <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Conf [...]
</div>
<div class="paragraph">
-<p>Appenders must also declare a <code>@PluginFactory</code> method that returns an instance
-of the appender or a builder class used to create the appender. The example below shows
-an Appender named "Stub" that can be used as an initial template.</p>
+<p>You can provide a custom <code>ConfigurationFactory</code> in the form of a <a href="#Custom_Plugins">plugin</a>.
+For example, see <a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core/src/main/java/org/apache/logging/log4j/core/config/xml/XmlConfigurationFactory.java"><code>XmlConfigurationFactory.java</code></a> and <a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core/src/main/java/org/apache/logging/log4j/core/config/xml/XmlConfiguration.java"><code>XmlConfiguration.java</code></a> of Log4j Core.</p>
</div>
<div class="paragraph">
-<p>Most Appenders use Managers. A manager actually "owns" the resources,
-such as an <code>OutputStream</code> or socket. When a reconfiguration occurs a new
-Appender will be created. However, if nothing significant in the
-previous Manager has changed, the new Appender will simply reference it
-instead of creating a new one. This insures that events are not lost
-while a reconfiguration is taking place without requiring that logging
-pause while the reconfiguration takes place.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Plugin(name = "Stub", category = "Core", elementType = "appender", printObject = true)
-public final class StubAppender extends AbstractOutputStreamAppender<StubManager> {
-
- private StubAppender(String name,
- Layout<?> layout,
- Filter filter,
- boolean ignoreExceptions,
- StubManager manager) {
- super(name, layout, filter, ignoreExceptions, true, manager);
- }
-
- @PluginFactory
- public static StubAppender createAppender(@PluginAttribute @Required(message = "No name provided for StubAppender") String name,
- @PluginAttribute boolean ignoreExceptions,
- @PluginElement Layout layout,
- @PluginElement Filter filter) {
-
- StubManager manager = StubManager.getStubManager(name);
- if (manager == null) {
- return null;
- }
- if (layout == null) {
- layout = PatternLayout.createDefaultLayout();
- }
- return new StubAppender(name, layout, filter, ignoreExceptions, manager);
- }
-}</code></pre>
+<p>You can use <a href="systemproperties.html#log4j2.configurationFactory" class="xref page">the <code>log4j2.configurationFactory</code> property</a> to explicitly set a <code>ConfigurationFactory</code> to be used before any other factory implementation.</p>
</div>
</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="Plugin_Builders"><a class="anchor" href="#Plugin_Builders"></a>Plugin Builders</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="LoggerConfig"><a class="anchor" href="#LoggerConfig"></a><code>LoggerConfig</code></h3>
<div class="paragraph">
-<p>Some plugins take a lot of optional configuration options. When a plugin
-takes many options, it is more maintainable to use a builder class
-rather than a factory method (see <em>Item 2: Consider a builder when faced
-with many constructor parameters</em> in <em>Effective Java</em> by Joshua Bloch).
-There are some other advantages to using an annotated builder class over
-an annotated factory method:</p>
+<p><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/LoggerConfig.html"><code>LoggerConfig</code></a> denotes the <code>Logger</code> configurations in a <code>Configuration</code>.
+A custom <code>LoggerConfig</code> needs to satisfy the following conditions:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>Attribute names don’t need to be specified if they match the field name or the parameter name.</p>
-</li>
-<li>
-<p>Default values can be specified in code rather than through an
-annotation (also allowing a runtime-calculated default value which isn’t
-allowed in annotations).</p>
+<p>It needs to extend from <code>LoggerConfig</code> class</p>
</li>
<li>
-<p>Adding new optional parameters doesn’t require existing programmatic
-configuration to be refactored.</p>
-</li>
+<p>It needs to be declared as a <a href="#Custom_Plugins">plugin</a></p>
+<div class="ulist">
+<ul>
<li>
-<p>Easier to write unit tests using builders rather than factory methods
-with optional parameters.</p>
+<p>Its plugin <code>category</code> should be set to <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Node.html#CATEGORY"><code>Node.CATEGORY</code></a></p>
</li>
-<li>
-<p>Default values are specified via code rather than relying on
-reflection and injection, so they work programmatically as well as in a
-configuration file.</p>
+</ul>
+</div>
</li>
</ul>
</div>
<div class="paragraph">
-<p>Here is an example of a plugin factory from <code>ListAppender</code>:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@PluginFactory
-public static ListAppender createAppender(
- @PluginAttribute("name") @Required(message = "No name provided for ListAppender") final String name,
- @PluginAttribute("entryPerNewLine") final boolean newLine,
- @PluginAttribute("raw") final boolean raw,
- @PluginElement("Layout") final Layout<? extends Serializable> layout,
- @PluginElement("Filter") final Filter filter) {
- return new ListAppender(name, filter, layout, newLine, raw);
-}</code></pre>
+<p>For example, see <code>RootLogger</code> definition in <a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core/src/main/java/org/apache/logging/log4j/core/config/LoggerConfig.java"><code>LoggerConfig.java</code></a>.</p>
</div>
</div>
+<div class="sect2">
+<h3 id="LogEventFactory"><a class="anchor" href="#LogEventFactory"></a><code>LogEventFactory</code></h3>
+<div class="paragraph">
+<p>Log4j Core uses <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/impl/LogEventFactory.html"><code>LogEventFactory</code></a> to create <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html"><code>LogEvent</code></a>s.
+You can replace the default <code>LogEventFactory</code> implementation with a custom one of yours by using <a href="systemproperties.html#log4j2.logEventFactory" class="xref page">the <code>log4j2.logEventFactory</code> property</a>.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
<div class="paragraph">
-<p>Here is that same factory using a builder pattern instead:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@PluginBuilderFactory
-public static Builder newBuilder() {
- return new Builder();
-}
-
-public static class Builder implements org.apache.logging.log4j.core.util.Builder<ListAppender> {
-
- @PluginBuilderAttribute
- @Required(message = "No name provided for ListAppender")
- private String name;
-
- @PluginBuilderAttribute
- private boolean entryPerNewLine;
-
- @PluginBuilderAttribute
- private boolean raw;
-
- @PluginElement("Layout")
- private Layout<? extends Serializable> layout;
-
- @PluginElement("Filter")
- private Filter filter;
-
- public Builder setName(final String name) {
- this.name = name;
- return this;
- }
-
- public Builder setEntryPerNewLine(final boolean entryPerNewLine) {
- this.entryPerNewLine = entryPerNewLine;
- return this;
- }
-
- public Builder setRaw(final boolean raw) {
- this.raw = raw;
- return this;
- }
-
- public Builder setLayout(final Layout<? extends Serializable> layout) {
- this.layout = layout;
- return this;
- }
-
- public Builder setFilter(final Filter filter) {
- this.filter = filter;
- return this;
- }
-
- @Override
- public ListAppender build() {
- return new ListAppender(name, filter, layout, entryPerNewLine, raw);
- }
-}</code></pre>
+<p><a href="async.html" class="xref page">Asynchronous loggers</a> discard <code>LogEventFactory</code> and any configuration related with it.</p>
</div>
+</td>
+</tr>
+</table>
</div>
-<div class="paragraph">
-<p>The only difference in annotations is using <code>@PluginBuilderAttribute</code> instead of <code>@PluginAttribute</code>
-so that default values and reflection can be used instead of specifying them in the annotation.
-Either annotation can be used in a builder, but the former is better suited for field injection
-while the latter is better suited for parameter injection. Otherwise, the same annotations
-(<code>@PluginConfiguration</code>, <code>@PluginElement</code>, <code>@PluginNode</code>, and <code>@PluginValue</code>) are all supported on fields.
-Note that a factory method is still required to supply a builder, and this factory method
-should be annotated with <code>@PluginBuilderFactory</code>.</p>
</div>
+<div class="sect2">
+<h3 id="MessageFactory"><a class="anchor" href="#MessageFactory"></a><code>MessageFactory2</code></h3>
<div class="paragraph">
-<p>When plugins are being constructed after a configuration has been
-parsed, a plugin builder will be used if available, otherwise a plugin
-factory method will be used as a fallback. If a plugin contains neither
-factory, then it cannot be used from a configuration file (it can still
-be used programmatically of course).</p>
+<p>Log4j Core uses <a href="../javadoc/log4j-api/org/apache/logging/log4j/message/MessageFactory2.html"><code>MessageFactory2</code></a> to create <a href="../javadoc/log4j-api/org/apache/logging/log4j/message/Message.html"><code>Message</code></a>s.
+You can replace the default <code>MessageFactory2</code> implementation with a custom one of yours by using <a href="systemproperties.html#log4j2.messageFactory" class="xref page">the <code>log4j2.messageFactory</code> property</a>.</p>
</div>
<div class="paragraph">
-<p>Here is an example of using a plugin factory versus a plugin builder
-programmatically:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">ListAppender list1 = ListAppender.createAppender("List1", true, false, null, null);
-ListAppender list2 = ListAppender.newBuilder().setName("List1").setEntryPerNewLine(true).build();</code></pre>
-</div>
+<p>In the case of <a href="flowtracing.html" class="xref page">Flow Tracing</a>, Log4j Core uses <a href="../javadoc/log4j-api/org/apache/logging/log4j/message/FlowMessageFactory.html"><code>FlowMessageFactory</code></a>.
+You can replace the default <code>FlowMessageFactory</code> implementation with a custom one of yours by using <a href="systemproperties.html#log4j2.flowMessageFactory" class="xref page">the <code>log4j2.flowMessageFactory</code> property</a>.</p>
+</div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Message factory implementations are expected to interpret formatting patterns containing placeholders denoted with <code>{}</code>.
+For instance, the default message factory chooses between a <a href="messages.html#SimpleMessage" class="xref page"><code>SimpleMessage</code></a> and a <a href="messages.html#ParameterizedMessage" class="xref page"><code>ParameterizedMessage</code></a> depending on the presence of placeholders in the formatting pattern.</p>
</div>
+<div class="paragraph">
+<p>If you want to change the placeholder style (e.g., switching from <code>{}</code> to <code>%s</code>), you should <strong>not</strong> replace the default message factory.
+Because this will break the existing Log4j API calls using the standard placeholder style.
+Instead, you can use <a href="../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html"><code>LogManager</code></a> methods accepting a message factory to create <code>Logger</code>s with your custom message factory implementations.</p>
</div>
+</td>
+</tr>
+</table>
</div>
-<div class="sect1">
-<h2 id="Custom_Plugins"><a class="anchor" href="#Custom_Plugins"></a>Custom Plugins</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>See the <a href="plugins.html" class="xref page">Plugins</a> section of the manual.</p>
</div>
</div>
</div>
diff --git a/manual/filters.html b/manual/filters.html
index b4a18c2225..e081c3323b 100644
--- a/manual/filters.html
+++ b/manual/filters.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -576,9 +576,15 @@ This reduces the costs (formatting, transfer through an asynchronous barrier) of
</div>
</div>
<div class="sect1">
-<h2 id="BurstFilter"><a class="anchor" href="#BurstFilter"></a>BurstFilter</h2>
+<h2 id="collection"><a class="anchor" href="#collection"></a>Collection</h2>
<div class="sectionbody">
<div class="paragraph">
+<p>Log4j bundles several predefined filters to assist in several common deployment use cases.
+Following sections explain all these in detail.</p>
+</div>
+<div class="sect2">
+<h3 id="BurstFilter"><a class="anchor" href="#BurstFilter"></a>BurstFilter</h3>
+<div class="paragraph">
<p>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.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
@@ -656,10 +662,8 @@ be ACCEPT, DENY or NEUTRAL. The default value is DENY.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="CompositeFilter"><a class="anchor" href="#CompositeFilter"></a>CompositeFilter</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="CompositeFilter"><a class="anchor" href="#CompositeFilter"></a>CompositeFilter</h3>
<div class="paragraph">
<p>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.
@@ -706,10 +710,8 @@ The filter element accepts no parameters.</p>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="DynamicThresholdFilter"><a class="anchor" href="#DynamicThresholdFilter"></a>DynamicThresholdFilter</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="DynamicThresholdFilter"><a class="anchor" href="#DynamicThresholdFilter"></a>DynamicThresholdFilter</h3>
<div class="paragraph">
<p>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.
@@ -794,10 +796,8 @@ be ACCEPT, DENY or NEUTRAL. The default value is DENY.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="LevelRangeFilter"><a class="anchor" href="#LevelRangeFilter"></a>LevelRangeFilter</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="LevelRangeFilter"><a class="anchor" href="#LevelRangeFilter"></a>LevelRangeFilter</h3>
<div class="paragraph">
<p><code>LevelRangeFilter</code> allows filtering against a level range, where levels get compared by their associated integral values; <code>OFF</code> has an integral value of 0, <code>FATAL</code> 100, <code>ERROR</code> 200, and so on.</p>
</div>
@@ -862,10 +862,8 @@ The filter will return <code>onMismatch</code> result (i.e., <code>DENY</code>,
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="MapFilter"><a class="anchor" href="#MapFilter"></a>MapFilter</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="MapFilter"><a class="anchor" href="#MapFilter"></a>MapFilter</h3>
<div class="paragraph">
<p>The MapFilter allows filtering against data elements that are in a MapMessage.</p>
</div>
@@ -1003,10 +1001,8 @@ be ACCEPT, DENY or NEUTRAL. The default value is DENY.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="MarkerFilter"><a class="anchor" href="#MarkerFilter"></a>MarkerFilter</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="MarkerFilter"><a class="anchor" href="#MarkerFilter"></a>MarkerFilter</h3>
<div class="paragraph">
<p>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.</p>
@@ -1071,10 +1067,8 @@ be ACCEPT, DENY or NEUTRAL. The default value is DENY.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="MutableThreadContextMapFilter"><a class="anchor" href="#MutableThreadContextMapFilter"></a>MutableThreadContextMapFilter</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="MutableThreadContextMapFilter"><a class="anchor" href="#MutableThreadContextMapFilter"></a>MutableThreadContextMapFilter</h3>
<div class="paragraph">
<p>The MutableThreadContextMapFilter or MutableContextMapFilter allows filtering against data elements that are in the current context.
By default, this is the ThreadContext Map.
@@ -1166,10 +1160,8 @@ be ACCEPT, DENY or NEUTRAL. The default value is DENY.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="NoMarkerFilter"><a class="anchor" href="#NoMarkerFilter"></a>NoMarkerFilter</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="NoMarkerFilter"><a class="anchor" href="#NoMarkerFilter"></a>NoMarkerFilter</h3>
<div class="paragraph">
<p>The NoMarkerFilter checks that there is no marker included in the LogEvent.
A match occurs when there is no marker in the Log Event.</p>
@@ -1229,10 +1221,8 @@ be ACCEPT, DENY or NEUTRAL. The default value is DENY.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="RegexFilter"><a class="anchor" href="#RegexFilter"></a>RegexFilter</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="RegexFilter"><a class="anchor" href="#RegexFilter"></a>RegexFilter</h3>
<div class="paragraph">
<p>The RegexFilter allows the formatted or unformatted message to be compared against a regular expression.</p>
</div>
@@ -1452,10 +1442,8 @@ See
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="StructuredDataFilter"><a class="anchor" href="#StructuredDataFilter"></a>StructuredDataFilter</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="StructuredDataFilter"><a class="anchor" href="#StructuredDataFilter"></a>StructuredDataFilter</h3>
<div class="paragraph">
<p>The StructuredDataFilter is a MapFilter that also allows filtering on the event id, type and message.</p>
</div>
@@ -1536,10 +1524,8 @@ be ACCEPT, DENY or NEUTRAL. The default value is DENY.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="ThreadContextMapFilter"><a class="anchor" href="#ThreadContextMapFilter"></a>ThreadContextMapFilter</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="ThreadContextMapFilter"><a class="anchor" href="#ThreadContextMapFilter"></a>ThreadContextMapFilter</h3>
<div class="paragraph">
<p>The ThreadContextMapFilter or ContextMapFilter allows filtering against data elements that are in the current context.
By default, this is the ThreadContext Map.</p>
@@ -1647,10 +1633,8 @@ be ACCEPT, DENY or NEUTRAL. The default value is DENY.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="ThresholdFilter"><a class="anchor" href="#ThresholdFilter"></a>ThresholdFilter</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="ThresholdFilter"><a class="anchor" href="#ThresholdFilter"></a>ThresholdFilter</h3>
<div class="paragraph">
<p>This filter returns the onMatch result if the level in the LogEvent is the same or more specific than the configured level and the <code>onMismatch</code>
value otherwise.
@@ -1717,10 +1701,8 @@ be ACCEPT, DENY or NEUTRAL. The default value is DENY.</p></td>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="TimeFilter"><a class="anchor" href="#TimeFilter"></a>TimeFilter</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="TimeFilter"><a class="anchor" href="#TimeFilter"></a>TimeFilter</h3>
<div class="paragraph">
<p>The time filter can be used to restrict the filter to only a certain portion of the day.</p>
</div>
@@ -1797,6 +1779,76 @@ be ACCEPT, DENY or NEUTRAL. The default value is DENY.</p></td>
</div>
</div>
</div>
+</div>
+<div class="sect1">
+<h2 id="extending"><a class="anchor" href="#extending"></a>Extending</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Filters are <a href="plugins.html" class="xref page">plugins</a> implementing <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/Filter.html">the <code>Filter</code> interface</a>.
+This section will guide you on how to create custom ones.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>While <a href="#collection">the predefined filter collection</a> should address most common use cases, you might find yourself needing to implement a custom one.
+If this is the case, we really appreciate it if you can <strong>share your use case in a <a href="https://logging.apache.org/support.html">user support channel</a></strong>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="sect2">
+<h3 id="extending-plugins"><a class="anchor" href="#extending-plugins"></a>Plugin preliminaries</h3>
+<div class="paragraph">
+<p>Log4j plugin system is the de facto extension mechanism embraced by various Log4j components.
+Plugins provide extension points to components, that can be used to implement new features, without modifying the original component.
+It is analogous to a <a href="https://en.wikipedia.org/wiki/Dependency_injection">dependency injection</a> framework, but curated for Log4j-specific needs.</p>
+</div>
+<div class="paragraph">
+<p>In a nutshell, you annotate your classes with <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/Plugin.html"><code>@Plugin</code></a> and their (<code>static</code>) factory methods with <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginFactory.html"><code>@PluginFactory</code></a>.
+Last, you inform the Log4j plugin system to discover these custom classes.
+This is done using running the <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/processor/PluginProcessor.html"><code>PluginProcessor</code></a> annotation processor while building your project.
+Refer to <a href="plugins.html" class="xref page">Plugins</a> for details.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="extending-filters"><a class="anchor" href="#extending-filters"></a>Extending filters</h3>
+<div class="paragraph">
+<p>Filter are <a href="plugins.html" class="xref page">plugins</a> implementing <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/Filter.html">the <code>Filter</code> interface</a>.
+We recommend users to extend from <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/filter/AbstractFilter.html"><code>AbstractFilter</code></a>, which provides implementation convenience.
+While annotating your filter with <code>@Plugin</code>, you need to make sure that</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>It has a unique <code>name</code> attribute across all available <code>Filter</code> plugins</p>
+</li>
+<li>
+<p>The <code>category</code> attribute is set to <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Node.html#CATEGORY"><code>Node.CATEGORY</code></a></p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>You can check out following files for examples:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core/src/main/java/org/apache/logging/log4j/core/filter/MarkerFilter.java"><code>MarkerFilter.java</code></a> – <a href="#MarkerFilter">MarkerFilter</a> matching on markers associated with the effective <code>LogEvent</code> in the context</p>
+</li>
+<li>
+<p><a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core/src/main/java/org/apache/logging/log4j/core/filter/RegexFilter.java"><code>RegexFilter.java</code></a> – <a href="#RegexFilter">RegexFilter</a> matching on the message associated with the effective <code>LogEvent</code> in the context</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
</article>
</div>
</main>
diff --git a/manual/flowtracing.html b/manual/flowtracing.html
index 37d669dc28..d205fc2561 100644
--- a/manual/flowtracing.html
+++ b/manual/flowtracing.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/garbagefree.html b/manual/garbagefree.html
index 80cba05566..f28c659edb 100644
--- a/manual/garbagefree.html
+++ b/manual/garbagefree.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -443,7 +443,7 @@ If not for yours, keep on reading.</p>
<p><a href="#core-properties">configure it using properties</a>,</p>
</li>
<li>
-<p>and employ garbage-free <a href="#Layouts">layouts</a>, <a href="#Appenders">appenders</a>, and <a href="#Filters">filters</a>.</p>
+<p>and employ garbage-free <a href="#Layouts">Layouts</a>, <a href="#Appenders">Appenders</a>, and <a href="#Filters">Filters</a>.</p>
</li>
</ul>
</div>
diff --git a/manual/getting-started.html b/manual/getting-started.html
index fb3dacc48a..93335b3e71 100644
--- a/manual/getting-started.html
+++ b/manual/getting-started.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/index.html b/manual/index.html
index 43225520ea..1fb59bcc89 100644
--- a/manual/index.html
+++ b/manual/index.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/installation.html b/manual/installation.html
index 121b1085b2..21edbbea19 100644
--- a/manual/installation.html
+++ b/manual/installation.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -1168,26 +1168,26 @@ rootLogger.appenderRef.0.ref = CONSOLE</code></pre>
<div class="content">
<div class="ulist tablist">
<ul>
-<li id="_tabs_12_log4j2_xml" class="tab">
-<p>log4j2.xml</p>
+<li id="_tabs_12_xml" class="tab">
+<p>XML</p>
</li>
-<li id="_tabs_12_log4j2_json" class="tab">
-<p>log4j2.json</p>
+<li id="_tabs_12_json" class="tab">
+<p>JSON</p>
</li>
-<li id="_tabs_12_log4j2_yaml" class="tab">
-<p>log4j2.yaml</p>
+<li id="_tabs_12_yaml" class="tab">
+<p>YAML</p>
</li>
-<li id="_tabs_12_log4j2_properties" class="tab">
-<p>log4j2.properties</p>
+<li id="_tabs_12_properties" class="tab">
+<p>Properties</p>
</li>
</ul>
</div>
-<div id="_tabs_12_log4j2_xml--panel" class="tabpanel" aria-labelledby="_tabs_12_log4j2_xml">
+<div id="_tabs_12_xml--panel" class="tabpanel" aria-labelledby="_tabs_12_xml">
<div class="paragraph">
<p>No dependency required.</p>
</div>
</div>
-<div id="_tabs_12_log4j2_json--panel" class="tabpanel" aria-labelledby="_tabs_12_log4j2_json">
+<div id="_tabs_12_json--panel" class="tabpanel" aria-labelledby="_tabs_12_json">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><dependency>
@@ -1199,7 +1199,7 @@ rootLogger.appenderRef.0.ref = CONSOLE</code></pre>
</div>
</div>
</div>
-<div id="_tabs_12_log4j2_yaml--panel" class="tabpanel" aria-labelledby="_tabs_12_log4j2_yaml">
+<div id="_tabs_12_yaml--panel" class="tabpanel" aria-labelledby="_tabs_12_yaml">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><dependency>
@@ -1211,7 +1211,7 @@ rootLogger.appenderRef.0.ref = CONSOLE</code></pre>
</div>
</div>
</div>
-<div id="_tabs_12_log4j2_properties--panel" class="tabpanel" aria-labelledby="_tabs_12_log4j2_properties">
+<div id="_tabs_12_properties--panel" class="tabpanel" aria-labelledby="_tabs_12_properties">
<div class="paragraph">
<p>No dependency required.</p>
</div>
@@ -1224,40 +1224,40 @@ rootLogger.appenderRef.0.ref = CONSOLE</code></pre>
<div class="content">
<div class="ulist tablist">
<ul>
-<li id="_tabs_13_log4j2_xml" class="tab">
-<p>log4j2.xml</p>
+<li id="_tabs_13_xml" class="tab">
+<p>XML</p>
</li>
-<li id="_tabs_13_log4j2_json" class="tab">
-<p>log4j2.json</p>
+<li id="_tabs_13_json" class="tab">
+<p>JSON</p>
</li>
-<li id="_tabs_13_log4j2_yaml" class="tab">
-<p>log4j2.yaml</p>
+<li id="_tabs_13_yaml" class="tab">
+<p>YAML</p>
</li>
-<li id="_tabs_13_log4j2_properties" class="tab">
-<p>log4j2.properties</p>
+<li id="_tabs_13_properties" class="tab">
+<p>Properties</p>
</li>
</ul>
</div>
-<div id="_tabs_13_log4j2_xml--panel" class="tabpanel" aria-labelledby="_tabs_13_log4j2_xml">
+<div id="_tabs_13_xml--panel" class="tabpanel" aria-labelledby="_tabs_13_xml">
<div class="paragraph">
<p>No dependency required.</p>
</div>
</div>
-<div id="_tabs_13_log4j2_json--panel" class="tabpanel" aria-labelledby="_tabs_13_log4j2_json">
+<div id="_tabs_13_json--panel" class="tabpanel" aria-labelledby="_tabs_13_json">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">runtimeOnly 'com.fasterxml.jackson.core:jackson-databind:2.17.1'</code></pre>
</div>
</div>
</div>
-<div id="_tabs_13_log4j2_yaml--panel" class="tabpanel" aria-labelledby="_tabs_13_log4j2_yaml">
+<div id="_tabs_13_yaml--panel" class="tabpanel" aria-labelledby="_tabs_13_yaml">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">runtimeOnly 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.17.1'</code></pre>
</div>
</div>
</div>
-<div id="_tabs_13_log4j2_properties--panel" class="tabpanel" aria-labelledby="_tabs_13_log4j2_properties">
+<div id="_tabs_13_properties--panel" class="tabpanel" aria-labelledby="_tabs_13_properties">
<div class="paragraph">
<p>No dependency required.</p>
</div>
diff --git a/manual/jmx.html b/manual/jmx.html
index 4ed77e71d9..066072759b 100644
--- a/manual/jmx.html
+++ b/manual/jmx.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/json-template-layout.html b/manual/json-template-layout.html
index e0478ab2b0..628465e8ff 100644
--- a/manual/json-template-layout.html
+++ b/manual/json-template-layout.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -3005,7 +3005,7 @@ If this is the case, we really appreciate it if you can <strong>share your use c
<h3 id="extending-plugins"><a class="anchor" href="#extending-plugins"></a>Plugin preliminaries</h3>
<div class="paragraph">
<p>Log4j plugin system is the de facto extension mechanism embraced by various Log4j components.
-Plugins make it possible for extensible components to <em>receive</em> feature implementations without any explicit links in between.
+Plugins provide extension points to components, that can be used to implement new features, without modifying the original component.
It is analogous to a <a href="https://en.wikipedia.org/wiki/Dependency_injection">dependency injection</a> framework, but curated for Log4j-specific needs.</p>
</div>
<div class="paragraph">
diff --git a/manual/layouts.html b/manual/layouts.html
index f977bcd4a9..df51618a2e 100644
--- a/manual/layouts.html
+++ b/manual/layouts.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -2066,7 +2066,7 @@ If this is the case, we really appreciate it if you can <strong>share your use c
<h3 id="extending-plugins"><a class="anchor" href="#extending-plugins"></a>Plugin preliminaries</h3>
<div class="paragraph">
<p>Log4j plugin system is the de facto extension mechanism embraced by various Log4j components.
-Plugins make it possible for extensible components to <em>receive</em> feature implementations without any explicit links in between.
+Plugins provide extension points to components, that can be used to implement new features, without modifying the original component.
It is analogous to a <a href="https://en.wikipedia.org/wiki/Dependency_injection">dependency injection</a> framework, but curated for Log4j-specific needs.</p>
</div>
<div class="paragraph">
@@ -2081,7 +2081,20 @@ Refer to <a href="plugins.html" class="xref page">Plugins</a> for details.</p>
<div class="paragraph">
<p>Layouts are <a href="plugins.html" class="xref page">plugins</a> implementing <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/Layout.html">the <code>Layout</code> interface</a>.
If your layout is a <code>String</code>-based one, we recommend you to extend your plugin class from <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/layout/AbstractStringLayout.html"><code>AbstractStringLayout</code></a>, which contains convenience for some of the boilerplate code shared by <code>String</code>-based layouts.
-You can check out following files for examples:</p>
+While annotating your layout with <code>@Plugin</code>, you need to make sure that</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>It has a unique <code>name</code> attribute across all available <code>Layout</code> plugins</p>
+</li>
+<li>
+<p>The <code>category</code> attribute is set to <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Node.html#CATEGORY"><code>Node.CATEGORY</code></a></p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>You can check out following files for examples:</p>
</div>
<div class="ulist">
<ul>
diff --git a/manual/logbuilder.html b/manual/logbuilder.html
index e645fdcd32..d8807bad86 100644
--- a/manual/logbuilder.html
+++ b/manual/logbuilder.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/logsep.html b/manual/logsep.html
index 66b1778838..76fb0bec5b 100644
--- a/manual/logsep.html
+++ b/manual/logsep.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/lookups.html b/manual/lookups.html
index 0f8927079b..fa8c94f591 100644
--- a/manual/lookups.html
+++ b/manual/lookups.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -343,9 +343,15 @@ page.</p>
</div>
</div>
<div class="sect1">
-<h2 id="ContextMapLookup"><a class="anchor" href="#ContextMapLookup"></a>Context Map Lookup</h2>
+<h2 id="collection"><a class="anchor" href="#collection"></a>Collection</h2>
<div class="sectionbody">
<div class="paragraph">
+<p>Log4j bundles several predefined lookups to assist in several common deployment use cases.
+Following sections explain all these in detail.</p>
+</div>
+<div class="sect2">
+<h3 id="ContextMapLookup"><a class="anchor" href="#ContextMapLookup"></a>Context Map Lookup</h3>
+<div class="paragraph">
<p>The ContextMapLookup allows applications to store data in the Log4j
ThreadContext Map and then retrieve the values in the Log4j
configuration. In the example below, the application would store the
@@ -365,10 +371,8 @@ resolve the variable for each event. Note that the pattern
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="DateLookup"><a class="anchor" href="#DateLookup"></a>Date Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="DateLookup"><a class="anchor" href="#DateLookup"></a>Date Lookup</h3>
<div class="paragraph">
<p>The DateLookup is somewhat unusual from the other lookups as it doesn’t
use the key to locate an item. Instead, the key can be used to specify a
@@ -388,10 +392,8 @@ be formatted as specified.</p>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="DockerLookup"><a class="anchor" href="#DockerLookup"></a>Docker Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="DockerLookup"><a class="anchor" href="#DockerLookup"></a>Docker Lookup</h3>
<div class="paragraph">
<p>The DockerLookup can be used to lookup attributes from the Docker container the application is running in.</p>
</div>
@@ -461,10 +463,8 @@ be formatted as specified.</p>
<p>This Lookup is subject to the requirements listed at <a href="../log4j-docker.html" class="xref page">Log4j Docker Support</a></p>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="environment-lookup"><a class="anchor" href="#environment-lookup"></a><a id="EnvironmentLookup"></a> Environment Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="environment-lookup"><a class="anchor" href="#environment-lookup"></a><a id="EnvironmentLookup"></a> Environment Lookup</h3>
<div class="paragraph">
<p>The EnvironmentLookup allows systems to configure environment variables,
either in global files such as /etc/profile or in the startup scripts
@@ -496,10 +496,8 @@ when the <code>USER</code> environment variable is undefined, the default value
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="EventLookup"><a class="anchor" href="#EventLookup"></a>Event Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="EventLookup"><a class="anchor" href="#EventLookup"></a>Event Lookup</h3>
<div class="paragraph">
<p>The EventLookup provides access to fields within the log event from the configuration.</p>
</div>
@@ -608,10 +606,8 @@ present in the log event.</p>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="JavaLookup"><a class="anchor" href="#JavaLookup"></a>Java Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="JavaLookup"><a class="anchor" href="#JavaLookup"></a>Java Lookup</h3>
<div class="paragraph">
<p>The JavaLookup allows Java environment information to be retrieved in
convenient preformatted strings using the <code>java:</code> prefix.</p>
@@ -697,10 +693,8 @@ convenient preformatted strings using the <code>java:</code> prefix.</p>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="JndiLookup"><a class="anchor" href="#JndiLookup"></a>JNDI Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="JndiLookup"><a class="anchor" href="#JndiLookup"></a>JNDI Lookup</h3>
<div class="paragraph">
<p>As of Log4j 2.15.1 JNDI operations require that <code>log4j2.enableJndi=true</code> be set as a system property or the
corresponding environment variable for this lookup to function. See the
@@ -733,10 +727,8 @@ or ip address are supported along with any hosts or ip addresses listed in the
<p><strong>Java’s JNDI module is not available on Android.</strong></p>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="JmxRuntimeInputArgumentsLookup"><a class="anchor" href="#JmxRuntimeInputArgumentsLookup"></a>JVM Input Arguments Lookup (JMX)</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="JmxRuntimeInputArgumentsLookup"><a class="anchor" href="#JmxRuntimeInputArgumentsLookup"></a>JVM Input Arguments Lookup (JMX)</h3>
<div class="paragraph">
<p>Maps JVM input arguments — but not <em>main</em> arguments — using JMX to
acquire the JVM arguments.</p>
@@ -752,15 +744,14 @@ acquire the JVM arguments.</p>
<p><strong>Java’s JMX module is not available on Android or on Google App Engine.</strong></p>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="KubernetesLookup"><a class="anchor" href="#KubernetesLookup"></a>Kubernetes Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="KubernetesLookup"><a class="anchor" href="#KubernetesLookup"></a>Kubernetes Lookup</h3>
<div class="paragraph">
<p>For retrieving attributes using Fabric8’s Kubernetes Client, see their <a href="https://github.com/fabric8io/kubernetes-client/blob/main/doc/KubernetesLog4j.md">Kubernetes Log4j Lookup</a>.</p>
</div>
</div>
</div>
+</div>
<div class="sect1">
<h2 id="Log4jConfigLookup"><a class="anchor" href="#Log4jConfigLookup"></a>Log4j Configuration Location Lookup</h2>
<div class="sectionbody">
@@ -783,11 +774,8 @@ relative to the log4j configuration file.</p>
</File></code></pre>
</div>
</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="LowerLookup"><a class="anchor" href="#LowerLookup"></a>Lower Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="LowerLookup"><a class="anchor" href="#LowerLookup"></a>Lower Lookup</h3>
<div class="paragraph">
<p>The LowerLookup converts the passed in argument to lower case. Presumably the value will be the
result of a nested lookup.</p>
@@ -802,10 +790,8 @@ result of a nested lookup.</p>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="AppMainArgsLookup"><a class="anchor" href="#AppMainArgsLookup"></a>Main Arguments Lookup (Application)</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="AppMainArgsLookup"><a class="anchor" href="#AppMainArgsLookup"></a>Main Arguments Lookup (Application)</h3>
<div class="paragraph">
<p>This lookup requires that you manually provide the main arguments of the
application to Log4j:</p>
@@ -838,9 +824,9 @@ key must be followed by a backslash as an escape character as in <code>${main:\-
<div class="paragraph">
<p>For example, suppose the static void main String[] arguments are:</p>
</div>
-<div class="literalblock">
+<div class="listingblock">
<div class="content">
-<pre>--file foo.txt --verbose -x bar</pre>
+<pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">--file foo.txt --verbose -x bar</code></pre>
</div>
</div>
<div class="paragraph">
@@ -909,10 +895,8 @@ key must be followed by a backslash as an escape character as in <code>${main:\-
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="MapLookup"><a class="anchor" href="#MapLookup"></a>Map Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="MapLookup"><a class="anchor" href="#MapLookup"></a>Map Lookup</h3>
<div class="paragraph">
<p>The MapLookup serves several purposes.</p>
</div>
@@ -964,10 +948,8 @@ page for information on how to set the default values.</p>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="marker-lookup"><a class="anchor" href="#marker-lookup"></a>Marker Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="marker-lookup"><a class="anchor" href="#marker-lookup"></a>Marker Lookup</h3>
<div class="paragraph">
<p>The marker lookup allows you to use markers in interesting
configurations like a routing appender. Consider the following YAML
@@ -1039,10 +1021,8 @@ check for the existence of a marker where <code>name</code> is the marker name.
the marker exists, the expression returns the name, otherwise <code>null</code>.</p>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="_resource_bundle_lookup"><a class="anchor" href="#_resource_bundle_lookup"></a>Resource Bundle Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="_resource_bundle_lookup"><a class="anchor" href="#_resource_bundle_lookup"></a>Resource Bundle Lookup</h3>
<div class="paragraph">
<p>The resource bundle lookup retrieves values from Resource Bundles (see Java documentation). The format is <code>${bundle:BundleName:BundleKey}</code>. The bundle name follows package naming conventions, for example: <code>${bundle:com.domain.Messages:MyKey}</code>.</p>
</div>
@@ -1056,10 +1036,8 @@ the marker exists, the expression returns the name, otherwise <code>null</code>.
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="_spring_boot_lookup"><a class="anchor" href="#_spring_boot_lookup"></a>Spring Boot Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="_spring_boot_lookup"><a class="anchor" href="#_spring_boot_lookup"></a>Spring Boot Lookup</h3>
<div class="paragraph">
<p>The Spring Boot Lookup retrieves the values of Spring properties from the Spring configuration as well as values of the active and default profiles. Specifying a key of "profiles.active" will return the active profiles while a key of "profiles.default" will return the default profiles. The default and active profiles can be an array. If more than one profile is present they will be returned as a comma separated list. To retrieve a single item from the array append "[{index}]" to the k [...]
</div>
@@ -1079,10 +1057,8 @@ the marker exists, the expression returns the name, otherwise <code>null</code>.
<p>This Lookup requires log4j-spring-cloud-config-client be included in the application.</p>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="StructuredDataLookup"><a class="anchor" href="#StructuredDataLookup"></a>Structured Data Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="StructuredDataLookup"><a class="anchor" href="#StructuredDataLookup"></a>Structured Data Lookup</h3>
<div class="paragraph">
<p>The StructuredDataLookup is very similar to the MapLookup in that it
will retrieve values from StructuredDataMessages. In addition to the Map
@@ -1111,10 +1087,8 @@ while "type" would have to be an item in the Map in a MapMessage.</p>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="system-properties-lookup"><a class="anchor" href="#system-properties-lookup"></a><a id="SystemPropertiesLookup"></a> System Properties Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="system-properties-lookup"><a class="anchor" href="#system-properties-lookup"></a><a id="SystemPropertiesLookup"></a> System Properties Lookup</h3>
<div class="paragraph">
<p>As it is quite common to define values inside and outside the
application by using System Properties, it is only natural that they
@@ -1142,10 +1116,8 @@ when the <code>logPath</code> system property is undefined, the default value
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="UpperLookup"><a class="anchor" href="#UpperLookup"></a>Upper Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="UpperLookup"><a class="anchor" href="#UpperLookup"></a>Upper Lookup</h3>
<div class="paragraph">
<p>The LowerLookup converts the passed in argument to upper case. Presumably the value will be the
result of a nested lookup.</p>
@@ -1160,10 +1132,8 @@ result of a nested lookup.</p>
</div>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="WebLookup"><a class="anchor" href="#WebLookup"></a>Web Lookup</h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="WebLookup"><a class="anchor" href="#WebLookup"></a>Web Lookup</h3>
<div class="paragraph">
<p>The WebLookup allows applications to retrieve variables that are
associated with the ServletContext. In addition to being able to
@@ -1247,6 +1217,75 @@ located then the corresponding value will be returned.</p>
</div>
</div>
</div>
+</div>
+<div class="sect1">
+<h2 id="extending"><a class="anchor" href="#extending"></a>Extending</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Lookups are <a href="plugins.html" class="xref page">plugins</a> implementing <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html">the <code>StrLookup</code> interface</a>.
+This section will guide you on how to create custom ones.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>While <a href="#collection">the predefined lookup collection</a> should address most common use cases, you might find yourself needing to implement a custom one.
+If this is the case, we really appreciate it if you can <strong>share your use case in a <a href="https://logging.apache.org/support.html">user support channel</a></strong>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="sect2">
+<h3 id="extending-plugins"><a class="anchor" href="#extending-plugins"></a>Plugin preliminaries</h3>
+<div class="paragraph">
+<p>Log4j plugin system is the de facto extension mechanism embraced by various Log4j components.
+Plugins provide extension points to components, that can be used to implement new features, without modifying the original component.
+It is analogous to a <a href="https://en.wikipedia.org/wiki/Dependency_injection">dependency injection</a> framework, but curated for Log4j-specific needs.</p>
+</div>
+<div class="paragraph">
+<p>In a nutshell, you annotate your classes with <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/Plugin.html"><code>@Plugin</code></a> and their (<code>static</code>) factory methods with <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginFactory.html"><code>@PluginFactory</code></a>.
+Last, you inform the Log4j plugin system to discover these custom classes.
+This is done using running the <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/processor/PluginProcessor.html"><code>PluginProcessor</code></a> annotation processor while building your project.
+Refer to <a href="plugins.html" class="xref page">Plugins</a> for details.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="extending-lookups"><a class="anchor" href="#extending-lookups"></a>Extending lookups</h3>
+<div class="paragraph">
+<p>Lookups are <a href="plugins.html" class="xref page">plugins</a> implementing <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html">the <code>StrLookup</code> interface</a>.
+While annotating your lookup with <code>@Plugin</code>, you need to make sure that</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>It has a unique <code>name</code> attribute across all available <code>StrLookup</code> plugins</p>
+</li>
+<li>
+<p>The <code>category</code> attribute is set to <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html#CATEGORY"><code>StrLookup.CATEGORY</code></a></p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>You can check out following files for examples:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/DateLookup.java"><code>LowerLookup.java</code></a> – <a href="#LowerLookup">Lower Lookup</a> lower-cases its input</p>
+</li>
+<li>
+<p><a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/EventLookup.java"><code>EventLookup.java</code></a> – <a href="#EventLookup">Event Lookup</a> extracts specified fields from the effective <code>LogEvent</code> in the context</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
</article>
</div>
</main>
diff --git a/manual/markers.html b/manual/markers.html
index 86a453908f..5d054e848e 100644
--- a/manual/markers.html
+++ b/manual/markers.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -439,9 +439,7 @@ complex hierarchies of markers where possible.</p>
<div class="sectionbody">
<div class="paragraph">
<p>Developers can use markers to filter the log statements delivered to log files.
-Marker processing is supported at least by
-<a href="https://logback.qos.ch/manual/filters.html">Logback</a>
-and the Log4j Core logging backends.
+Marker processing is supported at least by <a href="https://logback.qos.ch/manual/filters.html">Logback</a> and the Log4j Core logging implementations.
We will provide a sample configuration for both these backends.</p>
</div>
<div class="sect2">
diff --git a/manual/messages.html b/manual/messages.html
index b6aba6b281..53be72c8a1 100644
--- a/manual/messages.html
+++ b/manual/messages.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/migration.html b/manual/migration.html
index babcc61afb..38fc46a591 100644
--- a/manual/migration.html
+++ b/manual/migration.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -803,7 +803,7 @@ and require the <a href="#log4j-1-2-api-installation">installation of the Log4j
</li>
<li>
<p>If your Log4j 1 native component is not supported by the Log4j 1 to Log4j 2 bridge, we suggest to rewrite it directly as Log4j 2 component.
-See <a href="extending.html" class="xref page">Extending Log4j</a> for more details.</p>
+See <a href="extending.html" class="xref page">Extending</a> for more details.</p>
</li>
</ol>
</div>
diff --git a/manual/pattern-layout.html b/manual/pattern-layout.html
index a93ed329d4..6cc9ed0f44 100644
--- a/manual/pattern-layout.html
+++ b/manual/pattern-layout.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -2702,9 +2702,9 @@ Format modifiers to control such things as field width, padding, left, and right
<td class="tableblock halign-left valign-top" style="background-color: white;"></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top" style="background-color: white;"><p class="tableblock"><code><a href="#converter-thread-context-map[%X{key">,key2…​\</a>}<br>
+<td class="tableblock halign-left valign-top" style="background-color: white;"><p class="tableblock"><code><a href="#converter-thread-context-map[%X{key">,key2…​\}<br>
%mdc{key[,key2…​\]}<br>
-%MDC{key[,key2…​\]}]</code></p></td>
+%MDC{key[,key2…​\]}</a></code></p></td>
<td class="tableblock halign-left valign-top" style="background-color: white;"></td>
</tr>
<tr>
@@ -2820,7 +2820,7 @@ If this is the case, we really appreciate it if you can <strong>share your use c
<h3 id="extending-plugins"><a class="anchor" href="#extending-plugins"></a>Plugin preliminaries</h3>
<div class="paragraph">
<p>Log4j plugin system is the de facto extension mechanism embraced by various Log4j components.
-Plugins make it possible for extensible components to <em>receive</em> feature implementations without any explicit links in between.
+Plugins provide extension points to components, that can be used to implement new features, without modifying the original component.
It is analogous to a <a href="https://en.wikipedia.org/wiki/Dependency_injection">dependency injection</a> framework, but curated for Log4j-specific needs.</p>
</div>
<div class="paragraph">
diff --git a/manual/performance.html b/manual/performance.html
index 9e8d92711e..071df5bb23 100644
--- a/manual/performance.html
+++ b/manual/performance.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/plugins.html b/manual/plugins.html
index 54115ad1b1..09c9ae6a3a 100644
--- a/manual/plugins.html
+++ b/manual/plugins.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
@@ -331,146 +331,435 @@
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
-<p>Log4j 1.x allowed for extension by requiring class attributes on most of the configuration declarations. In the case of some elements, notably the PatternLayout, the only way to add new pattern converters was to extend the PatternLayout class and add them via code. One goal of Log4j 2 is to make extending it extremely easy through the use of plugins.</p>
+<p>Log4j plugin system is the de facto extension mechanism embraced by various Log4j Core components.
+Plugins make it possible for extensible components to <em>receive</em> feature implementations without any explicit links in between.
+It is analogous to a <a href="https://en.wikipedia.org/wiki/Dependency_injection">dependency injection</a> framework, but curated for Log4j-specific needs.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Log4j plugin system is implemented by Log4j Core, the logging implementation.
+It is deliberately not a part of the Log4j API to keep the logging API footprint small.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Did you know about <strong><a href="../plugin-reference.html" class="xref page">Plugin reference</a>, the documentation extracted from the source code</strong> of all predefined Log4j plugins?
+Like Javadoc, but specialized for plugins!</p>
+</div>
+</td>
+</tr>
+</table>
</div>
<div class="paragraph">
-<p>In Log4j 2 a plugin is declared by adding a <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/Plugin.html"><code>@Plugin</code></a> annotation to the class declaration. During initialization the <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html"><code>Configuration</code></a> will invoke the <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/util/PluginManager.html"><code>PluginManager</code></a> t [...]
+<p>In this section we will give an overview of the Log4j plugin system by answering certain questions:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
-<p>Serialized plugin listing files on the classpath. These files are generated automatically during the build (more details below).</p>
+<p><a href="#declare-plugin">How can you declare a plugin?</a></p>
</li>
<li>
-<p>(OSGi only) Serialized plugin listing files in each active OSGi bundle. A <code>BundleListener</code> is added on activation to continue checking new bundles after <code>log4j-core</code> has started.</p>
+<p><a href="#core">How can you declare a plugin that needs to be represented in a Log4j configuration file?</a></p>
</li>
<li>
-<p><strong>(Deprecated)</strong> A comma-separated list of packages specified by the <code>log4j.plugin.packages</code> system property.</p>
+<p><a href="#plugin-registry">How can you register your plugin to Log4j?</a></p>
</li>
<li>
-<p><strong>(Deprecated)</strong> Packages passed to the static <code>PluginManager.addPackages</code> method (before Log4j configuration occurs).</p>
+<p><a href="#plugin-discovery">How does Log4j discover plugins?</a></p>
</li>
<li>
-<p><strong>(Deprecated)</strong> The [packages](./configuration.html#ConfigurationSyntax) declared in your log4j2 configuration file.</p>
+<p><a href="#plugin-load">How can you load other plugins in a plugin?</a></p>
</li>
</ol>
</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="declare-plugin"><a class="anchor" href="#declare-plugin"></a>Declaring plugins</h2>
+<div class="sectionbody">
<div class="paragraph">
-<p>If multiple Plugins specify the same (case-insensitive) <code>name</code>, then the load order above determines which one will be used. For example, to override the <code>File</code> plugin which is provided by the built-in <code>FileAppender</code> class, you would need to place your plugin in a JAR file in the CLASSPATH ahead of`log4j-core.jar`. This is not recommended; plugin name collisions will cause a warning to be emitted. Note that in an OSGi environment, the order that bundle [...]
+<p>A class can be declared as a plugin by adding a <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/Plugin.html"><code>@Plugin</code></a> annotation, which is essentially composed of following attributes:</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><code>name</code></dt>
+<dd>
+<p>Name of the plugin.
+It is recommended to be distinct among plugins sharing the same <code>category</code>.
+<code>name</code> matching is case-insensitive.</p>
+</dd>
+<dt class="hdlist1"><code>category</code> (optional)</dt>
+<dd>
+<p>A name used for grouping a set of plugins.
+<code>category</code> matching is case-sensitive.</p>
+</dd>
+<dt class="hdlist1"><code>elementType</code> (deprecated)</dt>
+<dd>
+<p>We don’t recommend the usage of <code>elementType</code> anymore.
+Existing usages are kept for backward compatibility reasons with the legacy configuration syntax: <code><appender type="ConsoleAppender"</code>.</p>
+</dd>
+</dl>
</div>
<div class="paragraph">
-<p>Serialized plugin listing files are generated by an annotation processor contained in the log4j-core artifact which will automatically scan your code for Log4j 2 plugins and output a metadata file in your processed classes. There is nothing extra that needs to be done to enable this; the Java compiler will automatically pick up the annotation processor on the class path unless you explicitly disable it. In that case, it would be important to add another compiler pass to your build pro [...]
+<p>See <a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/LowerLookup.java"><code>LowerLookup.java</code></a> (a <a href="lookups.html" class="xref page">lookup</a> for lower-casing its input) for a simple example.</p>
</div>
-<div class="listingblock">
+<details>
+<summary class="title">Click to read more on <strong>name collision</strong> and <strong>overriding an existing plugin</strong></summary>
<div class="content">
-<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <version>3.1</version>
- <executions>
- <execution>
- <id>log4j-plugin-processor</id>
- <goals>
- <goal>compile</goal>
- </goals>
- <phase>process-classes</phase>
- <configuration>
- <proc>only</proc>
- <annotationProcessors>
- <annotationProcessor>org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor</annotationProcessor>
- </annotationProcessors>
- </configuration>
- </execution>
- </executions>
-</plugin></code></pre>
+<div class="paragraph">
+<p>The <code>name</code> attribute of plugins of a certain <code>category</code> is recommended to be distinct and this matching is case-insensitive.
+In case of a name collision, a warning will be emitted, and the plugin <a href="#plugin-discovery">discovery order</a> will determine the effective plugin.
+For example, to override the <code>File</code> plugin which is provided by the built-in <a href="appenders.html#FileAppender" class="xref page">File Appender</a>, you would need to place your plugin in a JAR file in the classpath ahead of Log4j Core JAR.
+In an OSGi environment, the order that bundles are scanned for plugins generally follows the same order that bundles were installed into the framework; see <a href="https://www.osgi.org/javadoc/r5/core/org/osgi/framework/BundleContext.html#getBundles()"><code>getBundles()</code></a> and <a href="https://www.osgi.org/javadoc/r5/core/org/osgi/framework/SynchronousBundleListener.html"><code>SynchronousBundleListener</code></a>.
+In short, name collisions are even more unpredictable in an OSGi environment.</p>
</div>
</div>
+</details>
</div>
</div>
<div class="sect1">
-<h2 id="core"><a class="anchor" href="#core"></a>Core</h2>
+<h2 id="core"><a class="anchor" href="#core"></a>Declaring plugins represented in a configuration file</h2>
<div class="sectionbody">
<div class="paragraph">
-<p>Core plugins are those that are directly represented by an element in a configuration file, such as an Appender, Layout, Logger or Filter. Custom plugins that conform to the rules laid out in the next paragraph may simply be referenced in the configuration, provided they are appropriate configured to be loaded by the PluginManager.</p>
+<p>If your plugin needs to be represented by an element in a configuration file (such as an <a href="appenders.html" class="xref page">appender</a>, <a href="layouts.html" class="xref page">layout</a>, <a href="api.html#loggers" class="xref page">logger</a>, or <a href="filters.html" class="xref page">filter</a>), following requirements must be met:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>The <code>category</code> attribute of the <code>@Plugin</code> annotation must be set to <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/Node.html#CATEGORY"><code>Node.CATEGORY</code></a> (<code>Core</code>)</p>
+</li>
+<li>
+<p>It must have a <a href="#declare-plugin-factory">plugin factory</a></p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>Every Core plugin must declare a static method annotated with @PluginFactory or @PluginBuilderFactory. The former is used for static factory methods that provide all options as method parameters, and the latter is used to construct a new Builder<T> class whose fields are used for injecting attributes and child nodes. To allow the Configuration to pass the correct parameters to the method, every parameter to the method must be annotated as one of the following attribute types. Ea [...]
+<p>See <a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-layout-template-json/src/main/java/org/apache/logging/log4j/layout/template/json/JsonTemplateLayout.java"><code>JsonTemplateLayout.java</code></a> for an example and notice these details:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>There are two plugin declarations: <code>JsonTemplateLayout</code> and <code>JsonTemplateLayout.EventTemplateAdditionalField</code></p>
+</li>
+<li>
+<p>Both plugin declarations</p>
+<div class="ulist">
+<ul>
+<li>
+<p>Set the <code>category</code> attribute to <code>Node.CATEGORY</code></p>
+</li>
+<li>
+<p>Provide a <code>@PluginBuilderFactory</code>-annotated static method</p>
+</li>
+</ul>
+</div>
+</li>
+</ul>
</div>
<div class="sect2">
-<h3 id="attribute-types"><a class="anchor" href="#attribute-types"></a>Attribute types</h3>
+<h3 id="declare-plugin-factory"><a class="anchor" href="#declare-plugin-factory"></a>Declaring plugin factories</h3>
+<div class="paragraph">
+<p>A <strong>plugin factory</strong> is responsible for</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Creating an instance of the plugin</p>
+</li>
+<li>
+<p>Receiving values (<code>Configuration</code> instance, configuration attributes, etc.) available in the context</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Every plugin that needs to be represented by an element in a configuration file must declare a plugin factory using one of the following:</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1">a <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginFactory.html"><code>@PluginFactory</code></a>-annotated static method</dt>
+<dd>
+<p>What is expected to be received is modelled as method arguments.
+Intended for simple plugins that receive less than a handful of values.</p>
+<div class="paragraph">
+<p>See <a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core/src/main/java/org/apache/logging/log4j/core/layout/CsvParameterLayout.java"><code>CsvParameterLayout.java</code></a> for an example on <code>@PluginFactory</code> usage.</p>
+</div>
+</dd>
+<dt class="hdlist1">a <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginBuilderFactory.html"><code>@PluginBuilderFactory</code></a>-annotated static method of return type <a href="../javadoc/log4j-core/src/main/java/org/apache/logging/log4j/core/util/Builder.java"><code>Builder<T></code></a></dt>
+<dd>
+<p>What is expected to be received is modelled as fields of a builder class.
+Intended for more sophisticated wiring needs.</p>
+<details>
+<summary class="title">Click for advantages of builder class over factory method</summary>
+<div class="content">
<div class="ulist">
<ul>
<li>
-<p>PluginAttribute: The parameter must be convertible from a String using a TypeConverter. Most built-in types are already supported, but custom TypeConverter plugins may also be provided for more type support. Note that PluginBuilderAttribute can be used in builder class fields as an easier way to provide default values.</p>
+<p>Attribute names don’t need to be specified, if they match the field name</p>
</li>
<li>
-<p>PluginElement: The parameter may represent a complex object that itself has parameters that can be configured. This also supports injecting an array of elements.</p>
+<p>Default values can be specified in code rather than through an annotation.
+This also allows a runtime-calculated default value, which isn’t allowed in annotations.</p>
</li>
<li>
-<p>PluginConfiguration: The current Configuration object will be passed to the plugin as a parameter.</p>
+<p>Default values are specified via code rather than relying on reflection and injection, so they work programmatically as well as in a configuration file.</p>
</li>
<li>
-<p>PluginNode: The current Node being parsed will be passed to the plugin as a parameter.</p>
+<p>Adding new optional parameters doesn’t require existing programmatic configuration to be refactored.</p>
</li>
<li>
-<p>PluginValue: The value of the current Node or its attribute named value.</p>
+<p>Easier to write unit tests using builders rather than factory methods with optional parameters.</p>
</li>
</ul>
</div>
</div>
-<div class="sect2">
-<h3 id="constraint-validators"><a class="anchor" href="#constraint-validators"></a>Constraint validators</h3>
+</details>
+<div class="paragraph">
+<p>See <a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-layout-template-json/src/main/java/org/apache/logging/log4j/layout/template/json/JsonTemplateLayout.java"><code>JsonTemplateLayout.java</code></a> for an example on <code>@PluginBuilderFactory</code> usage.</p>
+</div>
+</dd>
+</dl>
+</div>
+<div class="paragraph">
+<p>If a plugin class implements <code>Collection</code> or <code>Map</code>, then no factory method is used.
+Instead, the class is instantiated using the default constructor, and all child configuration nodes are added to the <code>Collection</code> or <code>Map</code>.</p>
+</div>
+<div class="sect3">
+<h4 id="attribute-types"><a class="anchor" href="#attribute-types"></a>Plugin factory attribute types</h4>
+<div class="paragraph">
+<p>To allow the current <code>Configuration</code> to populate the correct arguments for the <code>@PluginFactory</code>-annotated method (or fields for the builder class), every argument to the method must be annotated using one of the following attribute types.</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginAliases.html"><code>@PluginAliases</code></a></dt>
+<dd>
+<p>Identifies a list of aliases for a <code>@Plugin</code>, <code>@PluginAttribute</code>, or <code>@PluginBuilderAttribute</code></p>
+</dd>
+<dt class="hdlist1"><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginAttribute.html"><code>@PluginAttribute</code></a></dt>
+<dd>
+<p>Denotes a configuration element attribute.
+The parameter must be convertible from a <code>String</code> using a <code>TypeConverter</code>.
+Most built-in types are already supported, but custom <code>TypeConverter</code> plugins may also be provided for more type support.
+Note that <code>PluginBuilderAttribute</code> can be used in builder class fields as an easier way to provide default values.</p>
+</dd>
+<dt class="hdlist1"><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginConfiguration.html"><code>@PluginConfiguration</code></a></dt>
+<dd>
+<p>The current <code>Configuration</code> object will be passed to the plugin as a parameter.</p>
+</dd>
+<dt class="hdlist1"><a id="PluginElement"></a> <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginElement.html"><code>@PluginElement</code></a></dt>
+<dd>
+<p>The parameter may represent a complex object that itself has parameters that can be configured.
+This also supports injecting an array of elements.</p>
+</dd>
+<dt class="hdlist1"><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginNode.html"><code>@PluginNode</code></a></dt>
+<dd>
+<p>The current <code>Node</code> being parsed will be passed to the plugin as a parameter.</p>
+</dd>
+<dt class="hdlist1"><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/PluginValue.html"><code>@PluginValue</code></a></dt>
+<dd>
+<p>The value of the current <code>Node</code> or its attribute named <code>value</code>.</p>
+</dd>
+</dl>
+</div>
+<div class="paragraph">
+<p>Each attribute or element annotation must include the name that must be present in the configuration in order to match the configuration item to its respective parameter.
+For plugin builders, the names of the fields will be used by default if no name is specified in the annotation.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="type-converters"><a class="anchor" href="#type-converters"></a>Plugin factory attribute type converters</h4>
<div class="paragraph">
-<p>Plugin factory fields and parameters can be automatically validated at runtime using constraint validators inspired by the Bean Validation spec. The following annotations are bundled in Log4j, but custom ConstraintValidators can be created as well.</p>
+<p><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/convert/TypeConverter.html"><code>TypeConverter</code></a>s are a certain group of plugins for converting <code>String</code>s read from configuration file elements into the types used in plugin factory attributes.
+Other plugins can already be injected via <a href="#PluginElement">the <code>@PluginElement</code> annotation</a>; now, any type supported by <code>TypeConverter</code>s can be used in a <code>@PluginAttribute</code>-annotated factory attribute.</p>
+</div>
+<div class="paragraph">
+<p>Conversion of enum types are supported on demand and do not require custom <code>TypeConverter</code>s.
+A large number of built-in Java classes (<code>int</code>, <code>long</code>, <code>BigDecimal</code>, etc.) are already supported; see <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/convert/TypeConverters.html"><code>TypeConverters</code></a> for a more exhaustive listing.</p>
+</div>
+<div class="paragraph">
+<p>You can create custom <code>TypeConverter</code>s as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>Required: This annotation validates that a value is non-empty. This covers a check for null as well as several other scenarios: empty CharSequence objects, empty arrays, empty Collection instances, and empty Map instances.</p>
+<p>Extend from <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/convert/TypeConverter.html">the <code>TypeConverter</code> interface</a></p>
+</li>
+<li>
+<p>Set the <code>category</code> attribute of the <code>@Plugin</code> annotation to <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/convert/TypeConverters.html#CATEGORY"><code>TypeConverters.CATEGORY</code></a> (<code>TypeConverter</code>).
+Unlike other plugins, the plugin name of a <code>TypeConverter</code> is purely cosmetic.</p>
</li>
<li>
-<p>ValidHost: This annotation validates that a value corresponds to a valid hostname. This uses the same validation as InetAddress::getByName.</p>
+<p>Have a default constructor</p>
</li>
<li>
-<p>ValidPort: This annotation validates that a value corresponds to a valid port number between 0 and 65535.</p>
+<p>Optionally, extend from <code>Comparable<TypeConverter<?>></code>, which will be used for determining the order in case of multiple <code>TypeConverter</code> candidates for a certain type</p>
</li>
</ul>
</div>
+<div class="paragraph">
+<p>See <a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-core/org/apache/logging/log4j/core/config/plugins/convert/TypeConverters.java"><code>TypeConverters.java</code></a> for example implementations.</p>
</div>
</div>
-</div>
-<div class="sect1">
-<h2 id="key-providers"><a class="anchor" href="#key-providers"></a>Key providers</h2>
-<div class="sectionbody">
+<div class="sect3">
+<h4 id="constraint-validators"><a class="anchor" href="#constraint-validators"></a>Plugin factory attribute validators</h4>
<div class="paragraph">
-<p>Some components within Log4j may provide the ability to perform data encryption. These components require a secret key to perform the encryption. Applications may provide the key by creating a class that implements the SecretKeyProvider interface.</p>
+<p>Plugin factory fields and parameters can be automatically validated at runtime using constraint validators inspired by <a href="https://beanvalidation.org">Bean Validation</a>.
+The following annotations are bundled in Log4j, but custom <code>ConstraintValidator</code> can be created as well.</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/validation/constraints/Required.html"><code>@Required</code></a></dt>
+<dd>
+<p>This annotation validates that a value is non-empty.
+This covers a check for null as well as several other scenarios: empty <code>CharSequence</code> objects, empty arrays, empty <code>Collection</code> instances, and empty <code>Map</code> instances.</p>
+</dd>
+<dt class="hdlist1"><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidHost.html"><code>@ValidHost</code></a></dt>
+<dd>
+<p>This annotation validates that a value corresponds to a valid host name.
+This uses the same validation as <a href="https://docs.oracle.com/javase/8/docs/api/java/net/InetAddress.html#getByName-java.lang.String-"><code>InetAddress.getByName(String)</code></a>.</p>
+</dd>
+<dt class="hdlist1"><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidPort.html"><code>@ValidPort</code></a></dt>
+<dd>
+<p>This annotation validates that a value corresponds to a valid port number between 0 and 65535.</p>
+</dd>
+</dl>
+</div>
+</div>
</div>
</div>
</div>
<div class="sect1">
-<h2 id="lookups"><a class="anchor" href="#lookups"></a>Lookups</h2>
+<h2 id="plugin-registry"><a class="anchor" href="#plugin-registry"></a>Registering plugins</h2>
<div class="sectionbody">
<div class="paragraph">
-<p>Lookups are perhaps the simplest plugins of all. They must declare their type as "Lookup" on the plugin annotation and must implement the StrLookup interface. They will have two methods; a lookup method that accepts a String key and returns a String value and a second lookup method that accepts both a LogEvent and a String key and returns a String. Lookups may be referenced by specifying ${name:key} where name is the name specified in the Plugin annotation and key is the name of the i [...]
+<p>Registering plugins are done by placing a <strong>Log4j plugin descriptor</strong> (i.e., <code>Log4j2Plugins.dat</code>) into the classpath.
+This file is generated using the <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/processor/PluginProcessor.html"><code>PluginProcessor</code></a> annotation processor at compile-time.
+You need to configure your build tool as follows to employ <code>PluginProcessor</code> by the Java compiler:</p>
+</div>
+<div id="_tabs_1" class="openblock tabs is-sync is-loading">
+<div class="content">
+<div class="ulist tablist">
+<ul>
+<li id="_tabs_1_maven" class="tab">
+<p>Maven</p>
+</li>
+<li id="_tabs_1_gradle" class="tab">
+<p>Gradle</p>
+</li>
+</ul>
+</div>
+<div id="_tabs_1_maven--panel" class="tabpanel" aria-labelledby="_tabs_1_maven">
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>${maven-compiler-plugin.version}</version>
+ <executions>
+ <execution>
+ <id>generate-log4j-plugin-descriptor</id>
+ <goals>
+ <goal>compile</goal>
+ </goals>
+ <phase>process-classes</phase>
+ <configuration>
+ <proc>only</proc>
+ <annotationProcessorPaths>
+ <!-- Include `log4j-core` providing `org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor` that generates `Log4j2Plugins.dat` -->
+ <path>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-core</artifactId>
+ <version>2.23.1</version>
+ </path>
+ </annotationProcessorPaths>
+ <annotationProcessors>
+ <!-- Process sources using `org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor` to generate `Log4j2Plugins.dat` -->
+ <processor>org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor</processor>
+ </annotationProcessors>
+ </configuration>
+ </execution>
+ </executions>
+</plugin></code></pre>
+</div>
+</div>
+</div>
+<div id="_tabs_1_gradle--panel" class="tabpanel" aria-labelledby="_tabs_1_gradle">
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">dependencies {
+ // Process sources using `log4j-core` providing `org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor` that generates `Log4j2Plugins.dat` -->
+ annotationProcessor('org.apache.logging.log4j:log4j-core:2.23.1')
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
</div>
</div>
</div>
<div class="sect1">
-<h2 id="type-converters"><a class="anchor" href="#type-converters"></a>Type converters</h2>
+<h2 id="plugin-discovery"><a class="anchor" href="#plugin-discovery"></a>Discovering plugins</h2>
<div class="sectionbody">
<div class="paragraph">
-<p>TypeConverters are a sort of meta-plugin used for converting strings into other types in a plugin factory method parameter. Other plugins can already be injected via the @PluginElement annotation; now, any type supported by the type conversion system can be used in a @PluginAttribute parameter. Conversion of enum types are supported on demand and do not require custom TypeConverter classes. A large number of built-in Java classes are already supported; see TypeConverters for a more ex [...]
+<p><a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/util/PluginManager.html"><code>PluginManager</code></a> is responsible for discovering plugins and loading their descriptions.
+It locates plugins by looking in following places in given order:</p>
</div>
-<div class="paragraph">
-<p>Unlike other plugins, the plugin name of a TypeConverter is purely cosmetic. Appropriate type converters are looked up via the Type interface rather than via Class<?> objects only. Do note that TypeConverter plugins must have a default constructor. When multiple converters match for a type, the first will be returned. If any extends from Comparable<TypeConverter<?>>, it will be used for determining the order.</p>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>Plugin descriptor files on the classpath (using the class loader that loaded the <code>log4j-core</code> artifact).
+These files are generated automatically at compile-time by the Log4j plugin annotation processor.
+See <a href="#plugin-registry">Registering plugins</a> for details.</p>
+</li>
+<li>
+<p><strong>[OSGi only]</strong> Serialized plugin listing files in each active OSGi bundle.
+A <code>BundleListener</code> is added on activation to continue checking new bundles after Log4j Core has started.</p>
+</li>
+<li>
+<p><strong>[Deprecated]</strong> A comma-separated list of packages specified by the <code>log4j.plugin.packages</code> system property</p>
+</li>
+<li>
+<p><strong>[Deprecated]</strong> Packages passed to the static <code>PluginManager.addPackages()</code> method before Log4j configuration takes place</p>
+</li>
+<li>
+<p><strong>[Deprecated]</strong> The <code>packages</code> attribute declared at the root element of your Log4j configuration file</p>
+</li>
+</ol>
</div>
</div>
</div>
<div class="sect1">
-<h2 id="developer-notes"><a class="anchor" href="#developer-notes"></a>Developer notes</h2>
+<h2 id="plugin-load"><a class="anchor" href="#plugin-load"></a>Loading plugins</h2>
<div class="sectionbody">
<div class="paragraph">
-<p>If a plugin class implements Collection or Map, then no factory method is used. Instead, the class is instantiated using the default constructor, and all child configuration nodes are added to the Collection or Map.</p>
+<p>It is pretty common that a plugin uses other plugins; appenders accept layouts, some layouts accept key-value pairs, etc.
+You can do this as follows:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>If your plugin has a <a href="#declare-plugin-factory">plugin factory</a> (i.e., it is represented by a configuration file element), you can use <a href="#PluginElement">the <code>@PluginElement</code> annotation</a> to receive other plugins.
+See <code>@PluginElement("EventTemplateAdditionalField")</code> usage in <a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-layout-template-json/src/main/java/org/apache/logging/log4j/layout/template/json/JsonTemplateLayout.java"><code>JsonTemplateLayout.java</code></a> for an example.</p>
+</li>
+<li>
+<p>Otherwise, you can use <a href="../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/util/PluginUtl.html"><code>PluginUtil</code></a>, which is a convenient wrapper around <a href="#plugin-discovery"><code>PluginManager</code></a>, to discover and load plugins.
+See <a href="https://github.com/apache/logging-log4j2/tree/2.x/log4j-layout-template-json/src/main/java/org/apache/logging/log4j/layout/template/json/resolver/TemplateResolverFactories.java"><code>TemplateResolverFactories.java</code></a> for example usages.</p>
+</li>
+</ul>
</div>
</div>
</div>
diff --git a/manual/resource-logger.html b/manual/resource-logger.html
index 9e29bb3373..6ad52a9b18 100644
--- a/manual/resource-logger.html
+++ b/manual/resource-logger.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/scoped-context.html b/manual/scoped-context.html
index 4cfca18f9e..cf1623cda9 100644
--- a/manual/scoped-context.html
+++ b/manual/scoped-context.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/scripts.html b/manual/scripts.html
index 19abc4d06b..5ace0b70b6 100644
--- a/manual/scripts.html
+++ b/manual/scripts.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/simple-logger.html b/manual/simple-logger.html
index d59dd99c5b..846c35d253 100644
--- a/manual/simple-logger.html
+++ b/manual/simple-logger.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/status-logger.html b/manual/status-logger.html
index fe791cf026..989c5cde59 100644
--- a/manual/status-logger.html
+++ b/manual/status-logger.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/systemproperties.html b/manual/systemproperties.html
index fb4e4ed472..8e31bc0690 100644
--- a/manual/systemproperties.html
+++ b/manual/systemproperties.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/thread-context.html b/manual/thread-context.html
index c7038fd6db..954e8df1b7 100644
--- a/manual/thread-context.html
+++ b/manual/thread-context.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/manual/webapp.html b/manual/webapp.html
index 6341db173a..b469ed7f46 100644
--- a/manual/webapp.html
+++ b/manual/webapp.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="appenders.html">Appenders</a>
diff --git a/migrate-from-logback.html b/migrate-from-logback.html
index 4f80152248..915b8ee149 100644
--- a/migrate-from-logback.html
+++ b/migrate-from-logback.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/migrate-from-slf4j.html b/migrate-from-slf4j.html
index 38483ca1fd..a83dc3bc3a 100644
--- a/migrate-from-slf4j.html
+++ b/migrate-from-slf4j.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/plugin-reference.html b/plugin-reference.html
index 5d1522262c..39c278a8c9 100644
--- a/plugin-reference.html
+++ b/plugin-reference.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
@@ -16136,10 +16136,10 @@ Supports Lookup expressions.</p>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>boolean?</code></p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
-<p>If "true", includes the stacktrace of any Throwable in the generated JSON, defaults to "true".</p>
+<p>If "true", includes the stacktrace of any Throwable in the generated data, defaults to "true".</p>
</div>
<div class="paragraph">
-<p>If "true", includes the stacktrace of any Throwable in the generated data, defaults to "true".</p>
+<p>If "true", includes the stacktrace of any Throwable in the generated JSON, defaults to "true".</p>
</div></div></td>
</tr>
<tr>
@@ -17435,10 +17435,10 @@ Supports Lookup expressions.</p>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>boolean?</code></p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
-<p>If "true", includes the stacktrace of any Throwable in the generated JSON, defaults to "true".</p>
+<p>If "true", includes the stacktrace of any Throwable in the generated data, defaults to "true".</p>
</div>
<div class="paragraph">
-<p>If "true", includes the stacktrace of any Throwable in the generated data, defaults to "true".</p>
+<p>If "true", includes the stacktrace of any Throwable in the generated JSON, defaults to "true".</p>
</div></div></td>
</tr>
<tr>
@@ -17634,10 +17634,10 @@ Supports Lookup expressions.</p>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>boolean?</code></p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
-<p>If "true", includes the stacktrace of any Throwable in the generated JSON, defaults to "true".</p>
+<p>If "true", includes the stacktrace of any Throwable in the generated data, defaults to "true".</p>
</div>
<div class="paragraph">
-<p>If "true", includes the stacktrace of any Throwable in the generated data, defaults to "true".</p>
+<p>If "true", includes the stacktrace of any Throwable in the generated JSON, defaults to "true".</p>
</div></div></td>
</tr>
<tr>
diff --git a/release-notes.html b/release-notes.html
index 60eb5d6366..a89f62d4f0 100644
--- a/release-notes.html
+++ b/release-notes.html
@@ -161,7 +161,7 @@
<a class="nav-link" href="manual/systemproperties.html">Configuration properties</a>
</li>
<li class="nav-item" data-depth="2">
- <a class="nav-link" href="manual/customconfig.html">Programmatic Configuration</a>
+ <a class="nav-link" href="manual/customconfig.html">Programmatic configuration</a>
</li>
<li class="nav-item" data-depth="2">
<a class="nav-link" href="manual/appenders.html">Appenders</a>
diff --git a/sitemap.xml b/sitemap.xml
index 2fe4f25a6f..fc6fd02bb0 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,250 +2,250 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://logging.apache.org/log4j/2.x/development.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/download.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/faq.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/hibernate.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/index.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/javadoc.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-appserver.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-cassandra.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-couchdb.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-docker.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-flume-ng.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-iostreams.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-jakarta-web.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-jul.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-spring-boot.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-spring-cloud-config-client.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-spring-cloud-config.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-taglib.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-to-jul.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/log4j-web.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/api.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/appenders.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/architecture.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/async.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/cloud.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/compatibility.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/config-intro.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/configuration.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/customconfig.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/customloglevels.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/eventlogging.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/extending.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/filters.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/flowtracing.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/garbagefree.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/getting-started.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/index.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/installation.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/jmx.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/json-template-layout.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/layouts.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/logbuilder.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/logsep.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/lookups.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/markers.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/messages.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/migration.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/pattern-layout.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/performance.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/plugins.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/resource-logger.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/scoped-context.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/scripts.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/simple-logger.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/status-logger.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/systemproperties.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/thread-context.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/manual/webapp.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/migrate-from-logback.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/migrate-from-slf4j.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/plugin-reference.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/log4j/2.x/release-notes.html</loc>
-<lastmod>2024-07-02T19:03:30.769Z</lastmod>
+<lastmod>2024-07-03T08:14:11.225Z</lastmod>
</url>
</urlset>