日志子系统 AMQP 附加器

该框架为一些流行的日志子系统提供日志附加器。

logback（自 Spring AMQP 1.4 版本起）
log4j2（自 Spring AMQP 1.6 版本起）

附加器通过日志子系统的常规机制进行配置，可用属性在以下部分指定。

通用属性

以下属性可用于所有附加器。

表 1. 通用附加器属性
属性	默认值	描述
exchangeName	logs	要发布日志事件的交换机的名称。
exchangeType	topic	要发布日志事件的交换机的类型 - 仅当附加器声明交换机时才需要。请参阅 `declareExchange`。
routingKeyPattern	%c.%p	用于生成路由键的日志子系统模式格式。
applicationId		应用程序 ID - 如果模式包含 `%X{applicationId}`，则将其添加到路由键中。
senderPoolSize	2	用于发布日志事件的线程数。
maxSenderRetries	30	如果代理不可用或出现其他错误，重试发送消息的次数。重试延迟如下：`N ^ log(N)`，其中 `N` 是重试次数。
addresses		以以下形式表示的代理地址的逗号分隔列表：`host:port[,host:port]*` - 覆盖 `host` 和 `port`。
host	localhost	要连接的 RabbitMQ 主机。
port	5672	要连接的 RabbitMQ 端口。
virtualHost	/	要连接的 RabbitMQ 虚拟主机。
username	guest	连接时要使用的 RabbitMQ 用户。
password	guest	此用户的 RabbitMQ 密码。
useSsl	false	是否对 RabbitMQ 连接使用 SSL。请参阅 `RabbitConnectionFactoryBean` 和配置 SSL
verifyHostname	true	启用 TLS 连接的服务器主机名验证。请参阅 `RabbitConnectionFactoryBean` 和配置 SSL
sslAlgorithm	null	要使用的 SSL 算法。
sslPropertiesLocation	null	SSL 属性文件的路径。
keyStore	null	密钥库的路径。
keyStorePassphrase	null	密钥库的密码短语。
keyStoreType	JKS	密钥库类型。
trustStore	null	信任库的路径。
trustStorePassphrase	null	信任库的密码短语。
trustStoreType	JKS	信任库类型。
saslConfig	null (RabbitMQ client default applies)	`saslConfig` - 有关有效值，请参阅 `RabbitUtils.stringToSaslConfig` 的 javadoc。
contentType	text/plain	日志消息的 `content-type` 属性。
contentEncoding		日志消息的 `content-encoding` 属性。
declareExchange	false	此附加器启动时是否声明配置的交换机。另请参阅 `durable` 和 `autoDelete`。
durable	true	当 `declareExchange` 为 `true` 时，持久性标志设置为此值。
autoDelete	false	当 `declareExchange` 为 `true` 时，自动删除标志设置为此值。
charset	null	将 `String` 转换为 `byte[]` 时要使用的字符集。默认值：null（使用系统默认字符集）。如果当前平台不支持字符集，我们将回退到使用系统字符集。
deliveryMode	PERSISTENT	`PERSISTENT` 或 `NON_PERSISTENT`，用于确定 RabbitMQ 是否应持久化消息。
generateId	false	用于确定是否将 `messageId` 属性设置为唯一值。
clientConnectionProperties	null	RabbitMQ 连接的自定义客户端属性的逗号分隔的 `key:value` 对列表。
addMdcAsHeaders	true	在引入此属性之前，MDC 属性始终会被添加到 RabbitMQ 消息头中。对于大型 MDC，这可能会导致问题，因为 RabbitMQ 对所有头的缓冲区大小有限，并且此缓冲区非常小。引入此属性是为了避免在大型 MDC 情况下出现问题。默认情况下，此值为 `true`，以保持向后兼容性。`false` 会关闭将 MDC 序列化到头部的功能。请注意，`JsonLayout` 默认会将 MDC 添加到消息中。

Log4j 2 附加器

以下示例显示了如何配置 Log4j 2 附加器

<Appenders>
    ...
    <RabbitMQ name="rabbitmq"
        addresses="foo:5672,bar:5672" user="guest" password="guest" virtualHost="/"
        exchange="log4j2" exchangeType="topic" declareExchange="true" durable="true" autoDelete="false"
        applicationId="myAppId" routingKeyPattern="%X{applicationId}.%c.%p"
        contentType="text/plain" contentEncoding="UTF-8" generateId="true" deliveryMode="NON_PERSISTENT"
        charset="UTF-8"
        senderPoolSize="3" maxSenderRetries="5"
        addMdcAsHeaders="false">
    </RabbitMQ>
</Appenders>

从 1.6.10 和 1.7.3 版本开始，默认情况下，log4j2 附加器会在调用线程上将消息发布到 RabbitMQ。这是因为 Log4j 2 默认情况下不会创建线程安全的事件。如果代理宕机，则使用 maxSenderRetries 进行重试，重试之间没有延迟。如果您希望恢复在单独线程 (senderPoolSize) 上发布消息的先前行为，可以将 async 属性设置为 true。但是，您还需要配置 Log4j 2 以使用 DefaultLogEventFactory 而不是 ReusableLogEventFactory。一种方法是设置系统属性 -Dlog4j2.enable.threadlocals=false。如果您使用异步发布和 ReusableLogEventFactory，则由于交叉对话，事件很可能被破坏。

Logback 附加器

以下示例显示了如何配置 logback 附加器

