Package org.apache.logging.log4j.status

Class StatusLogger

  • All Implemented Interfaces:
    Serializable, org.apache.logging.log4j.Logger, org.apache.logging.log4j.spi.ExtendedLogger, org.apache.logging.log4j.spi.LocationAwareLogger
    public class StatusLogger
extends org.apache.logging.log4j.spi.AbstractLogger
    Records events that occur in the logging system. StatusLogger is expected to be a standalone, self-sufficient component that the logging system can rely on for low-level logging purposes.

    Listeners

    Each recorded event will first get buffered and then used to notify the registered StatusListeners. If none are available, the fallback listener of type StatusConsoleListener will be used.

    You can programmatically register listeners using registerListener(StatusListener) method.

    Configuration

    The StatusLogger can be configured in following ways:

    1. Passing system properties to the Java process (e.g., -Dlog4j2.StatusLogger.level=INFO)
    2. Providing properties in a "log4j2.StatusLogger.properties" file in the classpath
    3. Using Log4j configuration (i.e., <Configuration status="WARN" dest="out"> in a log4j2.xml in the classpath)
    4. 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:

    1. The default level (of fallback listener) is ERROR
    2. You have <Configuration status="WARN"> in your log4j2.xml
    3. Until your log4j2.xml configuration is read, the effective level will be ERROR
    4. Once your log4j2.xml configuration is read, the effective level will be WARN as you configured

    Hence, unless you use either system properties or "log4j2.StatusLogger.properties" 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.

    Configuration properties

    The list of available properties for configuring the StatusLogger is shared below.

    available properties for configuring the StatusLogger
    Name Default Description
    "log4j2.status.entries" 0 The maximum number of events buffered. Once the limit is reached, older entries will be removed as new entries are added.
    "log4j2.StatusLogger.level" ERROR The Level name to use as the fallback listener level.
    The fallback listener is used when the listener registry is empty. The fallback listener will accept entries filtered by the level provided in this configuration.
    "log4j2.StatusLogger.dateFormat" null A DateTimeFormatter pattern to format the created StatusData.
    "log4j2.debug" false The debug mode toggle.

    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.

    See Also:
    Serialized Form

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  StatusLogger.Config
      Holder for user-provided StatusLogger configurations.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static String DEFAULT_STATUS_LISTENER_LEVEL
      The name of the system property that can be configured with the Level name to use as the fallback listener level.
      static String MAX_STATUS_ENTRIES
      The name of the system property that can be configured with the maximum number of events buffered.
      static String PROPERTIES_FILE_NAME
      The name of the file to be searched in the classpath to read properties from.
      static String STATUS_DATE_FORMAT
      The name of the system property that can be configured with a DateTimeFormatter pattern that will be used while formatting the created StatusData.

      • Fields inherited from class org.apache.logging.log4j.spi.AbstractLogger

        CATCHING_MARKER, DEFAULT_FLOW_MESSAGE_FACTORY_CLASS, DEFAULT_MESSAGE_FACTORY_CLASS, ENTRY_MARKER, EXCEPTION_MARKER, EXIT_MARKER, FLOW_MARKER, name, THROWING_MARKER

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void clear()
      Deprecated.
      Since 2.23.0, instead of relying on the buffering provided by StatusLogger, users should register their own listeners to access to logged events.
      StatusConsoleListener getFallbackListener()
      Returns the fallback listener.
      org.apache.logging.log4j.Level getLevel()
      Returns the least specific level among listeners, if registered any; otherwise, the fallback listener level.
      Iterable<org.apache.logging.log4j.status.StatusListener> getListeners()
      Returns the listener collection.
      static StatusLogger getLogger()
      Gets the static instance.
      List<StatusData> getStatusData()
      Deprecated.
      Since 2.23.0, instead of relying on the buffering provided by StatusLogger, users should register their own listeners to access to logged events.
      boolean isEnabled​(org.apache.logging.log4j.Level messageLevel, org.apache.logging.log4j.Marker marker)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, CharSequence message, Throwable throwable)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, Object message, Throwable throwable)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, String message)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, String message, Object p0)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, String message, Object... params)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, String message, Object p0, Object p1)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, String message, Object p0, Object p1, Object p2)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, String message, Object p0, Object p1, Object p2, Object p3)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6, Object p7)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6, Object p7, Object p8)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6, Object p7, Object p8, Object p9)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, String message, Throwable throwable)  
      boolean isEnabled​(org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, org.apache.logging.log4j.message.Message message, Throwable throwable)  
      void logMessage​(String fqcn, org.apache.logging.log4j.Level level, org.apache.logging.log4j.Marker marker, org.apache.logging.log4j.message.Message message, Throwable throwable)  
      void registerListener​(org.apache.logging.log4j.status.StatusListener listener)
      Registers a new listener.
      void removeListener​(org.apache.logging.log4j.status.StatusListener listener)
      Removes the given listener.
      void reset()
      Clears the event buffer, removes the registered (not the fallback one!)
      void setLevel​(org.apache.logging.log4j.Level level)
      Deprecated.
      Since 2.23.0, instead use the setLevel(Level) method on the fallback listener returned by getFallbackListener().
      static void setLogger​(StatusLogger logger)
      Sets the static (i.e., singleton) instance returned by getLogger().
      void updateListenerLevel​(org.apache.logging.log4j.Level level)
      Deprecated.
      Since 2.23.0, instead use the setLevel(Level) method on the fallback listener returned by getFallbackListener().

      • Methods inherited from class org.apache.logging.log4j.spi.AbstractLogger

        always, atDebug, atError, atFatal, atInfo, atLevel, atTrace, atWarn, catching, catching, catching, catchingMsg, checkMessageFactory, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, debug, enter, enter, enter, enter, enter, entry, entry, entry, entryMsg, entryMsg, entryMsg, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, error, exit, exit, exit, exit, exitMsg, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, fatal, getFlowMessageFactory, getLogBuilder, getMessageFactory, getName, getRecursionDepth, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, info, isDebugEnabled, isDebugEnabled, isEnabled, isErrorEnabled, isErrorEnabled, isFatalEnabled, isFatalEnabled, isInfoEnabled, isInfoEnabled, isTraceEnabled, isTraceEnabled, isWarnEnabled, isWarnEnabled, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logIfEnabled, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, logMessage, printf, printf, requiresLocation, throwing, throwing, throwing, throwingMsg, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, trace, traceEntry, traceEntry, traceEntry, traceEntry, traceEntry, traceExit, traceExit, traceExit, traceExit, traceExit, traceExit, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn, warn

    • Field Detail

      • MAX_STATUS_ENTRIES

        public static final String MAX_STATUS_ENTRIES
        The name of the system property that can be configured with the maximum number of events buffered.

        Once the limit is reached, older entries will be removed as new entries are added.

        See Also:
        Constant Field Values

      • DEFAULT_STATUS_LISTENER_LEVEL

        public static final String DEFAULT_STATUS_LISTENER_LEVEL
        The name of the system property that can be configured with the Level name to use as the fallback listener level.

        The fallback listener is used when the listener registry is empty. The fallback listener will accept entries filtered by the level provided in this configuration.

        Since:
        2.8
        See Also:
        Constant Field Values

      • PROPERTIES_FILE_NAME

        public static final String PROPERTIES_FILE_NAME
        The name of the file to be searched in the classpath to read properties from.
        Since:
        2.23.0
        See Also:
        Constant Field Values

    • Constructor Detail

      • StatusLogger

        public StatusLogger​(String name,
                    org.apache.logging.log4j.message.MessageFactory messageFactory,
                    StatusLogger.Config config,
                    StatusConsoleListener fallbackListener)
        Constructs an instance using given properties. Users should not create new instances, but use getLogger() instead!
        Parameters:
        name - the logger name
        messageFactory - the message factory
        config - the configuration
        fallbackListener - the fallback listener
        Throws:
        NullPointerException - on null name, messageFactory, config, or fallbackListener
        Since:
        2.23.0

    • Method Detail

      • getLogger

        public static StatusLogger getLogger()
        Gets the static instance.
        Returns:
        the singleton instance

      • setLogger

        public static void setLogger​(StatusLogger logger)
        Sets the static (i.e., singleton) instance returned by getLogger(). This method is intended for testing purposes and can have unforeseen consequences if used in production code.
        Parameters:
        logger - a logger instance
        Throws:
        NullPointerException - on null logger
        Since:
        2.23.0

      • getFallbackListener

        public StatusConsoleListener getFallbackListener()
        Returns the fallback listener.
        Returns:
        the fallback listener
        Since:
        2.23.0

      • setLevel

        @Deprecated
