指标与管理

DeepSeek V3 中英对照 Metrics and Management

本节介绍如何捕获 Spring Integration 的指标。在最近的版本中，我们更多地依赖 Micrometer，并且计划在未来的版本中更多地使用 Micrometer。

在高流量环境中禁用日志记录

您可以控制主消息流中的调试日志记录。在高吞吐量的应用程序中，调用 isDebugEnabled() 在某些日志子系统中可能相当耗费资源。您可以禁用所有此类日志记录以避免这种开销。异常日志记录（无论是调试级别还是其他级别）不受此设置影响。

以下列表展示了控制日志记录功能的可用选项：

Java

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

public static class ContextConfiguration {
...
}

XML

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

• 设置为 false 以在主消息流中禁用所有日志记录，无论日志系统类别设置如何。设置为 true 以启用调试日志记录（如果日志子系统也启用了该功能）。仅当您未在 bean 定义中显式配置此设置时才会应用。默认值为 true。

important

defaultLoggingEnabled 仅在你未在 bean 定义中显式配置相应设置时生效。

Micrometer 集成

概述

从 5.0.3 版本开始，当应用上下文中存在 Micrometer MeterRegistry 时，将自动启用对 Micrometer 指标的支持。

要使用 Micrometer，请将 MeterRegistry bean 之一添加到应用程序上下文中。

对于每个 MessageHandler 和 MessageChannel，都会注册计时器。对于每个 MessageSource，都会注册计数器。

这仅适用于扩展了 AbstractMessageHandler、AbstractMessageChannel 和 AbstractMessageSource 的对象（大多数框架组件都属于这种情况）。

Timer 仪表用于消息通道发送操作，具有以下名称或标签：

• name: spring.integration.send

• tag: type:channel

• tag: name:<组件名称>

• tag: result:(success|failure)

• tag: exception:(none|exception simple class name)

• description: 发送处理时间

（一个带有 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: 接收到的消息

Timer 仪表用于消息处理器操作，具有以下名称或标签：

• name: spring.integration.send

• tag: type:handler

• tag: name:<组件名称>

• tag: result:(success|failure)

• tag: exception:(none|exception simple class name)

• description: 发送处理时间

Counter 类型指标用于消息源，具有以下名称/标签：

• name: spring.integration.receive

• tag: type:source

• tag: name:<组件名称>

• tag: result:success

• tag: exception:none

• description: 接收到的消息

此外，还有三个 Gauge 仪表：

• spring.integration.channels: 应用程序中 MessageChannels 的数量。

• spring.integration.handlers: 应用程序中 MessageHandlers 的数量。

• spring.integration.sources: 应用程序中 MessageSources 的数量。

可以通过提供 MicrometerMetricsCaptor 的子类来自定义集成组件创建的 Meter 的名称和标签。MicrometerCustomMetricsTests 测试用例展示了一个简单的示例，说明如何实现这一点。此外，你还可以通过重载构建器子类上的 build() 方法来进一步自定义这些仪表。

从 5.1.13 版本开始，QueueChannel 会暴露用于队列大小和剩余容量的 Micrometer 仪表：

• name: spring.integration.channel.queue.size

• tag: type:channel

• tag: name:<组件名称>

• description: 队列通道的大小

和

• name: spring.integration.channel.queue.remaining.capacity

• tag: type:channel

• tag: name:<componentName>

• description: 队列通道的剩余容量

禁用计量器

默认情况下，所有计量器在首次使用时会被注册。现在，通过 Micrometer，你可以向 MeterRegistry 添加 MeterFilter 来阻止部分或全部计量器的注册。你可以根据提供的任何属性（如 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 观测

从 6.0 版本开始，Spring Integration 采用了 Micrometer Observation 抽象，该抽象可以通过适当的 ObservationHandler 配置来处理指标以及追踪。

当应用程序上下文中存在 ObservationRegistry bean 且配置了 @EnableIntegrationManagement 时，IntegrationManagement 组件上的观察处理功能将被启用。为了自定义哪些组件集应被纳入监控，@EnableIntegrationManagement 注解上公开了一个 observationPatterns() 属性。有关模式匹配算法的详细信息，请参阅其 Javadocs。

important

默认情况下，所有 IntegrationManagement 组件均未配置 ObservationRegistry bean。可配置为 * 以匹配所有组件。

