跟蹤

Spring Boot Actuator 為 Micrometer Tracing（一個流行追蹤器庫的門面）提供依賴管理和自動配置。

要了解 Micrometer Tracing 的更多功能，請參閱其參考文件。

支援的追蹤器

Spring Boot 為以下追蹤器提供自動配置：

OpenTelemetry 與 Zipkin 或 OTLP。
OpenZipkin Brave 與 Zipkin。

入門

我們需要一個示例應用程式來開始追蹤。為此，開發您的第一個 Spring Boot 應用程式部分中介紹的簡單“Hello World!”Web 應用程式就足夠了。我們將使用 OpenTelemetry 追蹤器，並將 Zipkin 作為追蹤後端。

回顧一下，我們的主要應用程式程式碼如下所示：

Java
Kotlin

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@SpringBootApplication
public class MyApplication {

	private static final Log logger = LogFactory.getLog(MyApplication.class);

	@RequestMapping("/")
	String home() {
		logger.info("home() has been called");
		return "Hello World!";
	}

	public static void main(String[] args) {
		SpringApplication.run(MyApplication.class, args);
	}

}

import org.apache.commons.logging.Log
import org.apache.commons.logging.LogFactory
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@SpringBootApplication
class MyApplication {

	private val logger: Log = LogFactory.getLog(MyApplication::class.java)

	@RequestMapping("/")
	fun home(): String {
		logger.info("home() has been called")
		return "Hello, World!"
	}

}

fun main(args: Array<String>) {
	runApplication<MyApplication>(*args)
}

home() 方法中添加了一個日誌記錄器語句，這在後面會很重要。

現在我們必須新增以下依賴項：

org.springframework.boot:spring-boot-starter-actuator
io.micrometer:micrometer-tracing-bridge-otel - 將 Micrometer Observation API 橋接到 OpenTelemetry。
io.opentelemetry:opentelemetry-exporter-zipkin - 向 Zipkin 報告追蹤。

新增以下應用程式屬性：

屬性
YAML

management.tracing.sampling.probability=1

management:
  tracing:
    sampling:
      probability: 1.0

預設情況下，Spring Boot 只對 10% 的請求進行抽樣，以防止追蹤後端不堪重負。此屬性將其切換為 100%，以便每個請求都發送到追蹤後端。

為了收集和視覺化追蹤，我們需要一個正在執行的追蹤後端。這裡我們使用 Zipkin 作為我們的追蹤後端。Zipkin 快速入門指南提供了在本地啟動 Zipkin 的說明。

Zipkin 執行後，您可以啟動您的應用程式。

如果您在 Web 瀏覽器中開啟 localhost:8080，您應該會看到以下輸出

Hello World!

在幕後，已經為 HTTP 請求建立了一個觀察，該觀察又橋接到 OpenTelemetry，OpenTelemetry 將新的追蹤報告給 Zipkin。

現在開啟 Zipkin UI (localhost:9411) 並點選“執行查詢”按鈕列出所有收集到的追蹤。您應該會看到一個追蹤。點選“顯示”按鈕檢視該追蹤的詳細資訊。

日誌關聯 ID

關聯 ID 提供了一種有用的方式，可以將日誌檔案中的行連結到 span/追蹤。如果您正在使用 Micrometer Tracing，Spring Boot 預設會在您的日誌中包含關聯 ID。

預設的關聯 ID 由 traceId 和 spanId MDC 值構建。例如，如果 Micrometer Tracing 添加了 MDC traceId 為 803B448A0489F84084905D3093480352 和 MDC spanId 為 3425F23BB2432450，則日誌輸出將包含關聯 ID [803B448A0489F84084905D3093480352-3425F23BB2432450]。

如果您希望為關聯 ID 使用不同的格式，可以使用 logging.pattern.correlation 屬性來定義。例如，以下將為 Logback 提供先前由 Spring Cloud Sleuth 使用的格式的關聯 ID：

屬性
YAML

logging.pattern.correlation=[${spring.application.name:},%X{traceId:-},%X{spanId:-}] 
logging.include-application-name=false

logging:
  pattern:
    correlation: "[${spring.application.name:},%X{traceId:-},%X{spanId:-}] "
  include-application-name: false

在上面的示例中，logging.include-application-name 設定為 false 以避免應用程式名稱在日誌訊息中重複（logging.pattern.correlation 已包含它）。還需要提及的是，logging.pattern.correlation 包含一個尾隨空格，以便它與預設緊隨其後的日誌記錄器名稱分開。

關聯 ID 依賴於上下文傳播。請閱讀此文件瞭解更多詳細資訊。

傳播追蹤

要自動透過網路傳播追蹤，請使用自動配置的 RestTemplateBuilder、RestClient.Builder 或 WebClient.Builder 來構建客戶端。

如果您在不使用自動配置的構建器的情況下建立 RestTemplate、RestClient 或 WebClient，自動追蹤傳播將不起作用！

追蹤器實現

由於 Micrometer Tracer 支援多種追蹤器實現，Spring Boot 有多種可能的依賴組合。

