跳到主要内容
版本:2.0.7

可观测性

Doubao 中英对照 Observability

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

Micrometer 观测​

PulsarTemplate 和 PulsarListener 使用 Micrometer observations API 进行了埋点。当提供 Micrometer ObservationRegistry bean 时,发送和接收操作会被追踪并计时。

自定义标签​

默认实现为 template 观测添加 bean.name 标签,为 listener 观测添加 listener.id 标签。要向计时器和追踪添加其他标签,请分别为 template 或 listener 容器配置自定义的 PulsarTemplateObservationConvention 或 PulsarListenerObservationConvention。

提示

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

可观测性——指标​

下面列出本项目声明的所有指标。

Listener 观测​

Pulsar listener 收到消息时创建的观测。

指标名 spring.pulsar.listener(由约定类 org.springframework.pulsar.observation.DefaultPulsarListenerObservationConvention 定义)。类型 timer。

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

important

在 Observation 启动之后添加的 KeyValues 可能不会出现在 *.active 指标中。

important

Micrometer 内部以 nanoseconds 作为基本单位。不过,具体的后端会决定实际的基本单位。(例如 Prometheus 使用秒)

外层类的全限定名为 org.springframework.pulsar.observation.PulsarListenerObservation。

important

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

表 1. 低基数键

名称描述
spring.pulsar.listener.id (required)收到消息的 listener 容器的 Id。

Template 观测​

Pulsar template 发送消息时创建的观测。

指标名 spring.pulsar.template(由约定类 org.springframework.pulsar.observation.DefaultPulsarTemplateObservationConvention 定义)。类型 timer。

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

important

在 Observation 启动之后添加的 KeyValues 可能不会出现在 *.active 指标中。

important

Micrometer 内部以 nanoseconds 作为基本单位。不过,具体的后端会决定实际的基本单位。(例如 Prometheus 使用秒)

外层类的全限定名为 org.springframework.pulsar.observation.PulsarTemplateObservation。

important

所有标签都必须以 spring.pulsar.template 为前缀!

表 2. 低基数键

名称描述
spring.pulsar.template.name (required)发送消息的 template 的 bean 名称。

可观测性——Span​

下面列出本项目声明的所有 span。

Listener 观测 Span​

Pulsar listener 收到消息时创建的观测。

Span 名 spring.pulsar.listener(由约定类 org.springframework.pulsar.observation.DefaultPulsarListenerObservationConvention 定义)。

外层类的全限定名为 org.springframework.pulsar.observation.PulsarListenerObservation。

important

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

表 3. 标签键

名称描述
spring.pulsar.listener.id (required)收到消息的 listener 容器的 Id。

Template 观测 Span​

Pulsar template 发送消息时创建的观测。

Span 名 spring.pulsar.template(由约定类 org.springframework.pulsar.observation.DefaultPulsarTemplateObservationConvention 定义)。

外层类的全限定名为 org.springframework.pulsar.observation.PulsarTemplateObservation。

important

所有标签都必须以 spring.pulsar.template 为前缀!

表 4. 标签键

名称描述
spring.pulsar.template.name (required)发送消息的 template 的 bean 名称。

更多信息请参阅 Micrometer Tracing。

不使用 Spring Boot 的手动配置​

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

使用 Spring Boot 的自动配置​

如果你使用 Spring Boot,Spring Boot Actuator 会自动为你配置一个 ObservationRegistry 实例。如果 classpath 上有 micrometer-core,每一次停止的观测都会产生一个 timer。

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

示例配置​

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

  1. 将所需依赖添加到你的应用程序(分别针对 Maven 或 Gradle):
<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' 依赖。

  1. 将所需属性添加到你的应用程序:
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 示例应用 上看到前述配置。

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