在这种情况下，仪表数据并非独立收集，而是委托给配置在所提供的 ObservationRegistry 上的相应 ObservationHandler 进行处理。

以下 Spring Integration 组件已通过观测逻辑进行检测，每个组件均遵循相应的观测规范：

• MessageProducerSupport 作为流程的入站端点，被视为 CONSUMER 跨度类型，并使用 IntegrationObservation.HANDLER API；

• MessagingGatewaySupport 是一个入站请求-回复端点，被视为 SERVER 跨度类型，并使用 IntegrationObservation.GATEWAY API；

• AbstractMessageChannel.send() 操作是唯一一个产生消息的 Spring Integration API。因此，它被视为 PRODUCER 跨度类型，并使用 IntegrationObservation.PRODUCER API。当通道是分布式实现（例如 PublishSubscribeKafkaChannel 或 ZeroMqChannel）且必须向消息添加跟踪信息时，这一点更有意义。因此，IntegrationObservation.PRODUCER 观察基于 MessageSenderContext，其中 Spring Integration 提供一个 MutableMessage，以便后续的跟踪 Propagator 可以添加头部信息，从而使消费者能够使用这些信息；

• AbstractMessageHandler 是一个 CONSUMER 跨度类型，并使用 IntegrationObservation.HANDLER API；

• SourcePollingChannelAdapter（从版本 6.5 开始）作为流程的入站端点，被视为 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。

important

在启动观测后添加的 KeyValues 可能不会出现在 *.active 指标文件中。

important

Micrometer 内部使用 纳秒 作为基本单位。然而，每个后端会决定实际使用的基本单位。（例如，Prometheus 使用秒）

完全限定名称的封闭类 o.s.i.support.management.observation.IntegrationObservation。

important

所有标签都必须以 spring.integration. 为前缀！

表 1. 低基数键

名称	描述
spring.integration.name (必填)	消息网关组件的名称。
spring.integration.outcome (必填)	请求/回复执行的结果。
spring.integration.type (必填)	组件的类型 - 'gateway'。

Handler

消息处理器的观察。

指标名称 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。

important

在启动观测后添加的 KeyValues 可能不会出现在 *.active 指标文件中。

important

Micrometer 内部使用 纳秒 作为基本单位。然而，每个后端决定实际的基本单位。（例如，Prometheus 使用秒）

完全限定名称的封闭类 o.s.i.support.management.observation.IntegrationObservation。

important

所有标签都必须以 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。

important

在启动观测后添加的 KeyValues 可能不会出现在 *.active 指标文件中。

important

Micrometer 内部使用 纳秒 作为基本单位。然而，每个后端决定实际的基本单位。（例如，Prometheus 使用秒）

完全限定类名 o.s.i.support.management.observation.IntegrationObservation。

important

所有标签都必须以 spring.integration. 为前缀！

表 3. 低基数键

名称	描述
spring.integration.name (必填)	消息处理器组件的名称。
spring.integration.type (必填)	组件的类型 - 'producer'。

可观测性 - 跨度

以下是本项目声明的所有 Span 列表。

网关跨度

入站消息网关的观察。

Span 名称 spring.integration.gateway (由约定类 o.s.i.support.management.observation.DefaultMessageRequestReplyReceiverObservationConvention 定义)。

完全限定名称的封闭类 o.s.i.support.management.observation.IntegrationObservation。

important

所有标签都必须以 spring.integration. 为前缀！

表 4. 标签键

名称	描述
spring.integration.name (必填)	消息网关组件的名称。
spring.integration.outcome (必填)	请求/回复执行的结果。
spring.integration.type (必填)	组件的类型 - 'gateway'。

Handler Span

消息处理器的观察。

Span 名称 spring.integration.handler (由约定类 o.s.i.support.management.observation.DefaultMessageReceiverObservationConvention 定义)。

完全限定名称的封闭类 o.s.i.support.management.observation.IntegrationObservation。

important

所有标签都必须以 spring.integration. 为前缀！

表 5. 标签键

名称	描述
spring.integration.name (必需)	消息处理器组件的名称。
spring.integration.type (必需)	组件的类型 - 'handler'。

生产者跨度

对消息生产者（例如频道）的观察。

Span 名称 spring.integration.producer (由约定类 o.s.i.support.management.observation.DefaultMessageSenderObservationConvention 定义)。

完全限定名称的封闭类 o.s.i.support.management.observation.IntegrationObservation。

important

所有标签都必须以 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 支持。