追蹤

Spring Boot Actuator 為 Micrometer Tracing 提供了依賴管理和自動配置，它是流行追蹤器庫的門面。

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

支援的追蹤器

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

入門

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

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

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);
	}

}
在 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 請求建立了一個觀測 (observation)，該觀測隨後被橋接到 OpenTelemetry，OpenTelemetry 則向 Zipkin 報告一個新的追蹤 (trace)。

現在開啟位於 localhost:9411 的 Zipkin UI，然後點選“Run Query”按鈕以列出所有收集到的追蹤資料。你應該會看到一條追蹤記錄。點選“Show”按鈕檢視該追蹤記錄的詳情。

日誌中的關聯 ID

關聯 ID 提供了一種有用的方式，可以將日誌檔案中的行與 span/trace 關聯起來。如果你使用 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 Tracing 支援多種追蹤器實現，因此與 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.zipkin.tracing.* 配置屬性來配置報告給 Zipkin。

OpenTelemetry 與 Wavefront

使用 OpenTelemetry 進行追蹤並報告給 Wavefront 需要以下依賴項

  • io.micrometer:micrometer-tracing-bridge-otel - 將 Micrometer Observation API 橋接到 OpenTelemetry。

  • io.micrometer:micrometer-tracing-reporter-wavefront - 將追蹤資料報告給 Wavefront。

使用 management.wavefront.* 配置屬性來配置報告給 Wavefront。

OpenTelemetry 與 OTLP

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

  • io.micrometer:micrometer-tracing-bridge-otel - 將 Micrometer Observation API 橋接到 OpenTelemetry。

  • io.opentelemetry:opentelemetry-exporter-otlp - 將追蹤資料報告給可接受 OTLP 的收集器。

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

OpenZipkin Brave 與 Zipkin

使用 OpenZipkin Brave 進行追蹤並報告給 Zipkin 需要以下依賴項

  • io.micrometer:micrometer-tracing-bridge-brave - 將 Micrometer Observation API 橋接到 Brave。

  • io.zipkin.reporter2:zipkin-reporter-brave - 將追蹤資料報告給 Zipkin。

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

OpenZipkin Brave 與 Wavefront

使用 OpenZipkin Brave 進行追蹤並報告給 Wavefront 需要以下依賴項

  • io.micrometer:micrometer-tracing-bridge-brave - 將 Micrometer Observation API 橋接到 Brave。

  • io.micrometer:micrometer-tracing-reporter-wavefront - 將追蹤資料報告給 Wavefront。

使用 management.wavefront.* 配置屬性來配置報告給 Wavefront。

與 Micrometer Observation 整合

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

建立自定義 Span

你可以透過啟動一個觀測來建立自己的 span。為此，將 ObservationRegistry 注入到你的元件中

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 ...
		});
	}

}

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

如果你只想建立一個 span 而不建立指標 (metric)，你需要使用 Micrometer 提供的較低級別的 Tracer API。

Baggage

你可以使用 Tracer API 建立 baggage

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
		}
	}

}

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

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

測試

當使用 @SpringBootTest 時，負責報告資料的追蹤元件不會自動配置。詳情請參閱使用追蹤。