Metrics and Management

本部分介绍如何获取 Spring Integration 的指标。在最近的版本中，我们更多地依赖于 Micrometer（请参见 [role="bare"][role="bare"]https://micrometer.io），并且我们计划在将来的版本中更多地使用 Micrometer。

This section describes how to capture metrics for Spring Integration. In recent versions, we have relied more on Micrometer (see [role="bare"]https://micrometer.io), and we plan to use Micrometer even more in future releases.

Disabling Logging in High Volume Environments

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

You can control debug logging in the main message flow. In very high volume applications, calls to isDebugEnabled() can be quite expensive with some logging subsystems. You can disable all such logging to avoid this overhead. Exception logging (debug or otherwise) is not affected by this setting.

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

The following listing shows the available options for controlling logging:

  • Java

  • XML

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

public static class ContextConfiguration {
...
}
<int:management default-logging-enabled="true"/> 1
1 Set to false to disable all logging in the main message flow, regardless of the log system category settings. Set to 'true' to enable debug logging (if also enabled by the logging subsystem). Only applied if you have not explicitly configured the setting in a bean definition. The default is true.

defaultLoggingEnabled 仅在 bean 定义中未明确配置相应设置时才应用。

defaultLoggingEnabled is applied only if you have not explicitly configured the corresponding setting in a bean definition.

Micrometer Integration

Overview

从 5.0.3 版本开始，应用程序上下文中 @{33} @{32} 的存在触发了对 Micrometer 指标的支持。

Starting with version 5.0.3, the presence of a Micrometer MeterRegistry in the application context triggers support for Micrometer metrics.

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

To use Micrometer, add one of the MeterRegistry beans to the application context.

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

For each MessageHandler and MessageChannel, timers are registered. For each MessageSource, a counter is registered.

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

This only applies to objects that extend AbstractMessageHandler, AbstractMessageChannel, and AbstractMessageSource (which is the case for most framework components).

消息通道上的发送操作的 Timer 米制具有以下名称或标记：

The Timer Meters for send operations on message channels have the following names or tags:

  • 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。）

(A failure result with a none exception means the channel’s send() operation returned false.)

轮询消息通道上的接收操作的 Counter 米制具有以下名称或标记：

The Counter Meters for receive operations on pollable message channels have the following names or tags:

  • 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 米制具有以下名称或标记：

The Timer Meters for operations on message handlers have the following names or tags:

  • 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 米制具有以下名称/标记：

The Counter meters for message sources have the following names/tags:

  • name: spring.integration.receive

  • tag: type:source

  • tag: name:<componentName>

  • tag: result:success

  • tag: exception:none

  • description: Messages received

此外，还有三个 Gauge 米制：

In addition, there are three Gauge Meters:

  • spring.integration.channels: The number of MessageChannels in the application.

  • spring.integration.handlers: The number of MessageHandlers in the application.

  • spring.integration.sources: The number of MessageSources in the application.

可以通过提供 @{35} 子类自定义由集成组件创建的 @{34} 的名称和标记。@{37} 测试用例显示了如何执行此操作的简单示例。您还可以通过在构建器子类上重载 @{36} 方法进一步自定义仪表。

It is possible to customize the names and tags of Meters created by integration components by providing a subclass of MicrometerMetricsCaptor. The MicrometerCustomMetricsTests test case shows a simple example of how to do that. You can also further customize the meters by overloading the build() methods on builder subclasses.

从版本 5.1.13 开始，QueueChannel 公开用于队列大小和剩余容量的 Micrometer 米制：

Starting with version 5.1.13, the QueueChannel exposes Micrometer gauges for queue size and remaining capacity:

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

  • tag: type:channel

  • tag: name:<componentName>

  • description: The size of the queue channel

和

and

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

  • tag: type:channel

  • tag: name:<componentName>

  • description: The remaining capacity of the queue channel

Disabling Meters

默认情况下，在首次使用时会注册所有仪表。现在，有了 Micrometer，您可以将 @{38} 添加到 @{39} 以防止部分或全部仪表被注册。您可以使用任何提供的属性过滤出仪表（拒绝仪表），如 @{40}、@{41} 等。请参阅 Micrometer 文档中的 @{42} 以获取详细信息。

By default, all meters are registered when first used. Now, with Micrometer, you can add MeterFilter s to the MeterRegistry to prevent some or all from being registered. You can filter out (deny) meters by any of the properties provided, name, tag, etc. See Meter Filters in the Micrometer documentation for more information.

例如，对于给定：

For example, given:

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

使用以下操作可仅针对此通道抑制仪表的注册：

You can suppress registration of meters for just this channel with:

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

Micrometer Observation

从 6.0 版本开始，Spring 集成利用 Micrometer 观察抽象，该抽象可以通过适当的 @{43} 配置处理指标和 @{44}。

Starting with version 6.0, Spring Integration utilizes a Micrometer Observation abstraction which can handle metrics as well as tracing via appropriate ObservationHandler configuration.

只要应用程序上下文中存在 ObservationRegistry Bean 并配置了 @EnableIntegrationManagement，便会在 IntegrationManagement 组件上启用观察处理。若要自定义应该检测的一组组件，可以在 @EnableIntegrationManagement 注释上公开 observationPatterns() 属性。请查看其 Javadoc 以了解模式匹配算法。

The observation handling is enabled on the IntegrationManagement components whenever an ObservationRegistry bean is present in the application context and an @EnableIntegrationManagement is configured. To customize what set of components should be instrumented, an observationPatterns() attribute is exposed on the @EnableIntegrationManagement annotation. See its javadocs for a pattern matching algorithm.

默认情况下，IntegrationManagement 组件中没有一个使用 ObservationRegistry bean 进行检测。可将其配置为 * 以匹配所有组件。

By default, none of the IntegrationManagement components are instrumented with an ObservationRegistry bean. Can be configured as * to match all components.

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

The meters are not gathered in this case independently, but delegated to an appropriate ObservationHandler configured on the provided ObservationRegistry.

以下 Spring Integration 组件配备观察逻辑，每个逻辑都遵循一个相应的约定：

The following Spring Integration components are instrumented with observation logic each with a respective convention:

  • MessageProducerSupport, being the inbound endpoint of the flow, is considered as a CONSUMER span type and uses the IntegrationObservation.HANDLER API;

  • MessagingGatewaySupport` is an inbound request-reply endpoint, and is considered as a SERVER span type. It uses the IntegrationObservation.GATEWAY API;

  • An AbstractMessageChannel.send() operation is the only Spring Integration API where it produces messages. So, it is treated as a PRODUCER span type and uses the IntegrationObservation.PRODCUER API. This makes more sense when a channel is a distributed implementation (e.g. PublishSubscribeKafkaChannel or ZeroMqChannel) and trace information has to be added to the message. So, the IntegrationObservation.PRODUCER observation is based on a MessageSenderContext where Spring Integration supplies a MutableMessage to allow a subsequent tracing Propagator to add headers, so they are available to the consumer;

  • An AbstractMessageHandler is a CONSUMER span type and uses the IntegrationObservation.HANDLER API.

可以通过 ObservationConvention 配置自定义 IntegrationManagement 组件上的观察生成。例如，AbstractMessageHandler 通过其 setObservationConvention() API 期待 MessageReceiverObservationConvention。

An observation production on the IntegrationManagement components can be customized via ObservationConvention configuration. For example an AbstractMessageHandler expects a MessageReceiverObservationConvention via its setObservationConvention() API.

以下是针对观察 API 支持的指标、跨度和约定：

The following are supported metrics, spans and conventions for Observation API:

Unresolved include directive in modules/ROOT/pages/metrics.adoc - include::partial$metrics.adoc[]

Unresolved include directive in modules/ROOT/pages/metrics.adoc - include::partial$spans.adoc[]

Unresolved include directive in modules/ROOT/pages/metrics.adoc - include::partial$conventions.adoc[]

Observation Propagation

若要提供跟踪中连接的跨度链，该链独立于消息流的性质（即使 MessageChannel 是持久且分布式的），也必须启用此通道上的观察以及此通道的使用者（订阅者）上的观察。这样，跟踪信息便会存储在消息头中，然后才传播到使用者线程或持久到数据库中。这通过前面提到的 MessageSenderContext 完成。使用 MessageReceiverContext，使用者（MessageHandler）端会从那些头中还原跟踪信息，然后启动新子 Observation。

To supply a connected chain of spans in one trace, independently of the nature of the messaging flow, even if a MessageChannel is persistent and distributed, the observation must be enabled on this channel and on consumers (subscribers) for this channel. This way, the tracing information is stored in the message headers before it is propagated to a consumer thread or persisted into the database. This is done via mentioned above MessageSenderContext. The consumer (a MessageHandler) side restores tracing information from those headers using a MessageReceiverContext and starts a new child Observation.

Spring Integration JMX Support

另请参见 JMX Support。

Also see JMX Support.