指標與管理

本節說明如何擷取 Spring Integration 的指標。在最近的版本中，我們更加依賴 Micrometer (請參閱 micrometer.io)，我們計劃在未來的版本中更廣泛地使用 Micrometer。

在高容量環境中停用記錄

您可以控制主要訊息流程中的偵錯記錄。在非常高容量的應用程式中，對 isDebugEnabled() 的呼叫在某些記錄子系統中可能會非常耗費資源。您可以停用所有此類記錄，以避免這種額外負擔。例外狀況記錄 (無論是否為偵錯) 不受此設定的影響。

以下列表顯示了用於控制記錄的可用選項

Java
XML

@Configuration
@EnableIntegration
@EnableIntegrationManagement(
    defaultLoggingEnabled = "true" <1>)

public static class ContextConfiguration {
...
}

<int:management default-logging-enabled="true"/> (1)

1	設定為 `false` 以停用主要訊息流程中的所有記錄，無論記錄系統類別設定為何。設定為 'true' 以啟用偵錯記錄 (如果記錄子系統也啟用偵錯記錄)。僅在您未在 Bean 定義中明確設定此設定時套用。預設值為 `true`。

只有在您未在 Bean 定義中明確設定對應設定時，才會套用 defaultLoggingEnabled。

Micrometer 整合

總覽

從 5.0.3 版開始，應用程式環境定義中存在 Micrometer MeterRegistry 會觸發對 Micrometer 指標的支援。

若要使用 Micrometer，請將其中一個 MeterRegistry Bean 新增至應用程式環境定義。

針對每個 MessageHandler 和 MessageChannel，都會註冊計時器。針對每個 MessageSource，都會註冊計數器。

這僅適用於擴充 AbstractMessageHandler、AbstractMessageChannel 和 AbstractMessageSource 的物件 (大多數架構元件都是這種情況)。

訊息通道上傳送作業的 Timer Meter 具有以下名稱或標籤

name: spring.integration.send
tag: type:channel
tag: name:<componentName>
tag: result:(success|failure)
tag: exception:(none|exception simple class name)
description: 傳送處理時間

(failure 結果和 none 例外狀況表示通道的 send() 作業傳回 false。)

可輪詢訊息通道上接收作業的 Counter Meter 具有以下名稱或標籤

name: spring.integration.receive
tag: type:channel
tag: name:<componentName>
tag: result:(success|failure)
tag: exception:(none|exception simple class name)
description: 已接收訊息

訊息處理器上作業的 Timer Meter 具有以下名稱或標籤

name: spring.integration.send
tag: type:handler
tag: name:<componentName>
tag: result:(success|failure)
tag: exception:(none|exception simple class name)
description: 傳送處理時間

訊息來源的 Counter Meter 具有以下名稱/標籤

name: spring.integration.receive
tag: type:source
tag: name:<componentName>
tag: result:success
tag: exception:none
description: 已接收訊息

此外，還有三個 Gauge Meter

spring.integration.channels: 應用程式中 MessageChannels 的數量。
spring.integration.handlers: 應用程式中 MessageHandlers 的數量。
spring.integration.sources: 應用程式中 MessageSources 的數量。

可以透過提供 MicrometerMetricsCaptor 的子類別來自訂整合元件建立的 Meters 名稱和標籤。MicrometerCustomMetricsTests 測試案例顯示了如何執行此操作的簡單範例。您也可以透過在 builder 子類別上多載 build() 方法來進一步自訂 Meter。

從 5.1.13 版開始，QueueChannel 公開了 Micrometer Gauge，用於佇列大小和剩餘容量

name: spring.integration.channel.queue.size
tag: type:channel
tag: name:<componentName>
description: 佇列通道的大小

和

name: spring.integration.channel.queue.remaining.capacity
tag: type:channel
tag: name:<componentName>
description: 佇列通道的剩餘容量

停用 Meter

預設情況下，所有 Meter 都會在首次使用時註冊。現在，使用 Micrometer，您可以將 MeterFilter 新增至 MeterRegistry，以防止註冊部分或全部 Meter。您可以依提供的任何屬性 (name、tag 等) 篩選 (拒絕) Meter。如需詳細資訊，請參閱 Micrometer 文件中的 Meter Filters。

例如，假設

@Bean
public QueueChannel noMeters() {
    return new QueueChannel(10);
}

您可以使用以下方式禁止註冊僅適用於此通道的 Meter