public void setLevel​(org.apache.logging.log4j.Level level)
        Deprecated.
        Since 2.23.0, instead use the setLevel(Level) method on the fallback listener returned by getFallbackListener().
        Sets the level of the fallback listener.
        Parameters:
        level - a level

      • registerListener

        public void registerListener​(org.apache.logging.log4j.status.StatusListener listener)
        Registers a new listener.
        Parameters:
        listener - a listener to register

      • removeListener

        public void removeListener​(org.apache.logging.log4j.status.StatusListener listener)
        Removes the given listener.
        Parameters:
        listener - a listener to remove

      • updateListenerLevel

        @Deprecated
public void updateListenerLevel​(org.apache.logging.log4j.Level level)
        Deprecated.
        Since 2.23.0, instead use the setLevel(Level) method on the fallback listener returned by getFallbackListener().
        Sets the level of the fallback listener.
        Parameters:
        level - a level
        Since:
        2.6

      • getListeners

        public Iterable<org.apache.logging.log4j.status.StatusListener> getListeners()
        Returns the listener collection.
        Returns:
        a thread-safe read-only collection of listeners

      • reset

        public void reset()
        Clears the event buffer, removes the registered (not the fallback one!) listeners, and resets the fallback listener.

      • getStatusData

        @Deprecated
