可观测性

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 Observation API 时，完成的可观测对象将生成并报告 span 到 Zipkin 或 Wavefront。您可以通过设置 `management.tracing` 下的属性来控制跟踪。您可以使用 `management.zipkin.tracing` 配置 Zipkin，使用 `management.wavefront` 配置 Wavefront。

配置示例

以下示例展示了如何配置 Spring Boot 应用程序以使用 Brave 集成 Zipkin。

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

  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 示例应用 中查看上述配置。

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