指標と管理

このセクションでは、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 の 1 つをアプリケーションコンテキストに追加します。

MessageHandler および MessageChannel ごとに、タイマーが登録されます。MessageSource ごとに、カウンターが登録されます。

これは、AbstractMessageHandler、AbstractMessageChannel、AbstractMessageSource を継承するオブジェクトにのみ適用されます（ほとんどのフレームワークコンポーネントに当てはまります）。

メッセージチャネルの送信操作用の Timer メーターには、次の名前またはタグがあります。

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

（none 例外を含む failure 結果は、チャネルの send() 操作が false を返したことを意味します）

ポーリング可能なメッセージチャネルでの受信操作用の Counter メーターには、次の名前またはタグがあります。

name: spring.integration.receive
tag: type:channel
tag: name:<componentName>
tag: result:(success|failure)
tag: exception:(none|exception simple class name)
description: Messages received

メッセージハンドラーの操作用の Timer メーターには、次の名前またはタグがあります。

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 メーターには、次の名前 / タグがあります。

name: spring.integration.receive
tag: type:source
tag: name:<componentName>
tag: result:success
tag: exception:none
description: Messages received

さらに、3 つの Gauge メーターがあります。

spring.integration.channels: アプリケーション内の MessageChannels の数。
spring.integration.handlers: アプリケーション内の MessageHandlers の数。
spring.integration.sources: アプリケーション内の MessageSources の数。

MicrometerMetricsCaptor のサブクラスを提供することにより、統合コンポーネントによって作成された Meters の名前とタグをカスタマイズできます。MicrometerCustomMetricsTests [GitHub] (英語) テストケースは、その方法の簡単な例を示しています。ビルダーサブクラスの build() メソッドをオーバーロードすることにより、メーターをさらにカスタマイズすることもできます。

バージョン 5.1.13 以降、QueueChannel は、キューサイズと残り容量の Micrometer ゲージを公開します。

name: spring.integration.channel.queue.size
tag: type:channel
tag: name:<componentName>
description: The size of the queue channel

および

name: spring.integration.channel.queue.remaining.capacity
tag: type:channel
tag: name:<componentName>
description: The remaining capacity of the queue channel

メーターの無効化

デフォルトでは、最初の使用時にすべてのメーターが登録されます。Micrometer を使用すると、MeterFilter を MeterRegistry に追加して、一部またはすべてが登録されないようにすることができます。name、tag など、提供されている任意のプロパティでメーターを除外 (拒否) できます。詳細については、Micrometer ドキュメントのメーターフィルター (英語) を参照してください。

例: 与えられた:

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

次の方法で、このチャネルのみのメーターの登録を抑制することができます。

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 コンポーネントで監視処理が有効になります。計測するコンポーネントのセットをカスタマイズするために、observationPatterns() 属性が @EnableIntegrationManagement アノテーションで公開されます。パターンマッチングアルゴリズムについては、javadoc を参照してください。

デフォルトでは、ObservationRegistry Bean で計測される IntegrationManagement コンポーネントはありません。すべてのコンポーネントに一致するように * として構成できます。

この場合、メーターは個別に収集されませんが、提供された 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 を使用します。

IntegrationManagement コンポーネントの観測生成は、ObservationConvention 構成を介してカスタマイズできます。たとえば、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.

観測の開始後に追加された KeyValues は、*.active メトリクスから欠落している可能性があります。

Micrometer は、ベースユニットに nanoseconds を内部的に使用します。ただし、各バックエンドが実際のベースユニットを決定します。(つまり、Prometheus は秒を使用します)

外側のクラス o.s.i.support.management.observation.IntegrationObservation の完全修飾名。

すべてのタグには、spring.integration. プレフィックスを付ける必要があります。

表 1: カーディナリティの低いキー
名前	説明
`spring.integration.name` (必須)	メッセージゲートウェイコンポーネントの名前。
`spring.integration.outcome` (必須)	リクエスト / リプライ実行の結果。
`spring.integration.type` (必須)	コンポーネントの型 - 「ゲートウェイ」。

