Add Simple Logger and Status Logger pages

src/site/antora/modules/ROOT/nav.adoc

@@ -42,6 +42,8 @@
 ** xref:manual/flowtracing.adoc[]
 ** xref:manual/eventlogging.adoc[]
 ** xref:manual/resource-logger.adoc[]
+** xref:manual/simple-logger.adoc[]
+** xref:manual/status-logger.adoc[]
 * Configuration
 ** xref:manual/configuration.adoc[Configuration file]
 ** xref:manual/systemproperties.adoc[]

src/site/antora/modules/ROOT/pages/faq.adoc

@@ -126,11 +126,11 @@ By default, Log4j looks for a configuration file named `log4j2.xml` on the class
 Note the `2` in the file name!
 (See xref:manual/configuration.adoc[the Configuration page] for more details.)
 
-. Increase the logging verbosity of the internal status logger: +
+. Increase the logging verbosity of the internal xref:manual/status-logger.adoc[]: +
 `-Dlog4j2.statusLoggerLevel=TRACE`
 
 . Enable all internal debug logging: `-Dlog4j2.debug`.
-This disables level-based status logger filtering and effectively allows all status logs.
+This disables level-based xref:manual/status-logger.adoc[] filtering and effectively allows all status logs.
 
 [#separate_log_files]
 == How do I dynamically write to separate log files?
@@ -156,7 +156,7 @@ It is the responsibility of the logging _implementation_ to handle this object,
 * Log4j API offers support for logging xref:manual/messages.adoc[`Message` objects].
 Messages allow support for interesting and complex constructs to be passed through the logging system and be efficiently manipulated.
 Users are free to create their own message types and write custom layouts, filters and lookups to manipulate them.
-* Log4j API supports xref:manual/api.adoc#LambdaSupport[lambda expressions] both in its plain and fluent API.
+* Log4j API supports xref:manual/api.adoc#fluent-api[lambda expressions] both in its plain and fluent API.
 * Log4j API has better support for xref:manual/garbagefree.adoc[garbage-free logging]: it avoids creating `vararg` arrays and avoids creating ``String``s when logging ``CharSequence``s.
 
 [#gc-free-slf4j]

src/site/antora/modules/ROOT/pages/log4j-jmx-gui.adoc

@@ -16,7 +16,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 ////
 = Log4j JMX GUI
 
-https://github.com/apache/logging-log4j-jmx-gui[The Apache Log4j JMX GUI] is a basic client GUI that can be used to monitor the `StatusLogger` output and to remotely modify the Log4j configuration.
+https://github.com/apache/logging-log4j-jmx-gui[The Apache Log4j JMX GUI] is a basic client GUI that can be used to monitor the xref:manual/status-logger.adoc[] output and to remotely modify the Log4j configuration.
 The client GUI can be run as a stand-alone application or as a JConsole plug-in.
 
 [NOTE]

src/site/antora/modules/ROOT/pages/manual/api.adoc

@@ -49,9 +49,10 @@ You can also check out xref:manual/installation.adoc[] for the complete installa
 Log4j API provides
 
 * A logging API that libraries and applications can code to
+* xref:#simple-logger[A minimal logging implementation (aka. Simple logger)]
 * Adapter components to create a logging implementation
 
-This page tries to cover the most prominent Log4j API features that libraries and applications can code to.
+This page tries to cover the most prominent Log4j API features.
 
 [TIP]
 ====
@@ -92,7 +93,7 @@ include::partial$manual/api-best-practice-use-supplier.adoc[]
 [#loggers]
 == Loggers
 
-link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`]s obtained using link:../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html[`LogManager`] is the primary entry point for logging.
+link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`]s are the primary entry point for logging.
 In this section we will introduce you to further details about ``Logger``s.
 
 [#logger-names]
@@ -220,7 +221,25 @@ link:../javadoc/log4j-api/org/apache/logging/log4j/LogManager.html[`EventLogger`
 
 xref:manual/eventlogging.adoc[Read more on event loggers...]
 
-[#feature-fluent-api]
+[#simple-logger]
+=== Simple logger
+
+Even though Log4j Core is the reference implementation of Log4j API, Log4j API itself also provides a very minimalist implementation: _Simple Logger_.
+This is a convenience for environments where either a fully-fledged logging implementation is missing, or cannot be included for other reasons.
+`SimpleLogger` is the fallback Log4j API implementation if no other is available in the classpath.
+
+xref:manual/simple-logger.adoc[Read more on the simple logger...]
+
+[#status-logger]
+=== Status logger
+
+_Status Logger_ is a standalone, self-sufficient `Logger` implementation to record events that occur in the logging system (i.e., Log4j) itself.
+It is the logging system used by Log4j for reporting status of its internals.
+Users can use the status logger to either emit logs in their custom Log4j components, or troubleshoot a Log4j configuration.
+
+xref:manual/status-logger.adoc[Read more on the status logger...]
+
+[#fluent-api]
 == Fluent API
 
 The fluent API allows you to log using a fluent interface:

src/site/antora/modules/ROOT/pages/manual/appenders.adoc

@@ -1671,7 +1671,9 @@ Each log event is sent as a Kafka record.
 
 |syncSend
 |boolean
-|The default is `true`, causing sends to block until the record has been acknowledged by the Kafka server. When set to `false`, sends a return immediately, allowing for lower latency and significantly higher throughput. _New since 2.8. Be aware that this is a new addition, and it has not been extensively tested. Any failure sending to Kafka will be reported as an error to StatusLogger and the log event will be dropped (the ignoreExceptions parameter will not be effective). Log events may arrive out of order on the Kafka server._
+|The default is `true`, causing sends to block until the record has been acknowledged by the Kafka server. When set to `false`, sends a return immediately, allowing for lower latency and significantly higher throughput. _New since 2.8. Be aware that this is a new addition, and it has not been extensively tested.
+Any failure sending to Kafka will be reported as an error to xref:manual/status-logger.adoc[] and the log event will be dropped (the ignoreExceptions parameter will not be effective).
+Log events may arrive out of order on the Kafka server._
 
 |properties
 |Property[]
@@ -2925,7 +2927,7 @@ default is 1, meaning only the files in the specified base directory.
 false.
 
 |testMode |boolean |If true, files are not deleted but instead a message
-is printed to the xref:manual/configuration.adoc#StatusMessages[status logger]
+is printed to the xref:manual/status-logger.adoc[]
 at INFO level. Use this to do a dry run to test if the configuration
 works as expected. The default is false.
 
@@ -3170,7 +3172,7 @@ the paths in the `pathList`.
 under the base path up to the specified max depth, sorted most recently
 modified files first. The script is free to modify and return this list.
 
-|statusLogger |StatusLogger |The StatusLogger that can be used to log
+|statusLogger |StatusLogger |The xref:manual/status-logger.adoc[] that can be used to log
 internal events during script execution.
 
 |configuration |Configuration |The Configuration that owns this

src/site/antora/modules/ROOT/pages/manual/configuration.adoc

@@ -59,7 +59,7 @@ Upon initialization of a new logger context, Log4j assigns it a context name and
 . Files named `log4j2-test.<extension>`,
 . Files named `log4j2<contextName>.<extension>`
 . Files named `log4j2.<extension>`,
-. If no configuration file is found, Log4j uses the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/DefaultConfiguration[DefaultConfiguration], and the status logger prints a warning.
+. If no configuration file is found, Log4j uses the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/DefaultConfiguration[DefaultConfiguration], and xref:manual/status-logger.adoc[] prints a warning.
 The default configuration prints all messages less specific than
 xref:manual/systemproperties.adoc#log4j2.level[log4j2.level]
 to the console.
@@ -422,11 +422,12 @@ To modify these options during a reconfiguration, you also need to change the re
 | Default value (before 2.24.0) | value of `log4j2.defaultStatusLevel`
 |===
 
-Overrides the logging level of the status logger.
+Overrides the logging level of xref:manual/status-logger.adoc[].
 
-WARNING: Since 2.24.0 this attribute is deprecated and should be replaced with the
-xref:manual/systemproperties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel]
-configuration property.
+[WARNING]
+====
+Since version `2.24.0`, this attribute is deprecated and should be replaced with the xref:manual/systemproperties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel] configuration property instead.
+====
 
 [id=configuration-elements-filters]
 ==== Filters

src/site/antora/modules/ROOT/pages/manual/jmx.adoc

@@ -18,10 +18,10 @@
 
 Log4j 2 has built-in support for JMX.
 
-When JMX support is enabled, the StatusLogger, ContextSelector, and all LoggerContexts, LoggerConfigs, and Appenders are instrumented with MBeans.
+When JMX support is enabled, xref:manual/status-logger.adoc[], ContextSelector, and all LoggerContexts, LoggerConfigs, and xref:manual/appenders.adoc[] are instrumented with MBeans.
 
 Also included is a simple client GUI that can be used to monitor the
-StatusLogger output, as well as to remotely reconfigure Log4j with a
+status logger output, as well as to remotely reconfigure Log4j with a
 different configuration file, or to edit the current configuration
 directly.
 

src/site/antora/modules/ROOT/pages/manual/logsep.adoc

@@ -102,7 +102,7 @@ default ClassLoaderContextSelector.
 See the instructions shared in xref:manual/webapp.adoc[Log4j Web].
 Each application can be configured to share the same
 configuration used at the container or can be individually configured.
-If status logging is set to debug in the configuration there will be
+If xref:manual/status-logger.adoc[status logging] is set to debug in the configuration there will be
 output from when logging is initialized in the container and then again
 in each web application.
 

src/site/antora/modules/ROOT/pages/manual/scripts.adoc

@@ -115,7 +115,7 @@ interface if they support compiling their scripts.
 Beanshell does extend the `Compilable` interface, but an attempt to compile a script ends up in an
 https://docs.oracle.com/javase/{java-target-version}/docs/api/java/lang/Error.html[Error]
 being thrown.
-Log4j catches the throwable, but issues a warning in the status logger.
+Log4j catches the throwable, but issues a warning in xref:manual/status-logger.adoc[].
 
 ----
 2015-09-27 16:13:23,095 main DEBUG Script BeanShellSelector is compilable

src/site/antora/modules/ROOT/pages/manual/simple-logger.adoc

@@ -0,0 +1,34 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= Simple Logger
+
+Even though Log4j Core is the reference implementation of xref:manual/api.adoc[Log4j API], Log4j API itself also provides a very minimalist implementation: link:../javadoc/log4j-api/org/apache/logging/log4j/simple/SimpleLogger.html[`SimpleLogger`].
+This is a convenience for environments where either a fully-fledged logging implementation is missing, or cannot be included for other reasons.
+`SimpleLogger` is the default Log4j API implementation if no other is available in the classpath.
+
+[#config]
+== Configuration
+
+`SimpleLogger` can be configured using the following system properties:
+
+include::partial$manual/systemproperties/properties-simple-logger.adoc[leveloffset=+1]
+
+=== Thread context
+
+Simple Logger supports the same properties as Log4j Core for the configuration of the thread context.
+See xref:manual/systemproperties.adoc#properties-thread-context[] for details.

src/site/antora/modules/ROOT/pages/manual/status-logger.adoc

@@ -0,0 +1,107 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+:status-logger-properties-file-name: "log4j2.StatusLogger.properties"
+
+= Status Logger
+
+link:../javadoc/log4j-api/org/apache/logging/log4j/status/StatusLogger.html[`StatusLogger`] is a standalone, self-sufficient `Logger` implementation to record events that occur in the logging system (i.e., Log4j) itself.
+It is the logging system used by Log4j for reporting status of its internals.
+
+[#usage]
+== Usage
+
+You can use the status logger for several purposes:
+
+[#usage-troubleshoot]
+Troubleshooting::
+When Log4j is not behaving in the way you expect it to, you can increase the verbosity of status logger messages emitted using xref:#log4j2.debug[the `log4j2.debug` system property] for troubleshooting.
+See xref:#config[] for details.
+
+[#usage-report]
+Reporting internal status::
+If you have custom Log4j components (layouts, appenders, etc.), you cannot use Log4j API itself for logging, since this will result in a chicken and egg problem.
+This is where `StatusLogger` comes into play:
++
+[source,java]
+----
+private class CustomLog4jComponent {
+
+    private static final Logger LOGGER = StatusLogger.getInstance();
+
+    void doSomething(String input) {
+        LOGGER.trace("doing something with input: `{}`", input);
+    }
+
+}
+----
+
+[#usage-listen]
+Listening internal status::
+You can configure where the status logger messages are delivered to.
+See xref:#listeners[].
+
+[#config]
+== Configuration
+
+`StatusLogger` can be configured in following ways:
+
+. Passing system properties to the Java process (e.g., xref:#log4j2.statusLoggerLevel[`-Dlog4j2.statusLoggerLevel=INFO`]}
++
+[WARNING]
+====
+Due to several complexities involved, **you are strongly advised to xref:#properties[configure the status logger only using system properties]!**
+====
+. Providing properties in a `{status-logger-properties-file-name}` file in the classpath
+. Using Log4j configuration (i.e., `<Configuration status="WARN" dest="out">` in a `log4j2.xml` in the classpath)
++
+WARNING: Since version `2.24.0`, `status` attribute in the `Configuration` element is deprecated and should be replaced with the xref:manual/systemproperties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel] configuration property.
+. Programmatically (e.g., `StatusLogger.getLogger().setLevel(Level.WARN)`)
+
+It is crucial to understand that there is a time between the first `StatusLogger` access and a configuration file (e.g., `log4j2.xml`) read.
+Consider the following example:
+
+. The default level (of fallback listener) is `ERROR`
+. You have `<Configuration status="WARN">` in your `log4j2.xml`
+. Until your `log4j2.xml` configuration is read, the effective level will be `ERROR`
+. Once your `log4j2.xml` configuration is read, the effective level will be `WARN` as you configured
+
+Hence, unless you use either system properties or `{status-logger-properties-file-name}` file in the classpath, there is a time window that only the defaults will be effective.
+
+`StatusLogger` is designed as a singleton class accessed statically.
+If you are running an application containing multiple Log4j configurations (e.g., in a servlet environment with multiple containers), and you happen to have differing `StatusLogger` configurations (e.g, one `log4j2.xml` containing `<Configuration status="ERROR">` while the other `<Configuration status="INFO">`), the last loaded configuration will be the effective one.
+
+[#properties]
+=== Properties
+
+`StatusLogger` can be configured using the following system properties:
+
+include::partial$manual/systemproperties/properties-status-logger.adoc[leveloffset=+2]
+
+[#debug]
+== Debug mode
+
+When the `log4j2.debug` system property is present, any level-related filtering will be skipped and all events will be notified to listeners.
+If no listeners are available, the fallback listener of type `StatusConsoleListener` will be used.
+
+[#listeners]
+== Listeners
+
+Each recorded log event by `StatusLogger` will first get buffered and then used to notify the registered link:../javadoc/log4j-api/org/apache/logging/log4j/status/StatusListener.html[`StatusListener`]s.
+If none are available, *the fallback listener* of type link:../javadoc/log4j-api/org/apache/logging/log4j/status/StatusConsoleListener.html[`StatusConsoleListener`] will be used.
+
+You can programmatically register listeners using link:../javadoc/log4j-api/org/apache/logging/log4j/status/StatusLogger.html#registerListener(org.apache.logging.log4j.status.StatusListener)[the `StatusLogger#registerListener(StatusListener)` method].

src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc

@@ -88,41 +88,6 @@ In the particular case, when multiple implementations are present, you can selec
 
 include::partial$manual/systemproperties/properties-provider.adoc[leveloffset=+2]
 
-[id=properties-status-logger]
-=== Status Logger
-
-NOTE: To configure status logger you can also place its configuration in a file named `log4j2.StatusLogger.properties`.
-
-Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
-By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
-
-include::partial$manual/systemproperties/properties-status-logger.adoc[leveloffset=+2]
-
-[id=properties-simple-logger]
-=== Simple logger
-
-NOTE: To configure simple logger you can also place its configuration in a file named `log4j2.simplelog.properties`.
-
-The simple logger implementation contained in `log4j-api` can be configured using these properties:
-
-include::partial$manual/systemproperties/properties-simple-logger.adoc[leveloffset=+2]
-
-[id=properties-simple-logger-thread-context]
-=== Thread context (Simple Logger)
-
-The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
-
-[WARNING]
-====
-These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
-
-The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
-
-The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
-====
-
-include::partial$manual/systemproperties/properties-thread-context.adoc[leveloffset=+2]
-
 [id=properties-log4j-core]
 == Log4j Core properties
 
@@ -203,11 +168,21 @@ Moreover, each JNDI usage must be **explicitly** enabled by the user through the
 
 include::partial$manual/systemproperties/properties-jndi.adoc[leveloffset=+2]
 
-[id=properties-log4j-core-thread-context]
-=== Thread context (Log4j Core)
+[id=properties-thread-context]
+=== Thread context
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and xref:manual/simple-logger.adoc[] implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
 
-Log4j Core supports the same properties as Simple Logger for the configuration of the thread context.
-See <<properties-simple-logger-thread-context>> for more details.
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+include::partial$manual/systemproperties/properties-thread-context.adoc[leveloffset=+2]
 
 [id=properties-transport-security]
 === Transport security