Details
-
Improvement
-
Status: Resolved
-
Major
-
Resolution: Fixed
-
2.1
Description
From what I see on StackOverflow, a number of users have trouble troubleshooting configuration issues. Especially issues with not being able to find the config file can difficult to troubleshoot and StatusLogger output would be a useful tool in those situations.
Unfortunately our current documentation only covers how to configure the StatusLogger in the log4j2.xml (or JSON) configuration file. There is some documentation on the system properties that control StatusLogger level but this is confusing and incomplete (I wrote it and I'm confused when I read it... 
).
I propose making the following updates to the system properties docs:
Log4jDefaultStatusLevel
Keep current description, add this sentence:
Note: this property is used by the log4j-core implementation when a configuration file has been found.
log4j2.StatusLogger.level
Replace current description with:
The initial "listenersLevel" of the StatusLogger. If StatusLogger listeners are added, the "listenerLevel" is changed to that of the most verbose listener. If any listeners are registered, the listenerLevel is used to quickly determine if an interested listener exists.
By default, StatusLogger listeners are added when a configuration is found and by the JMX StatusLoggerAdmin MBean. For example, if a configuration contains <code><Configuration status="trace"></code>, a listener with statusLevel TRACE is registered and the StatusLogger listenerLevel is set to TRACE, resulting in verbose status messages displayed on the console.
If no listeners are registered, the listenersLevel is not used, and the StatusLogger output level is determined by <code>StatusLogger.getLogger().getLevel()</code>
(see property <code>org.apache.logging.log4j.simplelog.StatusLogger.level</code>).
Add new property:
org.apache.logging.log4j.simplelog.StatusLogger.level
This property is used to control the initial StatusLogger level, and can be overridden in code by calling <code>StatusLogger.getLogger().setLevel(someLevel)</code>. Note that the StatusLogger level is only used to determine the status log output level until a listener is registered. In practice, a listener is registered when a configuration is found, and from that point onwards, status messages are only sent to the listeners (depending on their statusLevel).