ハンドラー

メッセージハンドラーの観察。

指標名 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.

観測の開始後に追加された KeyValues は、*.active メトリクスから欠落している可能性があります。

外側のクラス o.s.i.support.management.observation.IntegrationObservation の完全修飾名。

すべてのタグには、spring.integration. プレフィックスを付ける必要があります。

表 2: カーディナリティの低いキー
名前	説明
`spring.integration.name` (必須)	メッセージハンドラーコンポーネントの名前。
`spring.integration.type` (必須)	コンポーネントの型 - 「ハンドラー」。

プロデューサー

メッセージプロデューサーの観察。チャンネル。

指標名 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.

観測の開始後に追加された KeyValues は、*.active メトリクスから欠落している可能性があります。

外側のクラス o.s.i.support.management.observation.IntegrationObservation の完全修飾名。

すべてのタグには、spring.integration. プレフィックスを付ける必要があります。

表 3: カーディナリティの低いキー
名前	説明
`spring.integration.name` (必須)	メッセージハンドラーコンポーネントの名前。
`spring.integration.type` (必須)	コンポーネントの型 - 「プロデューサー」。

可観測性 - スパン

以下に、このプロジェクトで宣言されたすべてのスパンのリストを示します。

ゲートウェイスパン

受信メッセージゲートウェイの監視。

スパン名 spring.integration.gateway (規約クラス o.s.i.support.management.observation.DefaultMessageRequestReplyReceiverObservationConvention で定義)。

外側のクラス o.s.i.support.management.observation.IntegrationObservation の完全修飾名。

すべてのタグには、spring.integration. プレフィックスを付ける必要があります。

表 4: タグキー
名前	説明
`spring.integration.name` (required)	Name of the message gateway component.
`spring.integration.outcome` (required)	Outcome of the request/reply execution.
`spring.integration.type` (required)	Type of the component - 'gateway'.

Handler Span

Observation for message handlers.

Span name spring.integration.handler (defined by convention class o.s.i.support.management.observation.DefaultMessageReceiverObservationConvention).

Fully qualified name of the enclosing class o.s.i.support.management.observation.IntegrationObservation.

All tags must be prefixed with spring.integration. prefix!

Table 5. Tag Keys
Name	Description
`spring.integration.name` (required)	Name of the message handler component.
`spring.integration.type` (required)	Type of the component - 'handler'.

Producer Span

Observation for message producers, e.g. channels.

Span name spring.integration.producer (defined by convention class o.s.i.support.management.observation.DefaultMessageSenderObservationConvention).

Fully qualified name of the enclosing class o.s.i.support.management.observation.IntegrationObservation.

All tags must be prefixed with spring.integration. prefix!

Table 6. Tag Keys
Name	Description
`spring.integration.name` (required)	Name of the message handler component.
`spring.integration.type` (required)	Type of the component - 'producer'.

Observability - Conventions

Below you can find a list of all GlobalObservationConvention and ObservationConvention declared by this project.

Table 7. ObservationConvention implementations
ObservationConvention Class Name	Applicable ObservationContext Class Name
`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`

観測伝播

メッセージングフローの性質とは無関係に、接続されたスパンのチェーンを 1 つのトレースで提供するには、MessageChannel が永続的で分散されている場合でも、このチャネルとこのチャネルのコンシューマー (サブスクライバー) で監視を有効にする必要があります。このように、トレース情報はコンシューマースレッドに伝播されるか、データベースに永続化される前に、メッセージヘッダーに保存されます。これは、前述の MessageSenderContext を介して行われます。コンシューマー (MessageHandler) 側は、MessageReceiverContext を使用してこれらのヘッダーからトレース情報を復元し、新しい子 Observation を開始します。

Spring Integration JMX サポート

JMX サポートも参照してください。