registry.config().meterFilter(MeterFilter.deny(id ->
        "channel".equals(id.getTag("type")) &&
        "noMeters".equals(id.getTag("name"))));

Micrometer Observation

從 6.0 版開始，Spring Integration 利用 Micrometer Observation 抽象概念，此抽象概念可以處理指標以及透過適當的 ObservationHandler 設定進行追蹤。

只要應用程式環境定義中存在 ObservationRegistry Bean 且已設定 @EnableIntegrationManagement，就會在 IntegrationManagement 元件上啟用觀察處理。若要自訂應檢測哪些元件集，@EnableIntegrationManagement 註解上會公開 observationPatterns() 屬性。如需模式比對演算法，請參閱其 Javadoc。

預設情況下，沒有任何 IntegrationManagement 元件使用 ObservationRegistry Bean 進行檢測。可以設定為 * 以比對所有元件。

在這種情況下，不會獨立收集 Meter，而是委派給在提供的 ObservationRegistry 上設定的適當 ObservationHandler。

以下 Spring Integration 元件使用觀察邏輯進行檢測，每個元件都有各自的慣例

MessageProducerSupport 作為流程的輸入端點，被視為 CONSUMER 範圍類型，並使用 IntegrationObservation.HANDLER API；
MessagingGatewaySupport` 是輸入請求-回覆端點，被視為 SERVER 範圍類型。它使用 IntegrationObservation.GATEWAY API；
AbstractMessageChannel.send() 作業是唯一的 Spring Integration API，它會產生訊息。因此，它被視為 PRODUCER 範圍類型，並使用 IntegrationObservation.PRODCUER API。當通道是分散式實作 (例如 PublishSubscribeKafkaChannel 或 ZeroMqChannel) 且追蹤資訊必須新增至訊息時，這更有意義。因此，IntegrationObservation.PRODUCER 觀察是基於 MessageSenderContext，其中 Spring Integration 提供 MutableMessage，以允許後續的追蹤 Propagator 新增標頭，以便它們可供消費者使用；
AbstractMessageHandler 是 CONSUMER 範圍類型，並使用 IntegrationObservation.HANDLER API。

可以透過 ObservationConvention 設定來自訂 IntegrationManagement 元件上的觀察產生。例如，AbstractMessageHandler 透過其 setObservationConvention() API 預期 MessageReceiverObservationConvention。

以下是 Observation API 支援的指標、範圍和慣例

可觀察性 - 指標

您可以在下方找到此專案宣告的所有指標清單。

閘道

輸入訊息閘道的觀察。

指標名稱 spring.integration.gateway (由慣例類別 o.s.i.support.management.observation.DefaultMessageRequestReplyReceiverObservationConvention 定義)。類型 timer。

指標名稱 spring.integration.gateway.active (由慣例類別 o.s.i.support.management.observation.DefaultMessageRequestReplyReceiverObservationConvention 定義)。類型 long task timer。

從 Observation 開始後新增的 KeyValue 可能會從 *.active 指標中遺失。

Micrometer 在內部使用 奈秒 作為基本單位。但是，每個後端都會決定實際的基本單位。(亦即 Prometheus 使用秒)

封閉類別 o.s.i.support.management.observation.IntegrationObservation 的完整名稱。

所有標籤都必須以 spring.integration. 字首開頭！

表 1. 低基數索引鍵
名稱	描述
`spring.integration.name` (必要)	訊息閘道元件的名稱。
`spring.integration.outcome` (必要)	請求/回覆執行的結果。
`spring.integration.type` (必要)	元件的類型 - 'gateway'。

處理器

訊息處理器的觀察。

指標名稱 spring.integration.handler (由慣例類別 o.s.i.support.management.observation.DefaultMessageReceiverObservationConvention 定義)。類型 timer。

指標名稱 spring.integration.handler.active (由慣例類別 o.s.i.support.management.observation.DefaultMessageReceiverObservationConvention 定義)。類型 long task timer。

從 Observation 開始後新增的 KeyValue 可能會從 *.active 指標中遺失。

Micrometer 在內部使用 奈秒 作為基本單位。但是，每個後端都會決定實際的基本單位。(亦即 Prometheus 使用秒)

封閉類別 o.s.i.support.management.observation.IntegrationObservation 的完整名稱。

所有標籤都必須以 spring.integration. 字首開頭！

表 2. 低基數索引鍵
名稱	描述
`spring.integration.name` (必要)	訊息處理器元件的名稱。
`spring.integration.type` (必要)	元件的類型 - 'handler'。

生產者

訊息生產者 (例如通道) 的觀察。

指標名稱 spring.integration.producer (由慣例類別 o.s.i.support.management.observation.DefaultMessageSenderObservationConvention 定義)。類型 timer。

指標名稱 spring.integration.producer.active (由慣例類別 o.s.i.support.management.observation.DefaultMessageSenderObservationConvention 定義)。類型 long task timer。

從 Observation 開始後新增的 KeyValue 可能會從 *.active 指標中遺失。

Micrometer 在內部使用 奈秒 作為基本單位。但是，每個後端都會決定實際的基本單位。(亦即 Prometheus 使用秒)

封閉類別 o.s.i.support.management.observation.IntegrationObservation 的完整名稱。

所有標籤都必須以 spring.integration. 字首開頭！

表 3. 低基數索引鍵
名稱	描述
`spring.integration.name` (必要)	訊息處理器元件的名稱。
`spring.integration.type` (必要)	元件的類型 - 'producer'。

可觀察性 - 範圍

您可以在下方找到此專案宣告的所有範圍清單。

閘道範圍

輸入訊息閘道的觀察。

範圍名稱 spring.integration.gateway (由慣例類別 o.s.i.support.management.observation.DefaultMessageRequestReplyReceiverObservationConvention 定義)。

封閉類別 o.s.i.support.management.observation.IntegrationObservation 的完整名稱。

所有標籤都必須以 spring.integration. 字首開頭！

表 4. 標籤索引鍵
名稱	描述
`spring.integration.name` (必要)	訊息閘道元件的名稱。
`spring.integration.outcome` (必要)	請求/回覆執行的結果。
`spring.integration.type` (必要)	元件的類型 - 'gateway'。

處理器範圍

訊息處理器的觀察。

範圍名稱 spring.integration.handler (由慣例類別 o.s.i.support.management.observation.DefaultMessageReceiverObservationConvention 定義)。

封閉類別 o.s.i.support.management.observation.IntegrationObservation 的完整名稱。

所有標籤都必須以 spring.integration. 字首開頭！

表 5. 標籤索引鍵
名稱	描述
`spring.integration.name` (必要)	訊息處理器元件的名稱。
`spring.integration.type` (必要)	元件的類型 - 'handler'。

生產者範圍

訊息生產者 (例如通道) 的觀察。

範圍名稱 spring.integration.producer (由慣例類別 o.s.i.support.management.observation.DefaultMessageSenderObservationConvention 定義)。

封閉類別 o.s.i.support.management.observation.IntegrationObservation 的完整名稱。

所有標籤都必須以 spring.integration. 字首開頭！

表 6. 標籤索引鍵
名稱	描述
`spring.integration.name` (必要)	訊息處理器元件的名稱。
`spring.integration.type` (必要)	元件的類型 - 'producer'。

可觀察性 - 慣例

您可以在下方找到此專案宣告的所有 GlobalObservationConvention 和 ObservationConvention 清單。

表 7. ObservationConvention 實作
ObservationConvention 類別名稱	適用的 ObservationContext 類別名稱
`o.s.i.support.management.observation.DefaultMessageReceiverObservationConvention`	`MessageReceiverContext`
`o.s.i.support.management.observation.MessageReceiverObservationConvention`	`MessageReceiverContext`
`o.s.i.support.management.observation.DefaultMessageRequestReplyReceiverObservationConvention`	`MessageRequestReplyReceiverContext`
`o.s.i.support.management.observation.MessageRequestReplyReceiverObservationConvention`	`MessageRequestReplyReceiverContext`
`o.s.i.support.management.observation.DefaultMessageSenderObservationConvention`	`MessageSenderContext`
`o.s.i.support.management.observation.MessageSenderObservationConvention`	`MessageSenderContext`

觀察傳播

若要在一個追蹤中提供已連線的範圍鏈，而不論訊息流程的性質為何，即使 MessageChannel 是持久且分散式的，也必須在此通道和此通道的消費者 (訂閱者) 上啟用觀察。這樣，追蹤資訊會儲存在訊息標頭中，然後再傳播到消費者執行緒或保存到資料庫中。這是透過上述 MessageSenderContext 完成的。消費者 (MessageHandler) 端會使用 MessageReceiverContext 從這些標頭還原追蹤資訊，並啟動新的子 Observation。

Spring Integration JMX 支援

另請參閱 JMX 支援。