可觀測性

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 示例應用程式上檢視上述配置。

這些步驟與配置任何其他受支援的跟蹤環境非常相似。