ppkarwasz commented on code in PR #2249: URL: https://github.com/apache/logging-log4j2/pull/2249#discussion_r1469414965
########## log4j-api/src/main/java/org/apache/logging/log4j/status/StatusLogger.java: ########## @@ -16,311 +16,590 @@ */ package org.apache.logging.log4j.status; -import java.io.Closeable; +import static java.util.Objects.requireNonNull; + +import edu.umd.cs.findbugs.annotations.Nullable; import java.io.IOException; +import java.io.InputStream; +import java.io.PrintStream; +import java.net.URL; +import java.time.format.DateTimeFormatter; import java.util.ArrayList; import java.util.Collection; +import java.util.Collections; +import java.util.Iterator; import java.util.List; +import java.util.Properties; import java.util.Queue; import java.util.concurrent.ConcurrentLinkedQueue; -import java.util.concurrent.CopyOnWriteArrayList; import java.util.concurrent.locks.Lock; import java.util.concurrent.locks.ReadWriteLock; -import java.util.concurrent.locks.ReentrantLock; import java.util.concurrent.locks.ReentrantReadWriteLock; import org.apache.logging.log4j.Level; import org.apache.logging.log4j.Marker; import org.apache.logging.log4j.message.Message; import org.apache.logging.log4j.message.MessageFactory; import org.apache.logging.log4j.message.ParameterizedNoReferenceMessageFactory; -import org.apache.logging.log4j.simple.SimpleLogger; -import org.apache.logging.log4j.simple.SimpleLoggerContext; import org.apache.logging.log4j.spi.AbstractLogger; import org.apache.logging.log4j.util.Constants; -import org.apache.logging.log4j.util.PropertiesUtil; /** - * Records events that occur in the logging system. By default, only error messages are logged to {@link System#err}. - * Normally, the Log4j StatusLogger is configured via the root {@code <Configuration status="LEVEL"/>} node in a Log4j - * configuration file. However, this can be overridden via a system property named - * {@value #DEFAULT_STATUS_LISTENER_LEVEL} and will work with any Log4j provider. - * - * @see SimpleLogger - * @see SimpleLoggerContext + * Records events that occur in the logging system. + * {@link StatusLogger} is expected to be a standalone, self-sufficient component that the logging system can rely on for low-level logging purposes. + * <h3>Listeners</h3> + * <p> + * Each recorded event will first get buffered and used to notify the registered {@link StatusListener}s. + * Listener registry is always initialized with a <em>default listener</em>, which is a {@link StatusConsoleListener}. + * </p> + * <p> + * You can programmatically register listeners using {@link #registerListener(StatusListener)} method. + * </p> + * <h3>Configuration</h3> + * <p> + * The {@code StatusLogger} can be configured in following ways: + * </p> + * <ol> + * <li>Passing system properties to the Java process (e.g., {@code -Dlog4j2.StatusLogger.level=INFO})</li> + * <li>Providing properties in a {@value StatusLogger#PROPERTIES_FILE_NAME} file in the classpath</li> + * <li>Using Log4j configuration (i.e., {@code <Configuration status="WARN" dest="out">} in a {@code log4j2.xml} in the classpath)</li> + * </ol> + * <p> + * It is crucial to understand that there is a time between the first {@code StatusLogger} access and a configuration file (e.g., {@code log4j2.xml}) read. + * Consider the following example: + * </p> + * <ol> + * <li>The default level is {@code ERROR}</li> + * <li>You have <Configuration status="WARN">} in your {@code log4j2.xml}</li> + * <li>Until your {@code log4j2.xml} configuration is read, the effective level will be {@code ERROR}</li> + * <li>Once your {@code log4j2.xml} configuration is read, the effective level will be {@code WARN} as you configured</li> + * </ol> + * <p> + * Hence, unless you use either system properties or {@value StatusLogger#PROPERTIES_FILE_NAME} file in the classpath, there is a time window that only the defaults will be effective. + * </p> + * <p> + * {@code 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 {@code StatusLogger} configurations (e.g, one {@code log4j2.xml} containing {@code <Configuration status="ERROR">} while the other {@code <Configuration status="INFO">}), the last loaded configuration will be effective one. + * </p> + * <h3>Debug mode</h3> + * <p> + * When the {@value Constants#LOG4J2_DEBUG} system property is present, any level-related filtering will be skipped and all events will be notified to listeners. + * </p> */ -public final class StatusLogger extends AbstractLogger { +public class StatusLogger extends AbstractLogger { Review Comment: Since we don't assign `StatusLogger` to instance fields, I don't think serialization is a problem. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@logging.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org