トレース

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

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

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

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

入門

トレースを開始するために使用できるサンプルアプリケーションが必要です。ここでは、初めての Spring Boot アプリケーションの開発セクションで説明されているシンプルな "Hello World!" Web アプリケーションで十分です。トレースバックエンドとして Zipkin を使用した OpenTelemetry トレーサーを使用します。

要約すると、メインのアプリケーションコードは次のようになります。

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() メソッドには logger ステートメントが追加されていますが、これは後で重要になります。

次に、次の依存関係を追加する必要があります。

  • 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 に報告します。

次に、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 トレーサーは複数のトレーサーの実装をサポートしているため、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 (英語) に自動的に登録され、完了した観測ごとにスパンが作成されます。

カスタムスパンの作成

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

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

バゲッジ

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

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

}

この例では、値 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) を使用する場合、データをレポートしているトレースコンポーネントは自動的に構成されません。詳細については、トレースの使用を参照してください。