日誌子系統 AMQP Appender

該框架為一些流行的日誌子系統提供了日誌 appender

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

Appender 透過日誌子系統的常規機制進行配置，可用屬性在以下部分中指定。

通用屬性

所有 appender 均提供以下屬性

表 1. 通用 Appender 屬性
財產	預設值	描述
exchangeName	logs	釋出日誌事件的交換機名稱。
exchangeType	topic	釋出日誌事件的交換機型別——僅當 appender 宣告交換機時才需要。請參閱 `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	此 appender 啟動時是否宣告已配置的交換機。另請參閱 `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 Appender

以下示例展示瞭如何配置 Log4j 2 appender

<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 appender 在呼叫執行緒上將訊息釋出到 RabbitMQ。這是因為 Log4j 2 預設不建立執行緒安全事件。如果代理關閉，maxSenderRetries 用於重試，重試之間沒有延遲。如果您希望恢復在單獨執行緒（senderPoolSize）上釋出訊息的先前行為，可以將 async 屬性設定為 true。但是，您還需要配置 Log4j 2 以使用 DefaultLogEventFactory 而不是 ReusableLogEventFactory。一種方法是設定系統屬性 -Dlog4j2.enable.threadlocals=false。如果將非同步釋出與 ReusableLogEventFactory 一起使用，事件很可能因交叉通話而損壞。

Logback Appender

以下示例展示瞭如何配置 logback appender

<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。提取呼叫者資料可能相當耗費資源，因為日誌事件必須建立可丟擲物件並檢查它以確定呼叫位置。因此，預設情況下，當事件新增到事件佇列時，與事件關聯的呼叫者資料不會被提取。您可以透過將 includeCallerData 屬性設定為 true 來配置 appender 以包含呼叫者資料。

從 2.0.0 版本開始，Logback AmqpAppender 支援 Logback 編碼器，並提供 encoder 選項。encoder 和 layout 選項互斥。

自定義訊息

預設情況下，AMQP appender 填充以下訊息屬性

投遞模式
contentType
如果配置了 contentEncoding
如果配置了 generateId，則為 messageId
日誌事件的 timestamp
如果配置了 applicationId，則為 appId

此外，它們還使用以下值填充頭部

日誌事件的 categoryName
日誌事件的級別
thread：發生日誌事件的執行緒名稱
日誌事件呼叫的堆疊跟蹤位置
所有 MDC 屬性的副本（除非將 addMdcAsHeaders 設定為 false）

每個 appender 都可以被子類化，讓您在釋出之前修改訊息。以下示例展示瞭如何自定義日誌訊息

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);
		}
	}

}

自定義客戶端屬性

您可以透過新增字串屬性或更復雜的屬性來新增自定義客戶端屬性。

簡單字串屬性

每個 appender 都支援向 RabbitMQ 連線新增客戶端屬性。

以下示例展示瞭如何新增自定義客戶端屬性

logback
log4j2

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

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

屬性是逗號分隔的 key:value 對列表。鍵和值不能包含逗號或冒號。

當檢視連線時，這些屬性會顯示在 RabbitMQ Admin UI 上。

Logback 的高階技術

您可以子類化 Logback appender。這樣做可以讓您在建立連線之前修改客戶端連線屬性。以下示例展示瞭如何做到這一點

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 appender 支援使用 BlockingQueueFactory，如以下示例所示

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