可观测性
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。
在 Observation 启动之后添加的 KeyValues 可能不会出现在 *.active 指标中。
Micrometer 内部以 nanoseconds 作为基本单位。不过,具体的后端会决定实际的基本单位。(例如 Prometheus 使用秒)
外层类的全限定名为 org.springframework.pulsar.observation.PulsarListenerObservation。
所有标签都必须以 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。
在 Observation 启动之后添加的 KeyValues 可能不会出现在 *.active 指标中。
Micrometer 内部以 nanoseconds 作为基本单位。不过,具体的后端会决定实际的基本单位。(例如 Prometheus 使用秒)
外层类的全限定名为 org.springframework.pulsar.observation.PulsarTemplateObservation。
所有标签都必须以 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。
所有标签都必须以 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。
所有标签都必须以 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 的步骤。
- 将所需依赖添加到你的应用程序(分别针对 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' 依赖。
- 将所需属性添加到你的应用程序:
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 示例应用 上看到前述配置。
这些步骤与配置任何其他受支持的追踪环境非常相似。