Package org.apache.logging.log4j.status

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:

• Serialized Form

Nested Class Summary

Nested Classes

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

Field Summary

Fields

Modifier and Type	Field	Description
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.
static final String	MAX_STATUS_ENTRIES	The name of the system property that can be configured with the maximum number of events buffered.
static final String	PROPERTIES_FILE_NAME	The name of the file to be searched in the classpath to read properties from.
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.

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

Constructor Summary

Constructors

Constructor	Description
StatusLogger(String name, MessageFactory messageFactory, StatusLogger.Config config, StatusConsoleListener fallbackListener)	Constructs an instance using given properties.

Method Summary

Modifier and Type	Method	Description
void	clear()	Deprecated. 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.
Level	getLevel()	Returns the least specific level among listeners, if registered any; otherwise, the fallback listener level.
Iterable<StatusListener>	getListeners()	Returns the listener collection.
static StatusLogger	getLogger()	Gets the static instance.
List<StatusData>	getStatusData()	Deprecated. Instead of relying on the buffering provided by StatusLogger, users should register their own listeners to access to logged events.
boolean	isEnabled(Level messageLevel, Marker marker)	Checks whether this Logger is enabled for the given Level and Marker.
boolean	isEnabled(Level level, Marker marker, CharSequence message, Throwable throwable)	Tests if logging is enabled.
boolean	isEnabled(Level level, Marker marker, Object message, Throwable throwable)	Tests if logging is enabled.
boolean	isEnabled(Level level, Marker marker, String message)	Tests if logging is enabled.
boolean	isEnabled(Level level, Marker marker, String message, Object p0)	Tests if logging is enabled.
boolean	isEnabled(Level level, Marker marker, String message, Object... params)	Tests if logging is enabled.
boolean	isEnabled(Level level, Marker marker, String message, Object p0, Object p1)	Tests if logging is enabled.
boolean	isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2)	Tests if logging is enabled.
boolean	isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3)	Tests if logging is enabled.
boolean	isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4)	Tests if logging is enabled.
boolean	isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5)	Tests if logging is enabled.
boolean	isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6)	Determines if logging is enabled.
boolean	isEnabled(Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, Object p4, Object p5, Object p6, Object p7)	Tests if logging is enabled.
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)	Tests if logging is enabled.
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)	Tests if logging is enabled.
boolean	isEnabled(Level level, Marker marker, String message, Throwable throwable)	Tests if logging is enabled.
boolean	isEnabled(Level level, Marker marker, Message message, Throwable throwable)	Tests if logging is enabled.
void	logMessage(String fqcn, Level level, Marker marker, Message message, Throwable throwable)	Logs a message at the specified level.
void	registerListener(StatusListener listener)	Registers a new listener.
void	removeListener(StatusListener listener)	Removes the given listener.
void	reset()	Clears the event buffer, removes the registered (not the fallback one!) listeners, and resets the fallback listener.
void	setLevel(Level level)	Deprecated. 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(Level level)	Deprecated. 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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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:

• 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

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:

• STATUS_DATE_FORMAT_ZONE
• 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 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.