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 the 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

File appenders

Appenders

Common configuration

File configuration

RandomAccessFile configuration

MemoryMappedFile configuration

`File` configuration

`RandomAccessFile` configuration

`MemoryMappedFile` configuration