可观测性

Spring for Apache Pulsar 包含一种通过 Micrometer 管理可观测性的方式。

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。

在启动观测后添加的键值可能会从 *.active 指标中缺失。

Micrometer 内部使用 纳秒 作为基本单位。但是，每个后端确定实际的基本单位。（即 Prometheus 使用秒）

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

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

在启动观测后添加的键值可能会从 *.active 指标中缺失。

Micrometer 内部使用 纳秒 作为基本单位。但是，每个后端确定实际的基本单位。（即 Prometheus 使用秒）

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

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

表 2. 低基数键
名称	描述
`spring.pulsar.template.name` （必需）	发送消息的模板的 Bean 名称。

可观测性 - Span

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

监听器观察 Span

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

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

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

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

表 3. 标签键
名称	描述
`spring.pulsar.listener.id` （必需）	接收消息的监听器容器的 ID。

模板观察 Span

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

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

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

所有标签都必须以 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 观测 API 时，完成的观测会导致跨度报告给 Zipkin 或 Wavefront。您可以通过设置 management.tracing 下的属性来控制跟踪。您可以将 Zipkin 与 management.zipkin.tracing 一起使用，而 Wavefront 使用 management.wavefront。

示例配置

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

将所需的依赖项添加到您的应用程序（分别在 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>

Gradle

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' 依赖项。

将所需的属性添加到您的应用程序
```
management:
  tracing.enabled: true
  zipkin:
    tracing.endpoint: "https://:9411/api/v2/spans"
```
上述 tracing.endpoint 期望 Zipkin 像此处所述那样在本地运行。

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

您还可以在 Spring for Apache Pulsar 示例应用程序上查看上述配置。

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