Class StatusLogger

java.lang.Object
org.apache.logging.log4j.spi.AbstractLogger
org.apache.logging.log4j.status.StatusLogger
All Implemented Interfaces:
Serializable, Logger, ExtendedLogger, LocationAwareLogger

public class StatusLogger extends 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:
  • Field Details

    • 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:
    • 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:
    • STATUS_DATE_FORMAT

      public static final 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.

      When not provided, Instant.toString() will be used.

      Since:
      2.11.0
      See Also:
    • 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:
  • Constructor Details

    • StatusLogger

      public StatusLogger(String name, 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 Details

    • 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
    • setLevel

      @Deprecated public void setLevel(Level level)
      Deprecated.
      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(StatusListener listener)
      Registers a new listener.
      Parameters:
      listener - a listener to register
    • removeListener

      public void removeListener(StatusListener listener)
      Removes the given listener.
      Parameters:
      listener - a listener to remove
    • updateListenerLevel

      @Deprecated public void updateListenerLevel(Level level)
      Deprecated.
      Instead use the setLevel(Level) method on the fallback listener returned by getFallbackListener().
      Sets the level of the fallback listener.
      Parameters:
      level - a level
    • getListeners

      public Iterable<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.
      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.
      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 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, Level level, Marker marker, Message message, Throwable throwable)
      Description copied from interface: ExtendedLogger
      Logs a message at the specified level. It is the responsibility of the caller to ensure the specified level is enabled.
      Parameters:
      fqcn - The fully qualified class name of the logger entry point, used to determine the caller class and method when location information needs to be logged.
      level - The logging Level to check.
      marker - A Marker or null.
      message - The Message.
      throwable - the exception to log, including its stack trace.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, String message, Throwable throwable)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      throwable - the exception to log, including its stack trace.
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, String message)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, String message, Object... params)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      params - The parameters.
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, String message, Object p0)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      p0 - the message parameters
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, String message, Object p0, Object p1)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      p0 - the message parameters
      p1 - the message parameters
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      p0 - the message parameters
      p1 - the message parameters
      p2 - the message parameters
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      p0 - the message parameters
      p1 - the message parameters
      p2 - the message parameters
      p3 - the message parameters
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      p0 - the message parameters
      p1 - the message parameters
      p2 - the message parameters
      p3 - the message parameters
      p4 - the message parameters
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      p0 - the message parameters
      p1 - the message parameters
      p2 - the message parameters
      p3 - the message parameters
      p4 - the message parameters
      p5 - the message parameters
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6)
      Description copied from interface: ExtendedLogger
      Determines if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      p0 - the message parameters
      p1 - the message parameters
      p2 - the message parameters
      p3 - the message parameters
      p4 - the message parameters
      p5 - the message parameters
      p6 - the message parameters
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6, Object p7)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      p0 - the message parameters
      p1 - the message parameters
      p2 - the message parameters
      p3 - the message parameters
      p4 - the message parameters
      p5 - the message parameters
      p6 - the message parameters
      p7 - the message parameters
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6, Object p7, Object p8)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      p0 - the message parameters
      p1 - the message parameters
      p2 - the message parameters
      p3 - the message parameters
      p4 - the message parameters
      p5 - the message parameters
      p6 - the message parameters
      p7 - the message parameters
      p8 - the message parameters
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6, Object p7, Object p8, Object p9)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      p0 - the message parameters
      p1 - the message parameters
      p2 - the message parameters
      p3 - the message parameters
      p4 - the message parameters
      p5 - the message parameters
      p6 - the message parameters
      p7 - the message parameters
      p8 - the message parameters
      p9 - the message parameters
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, CharSequence message, Throwable throwable)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      throwable - A Throwable.
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, Object message, Throwable throwable)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The message.
      throwable - A Throwable.
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level level, Marker marker, Message message, Throwable throwable)
      Description copied from interface: ExtendedLogger
      Tests if logging is enabled.
      Parameters:
      level - The logging Level to check.
      marker - A Marker or null.
      message - The Message.
      throwable - A Throwable.
      Returns:
      True if logging is enabled, false otherwise.
    • isEnabled

      public boolean isEnabled(Level messageLevel, Marker marker)
      Description copied from interface: Logger
      Checks whether this Logger is enabled for the given Level and Marker.
      Specified by:
      isEnabled in interface Logger
      Overrides:
      isEnabled in class AbstractLogger
      Parameters:
      messageLevel - The Level to check
      marker - The Marker to check
      Returns:
      boolean - true if this Logger is enabled for level and marker, false otherwise.