<appender name="AMQP" class="org.springframework.amqp.rabbit.logback.AmqpAppender">
    <layout>
        <pattern><![CDATA[ %d %p %t [%c] - <%m>%n ]]></pattern>
    </layout>
    <addresses>foo:5672,bar:5672</addresses>
    <abbreviation>36</abbreviation>
    <includeCallerData>false</includeCallerData>
    <applicationId>myApplication</applicationId>
    <routingKeyPattern>%property{applicationId}.%c.%p</routingKeyPattern>
    <generateId>true</generateId>
    <charset>UTF-8</charset>
    <durable>false</durable>
    <deliveryMode>NON_PERSISTENT</deliveryMode>
    <declareExchange>true</declareExchange>
    <addMdcAsHeaders>false</addMdcAsHeaders>
</appender>

从 1.7.1 版本开始，Logback 的 AmqpAppender 提供了一个 includeCallerData 选项，默认值为 false。提取调用者数据可能相当昂贵，因为日志事件必须创建一个 Throwable 并检查它以确定调用位置。因此，默认情况下，当事件添加到事件队列时，不会提取与事件关联的调用者数据。您可以通过将 includeCallerData 属性设置为 true 来配置附加器以包含调用者数据。

从 2.0.0 版本开始，Logback 的 AmqpAppender 支持使用 encoder 选项的 Logback 编码器。encoder 和 layout 选项是互斥的。

自定义消息

默认情况下，AMQP 附加器会填充以下消息属性

deliveryMode
contentType
如果已配置，则为 contentEncoding
如果已配置 generateId，则为 messageId
日志事件的 timestamp
如果已配置 applicationId，则为 appId

此外，它们还会使用以下值填充标头

日志事件的 categoryName
日志事件的级别
thread：发生日志事件的线程名称
日志事件调用堆栈跟踪的位置
所有 MDC 属性的副本（除非将 addMdcAsHeaders 设置为 false）

每个附加器都可以被子类化，让您在发布之前修改消息。以下示例显示了如何自定义日志消息

public class MyEnhancedAppender extends AmqpAppender {

    @Override
    public Message postProcessMessageBeforeSend(Message message, Event event) {
        message.getMessageProperties().setHeader("foo", "bar");
        return message;
    }

}

从 2.2.4 版本开始，log4j2 的 AmqpAppender 可以使用 @PluginBuilderFactory 扩展，并扩展 AmqpAppender.Builder。

@Plugin(name = "MyEnhancedAppender", category = "Core", elementType = "appender", printObject = true)
public class MyEnhancedAppender extends AmqpAppender {

	public MyEnhancedAppender(String name, Filter filter, Layout<? extends Serializable> layout,
			boolean ignoreExceptions, AmqpManager manager, BlockingQueue<Event> eventQueue, String foo, String bar) {
		super(name, filter, layout, ignoreExceptions, manager, eventQueue);

	@Override
	public Message postProcessMessageBeforeSend(Message message, Event event) {
			message.getMessageProperties().setHeader("foo", "bar");
		return message;
	}

	@PluginBuilderFactory
	public static Builder newBuilder() {
		return new Builder();
	}

	protected static class Builder extends AmqpAppender.Builder {

		@Override
		protected AmqpAppender buildInstance(String name, Filter filter, Layout<? extends Serializable> layout,
				boolean ignoreExceptions, AmqpManager manager, BlockingQueue<Event> eventQueue) {
			return new MyEnhancedAppender(name, filter, layout, ignoreExceptions, manager, eventQueue);
		}
	}

}

自定义客户端属性

您可以通过添加字符串属性或更复杂的属性来添加自定义客户端属性。

简单的字符串属性

每个附加器都支持向 RabbitMQ 连接添加客户端属性。

以下示例显示了如何为 logback 添加自定义客户端属性

<appender name="AMQP" ...>
    ...
    <clientConnectionProperties>thing1:thing2,cat:hat</clientConnectionProperties>
    ...
</appender>

log4j2

<Appenders>
    ...
    <RabbitMQ name="rabbitmq"
        ...
        clientConnectionProperties="thing1:thing2,cat:hat"
        ...
    </RabbitMQ>
</Appenders>

属性是 key:value 对的逗号分隔列表。键和值不能包含逗号或冒号。

当查看连接时，这些属性会显示在 RabbitMQ 管理 UI 上。

Logback 的高级技巧

您可以对 Logback 附加器进行子类化。这样做可以让您在建立连接之前修改客户端连接属性。以下示例显示了如何操作

public class MyEnhancedAppender extends AmqpAppender {

    private String thing1;

    @Override
    protected void updateConnectionClientProperties(Map<String, Object> clientProperties) {
        clientProperties.put("thing1", this.thing1);
    }

    public void setThing1(String thing1) {
        this.thing1 = thing1;
    }

}

然后，您可以将 <thing1>thing2</thing1> 添加到 logback.xml 中。

对于前面示例中所示的字符串属性，可以使用先前的技术。子类允许添加更丰富的属性（例如添加 Map 或数字属性）。

提供自定义队列实现

AmqpAppenders 使用 BlockingQueue 将日志事件异步发布到 RabbitMQ。默认情况下，使用 LinkedBlockingQueue。但是，您可以提供任何类型的自定义 BlockingQueue 实现。

以下示例显示了如何为 Logback 操作

public class MyEnhancedAppender extends AmqpAppender {

    @Override
    protected BlockingQueue<Event> createEventQueue() {
        return new ArrayBlockingQueue();
    }

}

Log4j 2 附加器支持使用 BlockingQueueFactory，如下例所示

<Appenders>
    ...
    <RabbitMQ name="rabbitmq"
              bufferSize="10" ... >
        <ArrayBlockingQueue/>
    </RabbitMQ>
</Appenders>