public List<StatusData> getStatusData()
        Deprecated.
        Since 2.23.0, instead of relying on the buffering provided by StatusLogger, users should register their own listeners to access to logged events.
        Returns buffered events.
        Returns:
        a thread-safe read-only collection of buffered events

      • clear

        @Deprecated
public void clear()
        Deprecated.
        Since 2.23.0, instead of relying on the buffering provided by StatusLogger, users should register their own listeners to access to logged events.
        Clears the event buffer.

      • getLevel

        public org.apache.logging.log4j.Level getLevel()
        Returns the least specific level among listeners, if registered any; otherwise, the fallback listener level.
        Returns:
        the least specific listener level, if registered any; otherwise, the fallback listener level

      • logMessage

        public void logMessage​(String fqcn,
                       org.apache.logging.log4j.Level level,
                       org.apache.logging.log4j.Marker marker,
                       org.apache.logging.log4j.message.Message message,
                       Throwable throwable)

      • isEnabled

        public boolean isEnabled​(org.apache.logging.log4j.Level level,
                         org.apache.logging.log4j.Marker marker,
                         String message,
                         Throwable throwable)

      • isEnabled

        public boolean isEnabled​(org.apache.logging.log4j.Level level,
                         org.apache.logging.log4j.Marker marker,
                         String message)

      • isEnabled

        public boolean isEnabled​(org.apache.logging.log4j.Level level,
                         org.apache.logging.log4j.Marker marker,
                         String message,
                         Object... params)

      • isEnabled

        public boolean isEnabled​(org.apache.logging.log4j.Level level,
                         org.apache.logging.log4j.Marker marker,
                         String message,
                         Object p0)

      • isEnabled

        public boolean isEnabled​(org.apache.logging.log4j.Level level,
                         org.apache.logging.log4j.Marker marker,
                         String message,
                         Object p0,
                         Object p1)

      • isEnabled

        public boolean isEnabled​(org.apache.logging.log4j.Level level,
                         org.apache.logging.log4j.Marker marker,
                         String message,
                         Object p0,
                         Object p1,
                         Object p2)

      • isEnabled

        public boolean isEnabled​(org.apache.logging.log4j.Level level,
                         org.apache.logging.log4j.Marker marker,
                         String message,
                         Object p0,
                         Object p1,
                         Object p2,
                         Object p3)

      • isEnabled

        public boolean isEnabled​(org.apache.logging.log4j.Level level,
                         org.apache.logging.log4j.Marker marker,
                         String message,
                         Object p0,
                         Object p1,
                         Object p2,
                         Object p3,
                         Object p4)

      • isEnabled

        public boolean isEnabled​(org.apache.logging.log4j.Level level,
                         org.apache.logging.log4j.Marker marker,
                         String message,
                         Object p0,
                         Object p1,
                         Object p2,
                         Object p3,
                         Object p4,
                         Object p5)

      • isEnabled

        public boolean isEnabled​(org.apache.logging.log4j.Level level,
                         org.apache.logging.log4j.Marker marker,
                         CharSequence message,
                         Throwable throwable)

      • isEnabled

        public boolean isEnabled​(org.apache.logging.log4j.Level level,
                         org.apache.logging.log4j.Marker marker,
                         Object message,
                         Throwable throwable)

      • isEnabled

        public boolean isEnabled​(org.apache.logging.log4j.Level level,
                         org.apache.logging.log4j.Marker marker,
                         org.apache.logging.log4j.message.Message message,
                         Throwable throwable)

      • isEnabled

        public boolean isEnabled​(org.apache.logging.log4j.Level messageLevel,
                         org.apache.logging.log4j.Marker marker)
        Specified by:
        isEnabled in interface org.apache.logging.log4j.Logger
        Overrides:
        isEnabled in class org.apache.logging.log4j.spi.AbstractLogger