所有追蹤器實現都需要 org.springframework.boot:spring-boot-starter-actuator 依賴項。

OpenTelemetry 與 Zipkin

使用 OpenTelemetry 追蹤並報告到 Zipkin 需要以下依賴項：

io.micrometer:micrometer-tracing-bridge-otel - 將 Micrometer Observation API 橋接到 OpenTelemetry。
io.opentelemetry:opentelemetry-exporter-zipkin - 向 Zipkin 報告追蹤。

使用 management.tracing.export.zipkin.* 配置屬性來配置向 Zipkin 報告。

OpenTelemetry 與 OTLP

使用 OpenTelemetry 追蹤並使用 OTLP 報告需要以下依賴項：

io.micrometer:micrometer-tracing-bridge-otel - 將 Micrometer Observation API 橋接到 OpenTelemetry。
io.opentelemetry:opentelemetry-exporter-otlp - 向可以接受 OTLP 的收集器報告追蹤。

使用 management.opentelemetry.tracing.export.otlp.* 配置屬性來配置使用 OTLP 報告。

如果需要對 OTLP span 匯出器進行高階自定義，請考慮註冊 OtlpHttpSpanExporterBuilderCustomizer 或 OtlpGrpcSpanExporterBuilderCustomizer bean。這些將在建立 OtlpHttpSpanExporter 或 OtlpGrpcSpanExporter 之前呼叫。自定義器優先於自動配置應用的任何內容。

OpenZipkin Brave 與 Zipkin

使用 OpenZipkin Brave 追蹤並報告到 Zipkin 需要以下依賴項：

io.micrometer:micrometer-tracing-bridge-brave - 將 Micrometer Observation API 橋接到 Brave。
io.zipkin.reporter2:zipkin-reporter-brave - 向 Zipkin 報告追蹤。

使用 management.tracing.export.zipkin.* 配置屬性來配置向 Zipkin 報告。

與 Micrometer Observation 整合

TracingAwareMeterObservationHandler 會自動註冊到 ObservationRegistry 上，它為每個完成的觀察建立 span。

建立自定義 Span

您可以透過啟動觀察來建立自己的 span。為此，將 ObservationRegistry 注入到您的元件中：

Java
Kotlin

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;

import org.springframework.stereotype.Component;

@Component
class CustomObservation {

	private final ObservationRegistry observationRegistry;

	CustomObservation(ObservationRegistry observationRegistry) {
		this.observationRegistry = observationRegistry;
	}

	void someOperation() {
		Observation observation = Observation.createNotStarted("some-operation", this.observationRegistry);
		observation.lowCardinalityKeyValue("some-tag", "some-value");
		observation.observe(() -> {
			// Business logic ...
		});
	}

}

import io.micrometer.observation.Observation
import io.micrometer.observation.ObservationRegistry
import org.springframework.stereotype.Component

@Component
class CustomObservation(private val observationRegistry: ObservationRegistry) {

	fun someOperation() {
		Observation.createNotStarted("some-operation", observationRegistry)
			.lowCardinalityKeyValue("some-tag", "some-value")
			.observe {
				// Business logic ...
			}
	}

}

這將建立一個名為“some-operation”的觀察，並帶有標籤“some-tag=some-value”。

如果您想建立 span 而不建立指標，則需要使用 Micrometer 的低階 Tracer API。

Baggage

您可以使用 Tracer API 建立 baggage

Java
Kotlin

import io.micrometer.tracing.BaggageInScope;
import io.micrometer.tracing.Tracer;

import org.springframework.stereotype.Component;

@Component
class CreatingBaggage {

	private final Tracer tracer;

	CreatingBaggage(Tracer tracer) {
		this.tracer = tracer;
	}

	void doSomething() {
		try (BaggageInScope scope = this.tracer.createBaggageInScope("baggage1", "value1")) {
			// Business logic
		}
	}

}

import io.micrometer.tracing.Tracer
import org.springframework.stereotype.Component

@Component
class CreatingBaggage(private val tracer: Tracer) {

	fun doSomething() {
		tracer.createBaggageInScope("baggage1", "value1").use {
			// Business logic
		}
	}

}

此示例建立名為 baggage1 且值為 value1 的 baggage。如果您使用 W3C 傳播，該 baggage 會自動透過網路傳播。如果您使用 B3 傳播，則 baggage 不會自動傳播。要手動透過網路傳播 baggage，請使用 management.tracing.baggage.remote-fields 配置屬性（這也適用於 W3C）。對於上面的示例，將此屬性設定為 baggage1 會生成 HTTP 頭 baggage1: value1。

如果您想將 baggage 傳播到 MDC，請使用 management.tracing.baggage.correlation.fields 配置屬性。對於上面的示例，將此屬性設定為 baggage1 會生成一個名為 baggage1 的 MDC 條目。

測試

使用 @SpringBootTest 時，不會自動配置報告資料的追蹤元件。有關詳細資訊，請參閱使用追蹤。