指标和管理

QWen Plus 中英对照 Metrics and Management

本节描述了如何为 Spring Integration 捕获指标。在最近的版本中，我们更加依赖 Micrometer（参见 micrometer.io），并且我们计划在未来的版本中更多地使用 Micrometer。

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

你可以在主消息流中控制调试日志。在非常高流量的应用程序中，调用 isDebugEnabled() 在某些日志记录子系统中可能会相当昂贵。你可以禁用所有此类日志记录以避免这种开销。异常日志记录（调试或其他）不受此设置的影响。

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

Java

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

public static class ContextConfiguration {
...
}

java

XML

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

xml

• 设置为 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 : <componentName>

• 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:<componentName>

• tag: result:(success|failure)

• tag: exception:(none|exception 简单类名)

• description: 发送处理时间

Counter 计数器用于消息源，具有以下名称/标签：

• name: spring.integration.receive

• tag: type:source

• tag: name:<componentName>

• tag: result:success

• tag: exception:none

• description: 接收到的消息

此外，还有三个 Gauge 表盘：

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

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

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

可以通过提供 MicrometerMetricsCaptor 的子类来定制集成组件创建的 Meters 的名称和标签。MicrometerCustomMetricsTests 测试案例展示了如何做到这一点的一个简单示例。您还可以通过重载构建器子类上的 build() 方法进一步自定义仪表。

从 5.1.13 版本开始，QueueChannel 暴露了 Micrometer 衡量指标来监控队列大小和剩余容量：

• 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: 队列通道的剩余容量

禁用计量器

默认情况下，所有仪表在首次使用时都会被注册。现在，使用 Micrometer，您可以在 MeterRegistry 中添加 MeterFilter 以防止部分或全部仪表被注册。您可以根据提供的任何属性过滤（拒绝）仪表，例如 name、tag 等。有关更多信息，请参阅 Micrometer 文档中的仪表过滤器。

例如，给定：

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

java

你可以通过以下方式抑制只为该通道注册计量器：

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

java

螺旋测微器观察

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

当应用程序上下文中存在 ObservationRegistry bean 并配置了 @EnableIntegrationManagement 时，会在 IntegrationManagement 组件上启用观察处理。为了自定义应instrument哪些组件集，在 @EnableIntegrationManagement 注解中暴露了一个 observationPatterns() 属性。有关模式匹配算法，请参阅其 javadocs。

important

默认情况下，没有任何 IntegrationManagement 组件使用 ObservationRegistry bean 进行监控。可以配置为 * 以匹配所有组件。

在这种情况下，仪表并不是独立收集的，而是委托给配置在提供的 ObservationRegistry 上的适当 ObservationHandler。

以下 Spring Integration 组件各自使用观察逻辑进行了 instrumentation，并遵循相应的约定：

• 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；

• SourcePollingChannelAdapter（从 6.5 版开始），作为流的入站端点，被视为 CONSUMER 跨类型并使用 IntegrationObservation.HANDLER API。

可以在 ObservationConvention 配置中自定义对 IntegrationManagement 组件的观测生产。例如，AbstractMessageHandler 通过其 setObservationConvention() API 期望一个 MessageReceiverObservationConvention。

以下是指标、跨度和 Observation API 的约定：

可观察性 - 指标

下面你可以找到该项目声明的所有指标的列表。

网关

入站消息网关的观察。

Metric name spring.integration.gateway（由约定类 o.s.i.support.management.observation.DefaultMessageRequestReplyReceiverObservationConvention 定义）。Type timer。

Metric name spring.integration.gateway.active （由约定类 o.s.i.support.management.observation.DefaultMessageRequestReplyReceiverObservationConvention 定义）。Type long task timer。

important

在开始观察后添加的 KeyValues 可能会缺失于 *.active metrics。

important

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

外部类的全限定名称 o.s.i.support.management.observation.IntegrationObservation。

important

所有标签必须以 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 任务计时器。

important

在开始观察之后添加的 KeyValues 可能会 missing from the *.active metrics。

important

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

外部类的全限定名称 o.s.i.support.management.observation.IntegrationObservation。

important

所有标签必须以 spring.integration. 前缀开头！

表 2. 低基数键

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

生产者

对消息生产者的观察，例如 通道。

Metric name spring.integration.producer （由约定类 o.s.i.support.management.observation.DefaultMessageSenderObservationConvention 定义）。Type timer。

Metric name spring.integration.producer.active （由约定类 o.s.i.support.management.observation.DefaultMessageSenderObservationConvention 定义）。Type long task timer。

important

在开始观察之后添加的 KeyValues 可能会缺失于 *.active 指标中。

important

Micrometer 内部使用 nanoseconds 作为基本单位。然而，每个后端决定了实际的基本单位。（例如，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 (必填)	组件类型 - '网关'。

处理程序跨度

消息处理程序的观察。

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 (必填)	组件类型 - '生产者'。

可观察性 - 约定

下面你可以找到该项目声明的所有 GlobalObservationConvention 和 ObservationConvention 列表。

表 7. ObservationConvention 实现

观察约定类名称	适用的观察上下文类名称
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 支持。