指标和管理

本节介绍如何捕获 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 支持。