Apache Log4j 2 Documentation

Apache Log4j is an industrial-grade Java logging framework consisting of an API, an implementation, and various components designed for diverse deployment use cases. It allows developers to track program execution flow, understand application behavior, and debug issues without a debugger.

Key capabilities include:

• Logging messages at various severity levels (from DEBUG to FATAL).
• Routing log messages to multiple destinations such as files, databases, or the console.
• High performance and flexibility for Java applications.

Log4j provides several built-in components to handle different logging requirements:

• Appenders: Direct log events to destinations such as files, network sockets, databases, or SMTP servers.
• Layouts: Format log events into specific structures like CSV, HTML, JSON, or Syslog.
• Filters: Control log event flow based on criteria such as log event rates, regular expressions, scripts, or time.
• Lookups: Access contextual information like system properties, environment variables, or log event fields during configuration or logging.

Log4j Core provides three different appender implementations for storing log messages in files, each with different performance characteristics and access methods:

• File: Uses FileOutputStream to access log files.
• RandomAccessFile: Uses RandomAccessFile to access log files. It always uses an internal buffer of size bufferSize.
• MemoryMappedFile: Maps log files into a MappedByteBuffer. It is significantly faster because it modifies local memory instead of making system calls to write to disk. It always uses a memory-mapped buffer of size regionLength.

Note: If you need to rotate your log files, use a rolling file appender instead of these static file appenders.

When using Log4j layouts, be aware of the following shared characteristics:

• Structured Logging: Log4j provides support for structured logging via specific message types and layouts. For production-grade structured logging (e.g., for Elasticsearch or Google Cloud), JsonTemplateLayout is recommended.
• Character Encoding: All layouts produce a String that is converted to bytes using a configured Charset. The default is UTF-8 unless explicitly configured otherwise.
• Log Event Content: Layouts format events into strings or byte arrays but do not typically modify the event content. To modify content (e.g., masking PII or injecting metadata), use the Rewrite Appender.
• Location Information: Some layouts support including source location information (class, method, file, line).

Log4j Core uses a property substitution system to dynamically retrieve data via Lookups. The system consists of:

• StrSubstitutor: The engine that evaluates ${...} expressions, supporting recursion and default values.
• Interpolator: Evaluates simple ${name} expressions. If name contains a colon (prefix:key), it delegates to a StrLookup plugin. If no colon is present, it resolves via the Properties configuration element.
• StrLookup: A plugin interface (associated with a prefix) that retrieves data from external sources. Lookups can operate in a Global context (during configuration) or an Event context (during log event processing).

Log4j Core can be configured using one of the following methods to determine which logging statements are captured and their destinations:

1. Configuration File: Use a static configuration file (e.g., XML, JSON, YAML, or properties).
2. Programmatic Configuration: Configure the logging behavior directly within your application code.

Note that certain meta-configuration settings, such as specifying the location of the configuration file, must be set using System Properties.

Log4j Core provides two types of rolling file appenders to archive and truncate log files:

1. RollingFile: Uses FileOutputStream to access log files.
2. RollingRandomAccessFile: Uses RandomAccessFile to access log files (typically higher performance).

Note that appenders with the same non-null fileName (or the same filePattern if fileName is null) share a common RollingFileManager. This ensures rollovers occur only once across those appenders, but requires most other configuration parameters to be identical.

The Log4j IOStreams extension allows you to bridge java.io classes with a Log4j Logger.

• Output-oriented classes: Use these to create an OutputStream, Writer, PrintWriter, or PrintStream that writes its contents as log messages to a Logger.
• Input-oriented classes: Use these to 'wiretap' an InputStream or Reader, allowing a Logger to capture the contents being read.

Requirements:

• Log4j 2 API
• Introduced in Log4j 2.1

Filters evaluate log event parameters and return one of three results:

• ACCEPT: The filter accepts the log event. This causes other filters in the same filtering stage to be skipped.
• DENY: The filter drops the log event.
• NEUTRAL: Log4j behaves as if the filter was not present. The event is passed to the next filter in the chain.

To correctly integrate logging into your project, you must distinguish between three core concepts:

• Logging API: An interface your code or dependencies log against. It is required at compile-time and is implementation-agnostic (e.g., Log4j API, SLF4J, JUL, JCL, JPL, JBoss Logging).
• Logging Implementation: The engine that actually processes and writes the logs. It is required at runtime and can be changed without recompiling code (e.g., Log4j Core, Logback).
• Logging Bridge: A specialized implementation of a logging API that forwards all messages to a different, primary logging API. Bridges allow a single implementation (like Log4j Core) to capture logs from various other APIs (e.g., log4j-slf4j2-impl bridges SLF4J calls to the Log4j API).