Log4j Concepts

Relevance

Applies to log4j 2.

Internal

• log4j

Overview

log4j initialize a tree of Loggers in memory. The application writes into those Loggers with methods like info(), warn(), error(), etc.. Depending on the logging level implied by the writing method, the logging level of the Logger themselves, the appenders associated with the loggers and their logging level, the logged information is filtered to various levels of verbosity and goes into different places. The main advantage of log4j over System.out.println() is the ability to disable certain log statements while allowing others, via configuration.

Logger

Logger is the central class in the log4j package. Most logging operations, except configuration, are done through this class. The Logger has a name and it is associated with a LoggerConfig. As the configuration is modified, Loggers may become associated with a different LoggerConfig, this causing this behavior to be modified.

Log4j makes it easy to name Loggers by software component. This can be accomplished by instantiating a Logger in each class, with the logger name equal to the fully qualified name of the class. Since naming Loggers after their owning class is such a common idiom, the convenience method LogManager.getLogger() is provided to automatically use the calling class's fully qualified class name as the Logger name.

Category deprecation note: Logger is a subclass of Category and extends it. Category has been deprecated. Internally, whenever log4j is asked to produce a Category object, it will instead produce a Logger object. In order to preserve backward compatibility, methods that previously accepted category objects still continue to accept category objects.

Creating a Logger Instance

The recommended way to create Logger instance is to request them by name from the LogManager:

Logger log = LogManager.getLogger("some-name");

LoggerConfig

The logging hierarchy is maintained as a relationship between LoggerConfig instances. LoggerConfig objects are created when Loggers are declared in the logging configuration. The LoggerConfig contains a set of Filters that must allow the LogEvent to pass before it will be passed to any Appenders. It contains references to the set of Appenders that should be used to process the event.

LoggerConfig Named Hierarchy

A LoggerConfig is said to be an ancestor of another LoggerConfig if its name followed by a dot is a prefix of the descendant name.

A LoggerConfig is said to be a parent of a child LoggerConfig is there are no ancestors between itself and the descendant LoggerConfig.

Root LoggerConfig

The root LoggerConfig resides at the top of the LoggerConfig hierarchy. It always exists and it is part of every hierarchy. The Logger that is directly linked to the root LoggerConfig can be obtained as follows:

Logger root = LogManager.getLogger(LogManager.ROOT_LOGGER_NAME);

which is equivalent with:

Logger root = LogManager.getRootLogger();

Log Levels

Each LoggerConfig has a log Level. For more details see http://logging.apache.org/log4j/2.x/log4j-api/apidocs/org/apache/logging/log4j/Level.html.

log4j implements level inheritance.

The level can be accessed from a logger by using the following API:

import org.apache.log4j.Logger;
import org.apache.log4j.Level;

...

Logger log = ...
Level currentLevel = log.getLevel();

Category

This class has been deprecated and replaced with the Logger subclass. There is no need for new client code to use or refer to the Category class.

Appender

The ability to selectively enable or disable logging requests based on their logger is just one part of the overall logging behavior.

Log4j allows logging requests to print to multiple destinations. An output destination is called an Appender. Currently, appenders exist for the console, files, remote socket servers, UNIX Syslog daemons, various database APIs., etc. For more details see http://logging.apache.org/log4j/2.x/log4j-core/apidocs/org/apache/logging/log4j/core/Appender.html.

An Appender can be added to a Logger by calling addLoggerAppender().

Appender Hierarchy

Each valid logging request for a given logger will be forwarded to all appenders in that Logger's LoggerConfig as well as the appenders of the LoggerConfig's parents. Appenders are inherited additively from the LoggerConfig hierarchy. This is known as appender additivity. However, if an ancestor of the LoggerConfig has the additivity flag set to false, the output will be send to all appenders up the hierarchy, including the ancestor configured with false additivity, but not its ancestors. Loggers have their additivity flag set to true by default.

Appender that Maintains a Log File at a Certain Size

RollingFileAppender

Layout

Formatting the log output is done by associating a Layout with an Appender. The Layout is responsible for formatting log events.

Configuration

The configuration of the log4j environment is typically performed on application initialization. The preferred way is by reading a configuration file. More details: http://logging.apache.org/log4j/2.x/manual/configuration.html

Also see:

log4j Configuration