指標和管理

本節介紹如何捕獲 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`。

defaultLoggingEnabled 僅在您未在 bean 定義中明確配置相應設定時應用。

Micrometer 整合

概述

從版本 5.0.3 開始，應用上下文中存在 Micrometer MeterRegistry 將觸發對 Micrometer 指標的支援。

要使用 Micrometer，請將其中一個 MeterRegistry bean 新增到應用上下文中。

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

這僅適用於繼承 AbstractMessageHandler, AbstractMessageChannel, 和 AbstractMessageSource 的物件（大多數框架元件都是如此）。

訊息通道傳送操作的 Timer Meters 具有以下名稱或標籤

name: spring.integration.send
tag: type:channel
tag: name:<componentName>
tag: result:(success|failure)
tag: exception:(none|exception simple class name)
description: Send processing time

（一個 failure 結果且異常為 none 意味著通道的 send() 操作返回了 false。）

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

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

訊息處理器操作的 Timer Meters 具有以下名稱或標籤

name: spring.integration.send
tag: type:handler
tag: name:<componentName>
tag: result:(success|failure)
tag: exception:(none|exception simple class name)
description: Send processing time

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

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

此外，還有三個 Gauge Meters

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

可以透過提供 MicrometerMetricsCaptor 的子類來定製整合元件建立的 Meters 的名稱和標籤。 MicrometerCustomMetricsTests 測試用例展示了一個簡單的例子。您還可以透過過載構建器子類上的 build() 方法來進一步定製 meters。

從版本 5.1.13 開始，QueueChannel 會暴露 Micrometer gauges，用於顯示佇列大小和剩餘容量

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: 佇列通道的剩餘容量

停用 Meters

預設情況下，所有 meters 在首次使用時註冊。現在，使用 Micrometer，您可以將 MeterFilter 新增到 MeterRegistry 中，以阻止部分或全部 meters 被註冊。您可以根據提供的任何屬性（name, tag 等）過濾（拒絕）meters。有關更多資訊，請參閱 Micrometer 文件中的 Meter Filters。

例如，假設有以下配置

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

您可以使用以下配置抑制僅針對此通道的 meters 註冊

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 配置，該抽象可以處理指標以及 tracing（追蹤）。

當應用上下文中存在 ObservationRegistry bean 並配置了 @EnableIntegrationManagement 時，將在 IntegrationManagement 元件上啟用觀察處理。要自定義應進行檢測的元件集，可以在 @EnableIntegrationManagement 註解上暴露 observationPatterns() 屬性。有關模式匹配演算法，請參閱其 javadocs。

預設情況下，沒有 IntegrationManagement 元件使用 ObservationRegistry bean 進行檢測。可以配置為 * 以匹配所有元件。

在這種情況下，meters 不是獨立收集的，而是委託給在提供的 ObservationRegistry 上配置的適當的 ObservationHandler。

以下 Spring Integration 元件已使用觀察邏輯進行檢測，每個元件都遵循各自的約定

MessageProducerSupport 作為流的入站端點，被視為 CONSUMER span 型別，並使用 IntegrationObservation.HANDLER API；
MessagingGatewaySupport 是一個入站請求-回覆端點，被視為 SERVER span 型別。它使用 IntegrationObservation.GATEWAY API；
AbstractMessageChannel.send() 操作是 Spring Integration API 中唯一產生訊息的操作。因此，它被視為 PRODUCER span 型別，並使用 IntegrationObservation.PRODUCER API。當通道是分散式實現（例如 PublishSubscribeKafkaChannel 或 ZeroMqChannel）並且需要將追蹤資訊新增到訊息中時，這更有意義。因此，IntegrationObservation.PRODUCER 觀察基於 MessageSenderContext，其中 Spring Integration 提供了一個 MutableMessage，以允許後續的追蹤 Propagator 新增頭資訊，從而使這些頭資訊對消費者可用；
AbstractMessageHandler 是一個 CONSUMER span 型別，並使用 IntegrationObservation.HANDLER API。

IntegrationManagement 元件上的觀察生產可以透過 ObservationConvention 配置進行自定義。例如，AbstractMessageHandler 透過其 setObservationConvention() API 期望一個 MessageReceiverObservationConvention。

以下是 Observation API 支援的指標、span 和約定

可觀察性 - 指標

下面列出了本專案宣告的所有指標。

閘道器

入站訊息閘道器的觀察。

指標名稱 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 啟動後新增的 KeyValues 可能不會出現在 *.active 指標中。

Micrometer 內部使用 nanoseconds 作為基本單位。但是，每個後端會確定實際的基本單位。（即 Prometheus 使用 seconds）

包含類 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 啟動後新增的 KeyValues 可能不會出現在 *.active 指標中。

Micrometer 內部使用 nanoseconds 作為基本單位。但是，每個後端會確定實際的基本單位。（即 Prometheus 使用 seconds）

包含類 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 啟動後新增的 KeyValues 可能不會出現在 *.active 指標中。

Micrometer 內部使用 nanoseconds 作為基本單位。但是，每個後端會確定實際的基本單位。（即 Prometheus 使用 seconds）

包含類 o.s.i.support.management.observation.IntegrationObservation 的完全限定名。

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

表 3. 低基數鍵
名稱	描述
`spring.integration.name` （必填）	訊息處理器元件的名稱。
`spring.integration.type` （必填）	元件型別 - 'producer'。

可觀察性 - Span

下面列出了本專案宣告的所有 span。

閘道器 Span

入站訊息閘道器的觀察。

Span 名稱 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'。

名稱

訊息處理器的觀察。

處理器 Span

包含類 o.s.i.support.management.observation.IntegrationObservation 的完全限定名。

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

**Span 名稱** `spring.integration.handler`（由約定類 `o.s.i.support.management.observation.DefaultMessageReceiverObservationConvention` 定義）。
名稱	描述
`spring.integration.name` （必填）	訊息處理器元件的名稱。
`spring.integration.type` （必填）	元件型別 - 'handler'。

表 5. 標籤鍵

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

生產者 Span

包含類 o.s.i.support.management.observation.IntegrationObservation 的完全限定名。

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

**Span 名稱** `spring.integration.producer`（由約定類 `o.s.i.support.management.observation.DefaultMessageSenderObservationConvention` 定義）。
名稱	描述
`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`

觀察傳播

為了在一個 trace 中提供連線的 span 鏈，無論訊息流的性質如何（即使 MessageChannel 是持久化和分散式的），都必須在此通道及其消費者（訂閱者）上啟用觀察。這樣，追蹤資訊在傳播到消費者執行緒或持久化到資料庫之前，會儲存在訊息頭中。這是透過上面提到的 MessageSenderContext 完成的。消費者（一個 MessageHandler）側使用 MessageReceiverContext 從這些頭資訊中恢復追蹤資訊，並啟動一個新的子 Observation。

Spring Integration JMX 支援

另請參見 JMX 支援。