追蹤

Spring Boot Actuator 為 Micrometer Tracing 提供依賴管理和自動組態，Micrometer Tracing 是熱門追蹤器程式庫的外觀模式。

若要深入了解 Micrometer Tracing 的功能，請參閱其參考文件。

支援的追蹤器

Spring Boot 隨附以下追蹤器的自動組態

開始使用

我們需要一個範例應用程式，可以用於開始使用追蹤。就我們的目的而言，開發您的第一個 Spring Boot 應用程式章節中涵蓋的簡單「Hello World!」網路應用程式就足夠了。我們將使用 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 執行後，您可以啟動您的應用程式。

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

Hello World!

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

現在開啟 Zipkin UI，網址為 localhost:9411，然後按下「執行查詢」按鈕以列出所有收集到的追蹤。您應該會看到一個追蹤。按下「顯示」按鈕以查看該追蹤的詳細資訊。

記錄關聯 ID

關聯 ID 提供了一種有用的方式，可將記錄檔中的行連結到 spans/traces。如果您使用 Micrometer Tracing，Spring Boot 預設會在您的記錄中包含關聯 ID。

預設關聯 ID 是從 traceId 和 spanId MDC 值建構而來。例如，如果 Micrometer Tracing 已新增 traceId 為 803B448A0489F84084905D3093480352 的 MDC 和 spanId 為 3425F23BB2432450 的 MDC，則記錄輸出將包含關聯 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 包含尾隨空格，以便預設情況下將其與緊隨其後的記錄器名稱分隔開。

傳播追蹤

若要自動透過網路傳播追蹤，請使用自動組態的 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.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 而不建立指標，則需要使用 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 傳播，則 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 時，報告資料的追蹤元件不會自動組態。有關更多詳細資訊，請參閱使用追蹤。