Log4j2 中的 Appenders

Appenders 负责将日志事件传递到目的地。每个 Appender 必须实现 Appender 接口。

虽然 Log4j Core 架构不要求严格遵守，但大多数 Appender 都继承自 AbstractAppender，并且：

将日志事件的过滤委托给 Filter 接口的实现。
将日志事件的格式化委托给 Layout 接口的实现。
直接处理将日志事件数据写入目标目的地的操作。

Appenders 始终有一个名称，以便可以从日志记录器配置中引用它们。

一、常见问题

1、缓冲

使用流式资源（如文件、TCP 连接）的 Appenders 拥有一个内部的 ByteBuffer，可以在将每个日志事件发送到底层资源之前对其进行格式化。缓冲区在以下情况发生时使用：

log4j2.enableDirectEncoders 配置属性被启用
bufferedIo 配置属性被启用

缓冲区会在三种情况下刷新到底层资源：

如果缓冲区已满
如果使用了异步 Loggers 或 Appenders，则在每个日志事件批次结束时刷新
如果 immediateFlush 配置属性为 true，则在每个日志事件结束时刷新

这些配置属性由多个 Appenders 共享：

bufferSize

类型：int
默认值：log4j2.encoderByteBufferSize

这个配置属性指定了 Appender 使用的 ByteBuffer 的大小。

bufferedIo

类型：boolean
默认值：true

如果设置为 true，Log4j Core 将使用内部的 ByteBuffer 来存储日志事件，然后再发送它们。

如果 log4j2.enableDirectEncoders 配置属性设置为 true，则内部的 ByteBuffer 始终会被使用。

immediateFlush

类型：boolean
默认值：true

如果设置为 true，Log4j 将在每个事件结束时刷新 Log4j Core 和 Java 缓冲区：

Appender 的内部 ByteBuffer 将被刷新。
对于基于 Java 的 OutputStream 的 Appenders，将调用 OutputStream.flush() 方法。
这个设置仅保证日志事件的字节表示形式被传递给操作系统，但不确保操作系统将事件写入底层存储。
如果你使用的是异步 Loggers 或 Appenders，可以将此属性设置为 false。即使在这种情况下，Log4j Core 也会在日志事件队列为空时刷新内部缓冲区。

2、异常处理

默认情况下，Log4j Core 使用 Status Logger 来报告在 Appenders 中发生的异常。可以通过以下配置属性来更改这一行为：

ignoreExceptions

类型：boolean
默认值：true

如果设置为 false，日志记录异常将被转发给调用者。否则，异常将使用 Status Logger 记录。

如果你的业务中日志记录非常重要，可以考虑使用 Failover Appender。Failover Appender 可以在发生异常时将日志事件重定向到不同的 Appender。

3、运行时属性赋值

以下配置属性也在运行时进行评估，因此可以包含转义的 $${…} 属性替换表达式。

Component	Parameter	Event type	Evaluation context
HTTP Appender	Property/value	Log event	global
Kafka Appender	key	Log event	global
NoSQL Appender	KeyValuePair/value	Log event	global
PropertiesRewrite Policy	Property/value	Log event	global
Routes Container	pattern	Log event	log event
Rolling File Appenders	filePattern	Rollover	global
Optional Rollover Actions	basePath	Rollover	global

Routing Appender 的 Route 组件是特殊的：其子元素在运行时被评估，但在配置时不会被评估。在 Route 组件内部，你不应该使用转义的 $${...} 属性替换表达式，而应该只使用未转义的 ${...} 属性替换表达式。

二、Appender

Log4j 捆绑了几个预定义的附加器，以帮助处理几个常见的部署用例。它们根据目标资源记录在单独的页面中：

Console Appender
File Appenders
Database Appenders
Network Appenders
Message Queue Appenders
Servlet Appender
Delegating Appenders

1、Console Appender

Console Appender 将其输出写入标准输出或标准错误输出。

1.1 访问输出流方式

该 Appender 支持四种不同的方式来访问输出流：

1.1.1 direct

这种模式提供最佳性能。可以通过将 direct 属性设置为 true 来启用。

1.1.2 default

默认情况下，Console Appender 使用配置时的 System.out 或 System.err 的值。运行时对这些流的任何更改都将被忽略。

1.1.3 follow

这种模式始终使用 System.out 和 System.err 的当前值。可以通过将 follow 属性设置为 true 来启用。

此设置在多应用程序环境中可能很有用。一些应用程序服务器修改 System.out 和 System.err，使其始终指向当前运行的应用程序。

1.1.4 JANSI

如果应用程序在 Windows 上运行并且 JANSI 库可用，Console Appender 将使用 JANSI 来模拟 ANSI 序列支持。可以通过将 log4j2.skipJansi 配置属性设置为 true 来禁用此模式。

使用 JANSI 需要额外的运行时依赖关系：

<dependency>
    <groupId>org.fusesource.jansi</groupId>
    <artifactId>jansi</artifactId>
    <version>1.18</version>
</dependency>

1.2 Console Appender 的属性和子元素

1.2.1 必须属性

属性	类型	默认值	描述
`name`	`String`		Appender 的名称

1.2.2 可选属性

bufferSize

int 类型，默认值为 8192

Appender 内部的 ByteBuffer 的大小。

direct

boolean 类型，默认值为 false

如果设置为 true，日志事件将直接写入 FileDescriptor.out 或 FileDescriptor.err。

此设置绕过了 System.out 和 System.err 的缓冲，可能会提供与 File Appender 相当的性能。

如果其他日志记录后台或应用程序本身使用了 System.out 或 System.err，将此设置为 true 可能会导致输出交错。

此设置与 follow 属性和 JANSI 支持不兼容。

follow

boolean 类型，默认值为 false

如果设置为 true，Appender 将尊重通过 System.setOut 或 System.setErr 对 System.out或 System.err 的重新赋值。

否则，将使用配置时的 System.out 或 System.err 的值。

此设置与 direct 属性和 JANSI 支持不兼容。

ignoreExceptions

boolean 类型，默认值为 true

如果设置为 false，日志记录异常将被转发给日志记录语句的调用者。否则，这些异常将被忽略。

日志记录异常总是还会被记录到 Status Logger。

immediateFlush

如果设置为 true，Appender 将在每个日志事件后刷新其内部缓冲区以及 System.out 或 System.err 流的缓冲区。

target

Target 类型，默认值 SYSTEM_OUT

指定使用的标准输出流。

可选值：

SYSTEM_OUT，使用标准输出
SYSTEM_ERR，使用标准异常输出

1.2.3 嵌套子元素

Filter

0 个或 1 个

允许在格式化和发送日志事件之前对其进行过滤。

Layout

0 个或 1 个

格式化日志事件。

1.3 配置示例

1
2
3

<Console name="CONSOLE">
    <PatternLayout pattern="%d [%t] %p %c - %m%n"/>
</Console>

1
2
3

<Console name="CONSOLE" direct="true">
     <JsonTemplateLayout/>
</Console>

2、File Appenders

FileAppender 和 RollingFileAppender 是两种常用的将日志消息写入文件的 Appender。它们的主要区别在于处理日志文件的方式和性能特性。

FileAppender 是最基本的文件 Appender，它将日志消息写入指定的文件中。

RollingFileAppender 是 FileAppender 的扩展，它支持日志文件的自动轮转。这意味着当满足某些条件（如文件大小、时间间隔等）时，当前的日志文件会被归档，新的日志文件会被创建。