可观测性

DeepSeek V3 中英对照 Observability

Spring for Apache Pulsar 提供了一种通过 Micrometer 来管理可观测性的方式。

备注

可观测性尚未添加到 Reactive 组件中

Micrometer 观测

PulsarTemplate 和 PulsarListener 使用了 Micrometer 的观测 API 进行检测。当提供了一个 Micrometer ObservationRegistry bean 时，发送和接收操作会被跟踪并计时。

自定义标签

默认实现为模板观测添加了 bean.name 标签，为监听器观测添加了 listener.id 标签。要为计时器和跟踪添加其他标签，请分别向模板或监听器容器配置自定义的 PulsarTemplateObservationConvention 或 PulsarListenerObservationConvention。

提示

你可以继承 DefaultPulsarTemplateObservationConvention 或 DefaultPulsarListenerObservationConvention，或者提供全新的实现。

可观测性 - 指标

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

监听器观察

当 Pulsar 监听器接收到消息时创建的观察。

指标名称 spring.pulsar.listener（由约定类 org.springframework.pulsar.observation.DefaultPulsarListenerObservationConvention 定义）。类型 timer。

指标名称 spring.pulsar.listener.active（由约定类 org.springframework.pulsar.observation.DefaultPulsarListenerObservationConvention 定义）。类型 long task timer。

important

在启动观察后添加的 KeyValues 可能会在 *.active 指标中缺失。

important

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

封闭类的完全限定名称 org.springframework.pulsar.observation.PulsarListenerObservation。

important

所有标签都必须以 spring.pulsar.listener 作为前缀！

表 1. 低基数键

名称	描述
spring.pulsar.listener.id (必填)	接收消息的监听器容器的 ID。

模板观察

当 Pulsar 模板发送消息时创建的观察。

指标名称 spring.pulsar.template（由约定类 org.springframework.pulsar.observation.DefaultPulsarTemplateObservationConvention 定义）。类型 timer。

指标名称 spring.pulsar.template.active（由约定类 org.springframework.pulsar.observation.DefaultPulsarTemplateObservationConvention 定义）。类型 long task timer。

important

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

important

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

封闭类的完全限定名称 org.springframework.pulsar.observation.PulsarTemplateObservation。

important

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

表 2. 低基数键

名称	描述
spring.pulsar.template.name (必填)	发送消息的模板的 Bean 名称。

可观测性 - Spans

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

监听器观察跨度

当 Pulsar 监听器接收到消息时创建的观察。

Span 名称 spring.pulsar.listener（由约定类 org.springframework.pulsar.observation.DefaultPulsarListenerObservationConvention 定义）。

封闭类的完全限定名称 org.springframework.pulsar.observation.PulsarListenerObservation。

important

所有标签都必须以 spring.pulsar.listener 前缀开头！

表 3. 标签键

名称	描述
spring.pulsar.listener.id (必填)	接收消息的监听器容器的 ID。

模板观察跨度

当 Pulsar 模板发送消息时创建的观察结果。

Span 名称 spring.pulsar.template（由约定类 org.springframework.pulsar.observation.DefaultPulsarTemplateObservationConvention 定义）。

封闭类的完全限定名称 org.springframework.pulsar.observation.PulsarTemplateObservation。

important

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

表 4. 标签键

名称	描述
spring.pulsar.template.name (必填)	发送消息的模板的 Bean 名称。

更多信息请参见 Micrometer Tracing。

不使用 Spring Boot 的手动配置

如果你不使用 Spring Boot，你需要配置并提供一个 ObservationRegistry 以及 Micrometer Tracing。更多信息请参阅 Micrometer Tracing。

使用 Spring Boot 进行自动配置

如果你使用 Spring Boot，Spring Boot Actuator 会自动为你配置一个 ObservationRegistry 实例。如果 micrometer-core 在类路径上，每个停止的观测都会生成一个计时器。

Spring Boot 也会自动为你配置 Micrometer Tracing。这包括对 Brave OpenTelemetry、Zipkin 和 Wavefront 的支持。当使用 Micrometer Observation API 时，完成观测会导致 span 被报告到 Zipkin 或 Wavefront。你可以通过在 management.tracing 下设置属性来控制追踪。你可以使用 management.zipkin.tracing 来配置 Zipkin，而 Wavefront 则使用 management.wavefront。

示例配置

以下示例展示了将 Spring Boot 应用程序配置为使用 Zipkin 和 Brave 的步骤。

1. 将所需的依赖项添加到你的应用程序中（分别在 Maven 或 Gradle 中）：

   Maven

   <dependencies>
       <dependency>
           <groupId>org.springframework.boot</groupId>
           <artifactId>spring-boot-starter-actuator</artifactId>
       </dependency>
       <dependency>
           <groupId>io.micrometer</groupId>
           <artifactId>micrometer-tracing-bridge-brave</artifactId>
       </dependency>
       <dependency>
           <groupId>io.zipkin.reporter2</groupId>
           <artifactId>zipkin-reporter-brave</artifactId>
       </dependency>
       <dependency>
           <groupId>io.zipkin.reporter2</groupId>
           <artifactId>zipkin-sender-urlconnection</artifactId>
       </dependency>
   </dependencies>

   dependencies {
       implementation 'org.springframework.boot:spring-boot-starter-actuator'
       implementation 'io.micrometer:micrometer-tracing-bridge-brave'
       implementation 'io.zipkin.reporter2:zipkin-reporter-brave'
       implementation 'io.zipkin.reporter2:zipkin-sender-urlconnection'
   }

   注意：只有在你的应用程序没有配置 WebClient 或 RestTemplate 时，才需要 'io.zipkin.reporter2:zipkin-sender-urlconnection' 依赖项。

2. 将所需的属性添加到你的应用程序中：

   management:
     tracing.enabled: true
     zipkin:
       tracing.endpoint: "http://localhost:9411/api/v2/spans"

   上面的 tracing.endpoint 期望 Zipkin 在本地运行，如此处所述。

此时，当您发送和接收 Pulsar 消息时，您的应用程序应该记录跟踪信息。您应该能够在 Zipkin UI 中查看这些跟踪信息（在本地运行时，访问 localhost:9411）。

提示

你也可以在 Spring for Apache Pulsar 示例应用 上查看前面的配置。

步骤与配置任何其他受支持的 Tracing 环境非常相似。