File appenders

Log4j Core provides multiple appenders that store log messages in a file. These appenders differ in the way they access the file system and might provide different performance characteristics.

File appenders do not offer a mechanism for external applications to force it to reopen the log file. External log archiving tools such as logrotate will therefore need to copy the current log file and then truncate it. Log events emitted during this operation will be lost.

If you want to rotate your log files, use a rolling file appender instead.

Appenders

Log4j Core provides three file appender implementations:

File

The File Appender uses FileOutputStream to access log files.

RandomAccessFile

The RandomAccessFile Appender uses RandomAccessFile to access log files.

MemoryMappedFile

The MemoryMappedFile Appender maps log files into a MappedByteBuffer.

Instead of making system calls to write to disk, this appender can simply change the program’s local memory, which is orders of magnitude faster.

Two appenders, even from different logger contexts, share a common FileManager if they use the same value fileName attribute.

Sharing a FileManager guarantees that multiple appenders will access the log file sequentially, but requires most of the remaining configuration parameters to be the same.

Common configuration

Table 1. Common configuration attributes
Attribute Type Default value Description

Required

fileName

Path

The path to the current log file If the folder containing the file does not exist, it will be created.

name

String

The name of the appender.

Optional

bufferSize

int

8192

The size of the ByteBuffer internally used by the appender.

See Buffering for more details.

ignoreExceptions

boolean

true

If false, logging exception will be forwarded to the caller of the logging statement. Otherwise, they will be ignored.

Logging exceptions are always also logged to Status Logger

immediateFlush

boolean

true

If set to true, the appender will flush its internal buffer after each event.

See Buffering for more details.
Table 2. Common nested elements
Type Multiplicity Description

Filter

zero or one

Allows filtering log events just before they are formatted and sent.

See also appender filtering stage.

Layout

zero or one

Formats log events.

See Layouts for more information.

File configuration

The File Appender provides the following configuration options, beyond the common ones:

Table 3. File configuration attributes
Attribute Type Default value Description

append

boolean

true

If true, the log file will be opened in APPEND mode.

On most systems this guarantees atomic writes to the end of the file, even if the file is opened by multiple applications.

bufferedIo

boolean

true

If set to true, Log4j Core will format each log event in an internal buffer, before sending it to the underlying resource.

See Buffering for more details.

createOnDemand

boolean

false

The appender creates the file on-demand. The appender only creates the file when a log event passes all filters and is routed to this appender. Defaults to false.

filePermissions

PosixFilePermissions

null

If not null, it specifies the POSIX file permissions to apply to each created file. The permissions must be provided in the format used by PosixFilePermissions.fromString(), e.g. rw-rw----.

The underlying files system shall support POSIX file attribute view.

fileOwner

String

null

If not null, it specifies the file owner to apply to each created file.

The underlying files system shall support file owner attribute view.

fileGroup

String

null

If not null, it specifies the file group owner to apply to each created file.

The underlying files system shall support POSIX file attribute view.

locking

boolean

false

If true, Log4j will lock the log file at each log event.

Note that the effects of this setting depend on the Operating System: some systems like most POSIX OSes do not offer mandatory locking, but only advisory file locking.

This setting can also reduce the performance of the appender.

📖 Plugin reference for File

RandomAccessFile configuration

The RandomAccessFile Appender provides the following configuration options, beyond the common ones:

Table 4. RollingRandomAccessFile configuration attributes
Attribute Type Default value Description

append

boolean

true

If true, the appender starts writing at the end of the file.

This setting does not give the same atomicity guarantees as for the RollingFile Appender. The log file cannot be opened by multiple applications at the same time.

Unlike the File appender, this appender always uses an internal buffer of size bufferSize.

📖 Plugin reference for RandomAccessFile

MemoryMappedFile configuration

The MemoryMappedFile Appender provides the following configuration options, beyond the common ones:

Table 5. RollingRandomAccessFile configuration attributes
Attribute Type Default value Description

append

boolean

true

If true, the appender starts writing at the end of the file.

This setting does not give the same atomicity guarantees as for the RollingFile Appender. The log file cannot be opened by multiple applications at the same time.

regionLength

int

32 × 1024 × 1024

It specifies the size measured in bytes of the memory mapped log file buffer.

Unlike other file appenders, this appender always uses a memory mapped buffer of size regionLength as its internal buffer.

📖 Plugin reference for MemoryMappedFile