[jira] [Created] (LOG4J2-955) Improve documentation for StatusLogger properties

["Remko Popma (JIRA)" <ji...@apache.org>]

Remko Popma created LOG4J2-955:
----------------------------------

             Summary: Improve documentation for StatusLogger properties
                 Key: LOG4J2-955
                 URL: https://issues.apache.org/jira/browse/LOG4J2-955
             Project: Log4j 2
          Issue Type: Improvement
          Components: Documentation
    Affects Versions: 2.1
            Reporter: Remko Popma


>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 jason) 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:
{quote}Note: this property is used by the log4j-core implementation when a configuration file has been found.{quote}

*log4j2.StatusLogger.level*
Replace current description with:
{quote}
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 the JMX StatusLoggerAdmin MBean.

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>).
{quote}

Add new property:
*org.apache.logging.log4j.simplelog.StatusLogger.level*
{quote}
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).
{quote}





--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org