このバージョンはまだ開発中であり、まだ安定しているとは見なされていません。最新の安定バージョンについては、Spring Boot 4.0.3 を使用してください！

トレース

Spring Boot Actuator は、一般的なトレーサーライブラリのファサードである Micrometer トレース (英語) の依存関係管理と自動構成を提供します。

Micrometer トレース機能の詳細については、リファレンスドキュメント (英語) を参照してください。

サポートされているトレーサー

Spring Boot には、次のトレーサーの自動構成が同梱されています。

入門

トレースを始めるには、サンプルアプリケーションが必要です。今回の目的には、初めての Spring Boot アプリケーションの開発セクションで紹介されているシンプルな "Hello World!" Web アプリケーションで十分です。Brave トレーサーを使用し、トレースバックエンドには 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() メソッドには logger ステートメントが追加されていますが、これは後で重要になります。

ここで、org.springframework.boot:spring-boot-starter-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 リクエストの観測が作成され、それが Brave にブリッジされ、Zipkin に新しいトレースが報告されます。

次に、localhost:9411 で Zipkin UI を開き、クエリの実行 ボタンを押して、収集されたすべてのトレースを一覧表示します。トレースが 1 つ表示されるはずです。「表示」ボタンを押すと、そのトレースの詳細が表示されます。

相関 ID のログ記録

相関 ID は、ログファイル内の行をスパン / トレースにリンクする便利な方法を提供します。Micrometer トレースを使用している場合、Spring Boot はデフォルトでログに相関 ID を含めます。

デフォルトの相関 ID は、traceId および spanId MDC (英語) 値から構築されます。例: Micrometer トレースが 803B448A0489F84084905D3093480352 の MDC traceId と 3425F23BB2432450 の MDC spanId を追加した場合、ログ出力には相関 ID [803B448A0489F84084905D3093480352-3425F23BB2432450] が含まれます。

相関 ID に別の形式を使用したい場合は、logging.pattern.correlation プロパティを使用して相関 ID を定義できます。例: 以下は、以前に Spring Cloud Sleuth で使用されていた形式で Logback の相関 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 (Javadoc) 、RestClient (Javadoc) 、WebClient (Javadoc) を作成すると、自動トレース伝播は機能しません。

トレーサーの実装

Micrometer Tracer は複数のトレーサー実装をサポートしているため、Spring Boot との依存関係は複数可能です。OpenTelemetry と OTLP、Brave と Zipkin の組み合わせは一般的であり、専用のスターターが用意されています。

OpenTelemetry と OTLP

OpenTelemetry を使用したトレースと OTLP を使用したレポートには、次の依存関係が必要です。

  • org.springframework.boot:spring-boot-starter-opentelemetry

management.opentelemetry.tracing.export.otlp.* 構成プロパティを使用して、OTLP を使用したレポートを構成します。

OTLP スパンエクスポーターに高度なカスタマイズを適用する必要がある場合は、OtlpHttpSpanExporterBuilderCustomizer (Javadoc) または OtlpGrpcSpanExporterBuilderCustomizer (Javadoc) Bean の登録を検討してください。これらは、OtlpHttpSpanExporter または OtlpGrpcSpanExporter の作成前に呼び出されます。カスタマイザーは、自動構成によって適用されるものよりも優先されます。

OpenTelemetry と Zipkin

OpenTelemetry を使用したトレースと Zipkin へのレポートには、次の依存関係が必要です。

  • org.springframework.boot:spring-boot-micrometer-tracing-opentelemetry - Spring Boot は OpenTelemetry 経由の Micrometer トレースをサポートします。

  • io.micrometer:micrometer-tracing-bridge-otel - Micrometer Observation API を OpenTelemetry にブリッジします。

  • org.springframework.boot:spring-boot-zipkin - Spring Boot による Zipkin のサポート。

  • io.opentelemetry:opentelemetry-exporter-zipkin - トレースを Zipkin に報告する OpenTelemetry エクスポータ。

management.tracing.export.zipkin.* 構成プロパティを使用して、Zipkin へのレポートを構成します。

OpenZipkin Brave と Zipkin

OpenZipkin Brave を使用したトレースと Zipkin へのレポートには、次の依存関係が必要です。

  • org.springframework.boot:spring-boot-starter-zipkin

management.tracing.export.zipkin.* 構成プロパティを使用して、Zipkin へのレポートを構成します。

Micrometer Observation との統合

TracingAwareMeterObservationHandler (英語) は ObservationRegistry (英語) に自動的に登録され、完了した観測ごとにスパンが作成されます。

カスタムスパンの作成

観測を開始することで、独自のスパンを作成できます。そのためには、コンポーネントに 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-tag=some-value" を持つ "some-operation" という名前の観測が作成されます。

メトリクスを作成せずにスパンを作成する場合は、Micrometer の下位レベルの Tracer API (英語) を使用する必要があります。

バゲッジ

Tracer (英語) API を使用してバゲッジを作成できます。

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

}

この例では、値 value1 を持つ baggage1 という名前のバゲッジを作成します。W3C 伝播を使用している場合、バゲッジはネットワーク上で自動的に伝播されます。B3 伝播を使用している場合、バゲッジは自動的には伝播されません。ネットワーク上でバゲージを手動で伝播するには、management.tracing.baggage.remote-fields 構成プロパティを使用します (これは W3C にも機能します)。上の例では、このプロパティを baggage1 に設定すると、HTTP ヘッダー baggage1: value1 が生成されます。

バゲージを MDC に伝播する場合は、management.tracing.baggage.correlation.fields 構成プロパティを使用します。上の例では、このプロパティを baggage1 に設定すると、baggage1 という名前の MDC エントリが作成されます。

テスト

@SpringBootTest (Javadoc) を使用する場合、データをレポートしているトレースコンポーネントは自動的に構成されません。詳細については、トレースの使用を参照してください。