可観測性

可観測性とは、実行中のシステムの内部状態を外部から観察する機能です。これは、ログ、メトリクス、トレースの 3 つの柱で構成されます。

メトリクスとトレースの場合、Spring Boot は Micrometer Observation (英語) を使用します。独自の観察結果 (メトリクスとトレースにつながる) を作成するには、ObservationRegistry を注入できます。

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

import org.springframework.stereotype.Component;

@Component
public class MyCustomObservation {

	private final ObservationRegistry observationRegistry;

	public MyCustomObservation(ObservationRegistry observationRegistry) {
		this.observationRegistry = observationRegistry;
	}

	public void doSomething() {
		Observation.createNotStarted("doSomething", this.observationRegistry)
			.lowCardinalityKeyValue("locale", "en-US")
			.highCardinalityKeyValue("userId", "42")
			.observe(() -> {
				// Execute business logic here
			});
	}

}
カーディナリティの低いタグはメトリクスとトレースに追加されますが、カーディナリティの高いタグはトレースにのみ追加されます。

ObservationPredicate、GlobalObservationConvention、ObservationFilter、ObservationHandler 型の Bean は、ObservationRegistry に自動的に登録されます。任意の数の ObservationRegistryCustomizer Bean を追加登録して、レジストリをさらに構成できます。

可観測性のサポートは、スレッドおよびリアクティブパイプライン間で現在の監視を転送するためにコンテキスト伝播ライブラリ [GitHub] (英語) に依存します。デフォルトでは、ThreadLocal 値はリアクティブオペレーターで自動的には復元されません。この動作は spring.reactor.context-propagation プロパティで制御されます。このプロパティを auto に設定すると、自動伝播が有効になります。

観測の詳細については、Micrometer 観測資料 (英語) を参照してください。

JDBC の可観測性は、別のプロジェクトを使用して構成できます。データソース Micrometer プロジェクト [GitHub] (英語) は、JDBC 操作が呼び出されたときに自動的にオブザベーションを作成する Spring Boot スターターを提供します。詳細については、リファレンスドキュメント (英語) を参照してください。
R2DBC の可観測性は Spring Boot に組み込まれています。これを有効にするには、プロジェクトに io.r2dbc:r2dbc-proxy 依存関係を追加します。

共通タグ

共通タグは通常、ホスト、インスタンス、リージョン、スタックなどの動作環境の次元ドリルダウンに使用されます。共通タグは、カーディナリティの低いタグとしてすべての観測値に適用され、次の例に示すように構成できます。

  • プロパティ

  • YAML

management.observations.key-values.region=us-east-1
management.observations.key-values.stack=prod
management:
  observations:
    key-values:
      region: "us-east-1"
      stack: "prod"

前述の例では、すべての観測値に region タグと stack タグをそれぞれ us-east-1 と prod の値で追加します。

観察の防止

一部の観察が報告されるのを防ぎたい場合は、management.observations.enable プロパティを使用できます。

  • プロパティ

  • YAML

management.observations.enable.denied.prefix=false
management.observations.enable.another.denied.prefix=false
management:
  observations:
    enable:
      denied:
        prefix: false
      another:
        denied:
          prefix: false

前述の例では、denied.prefix または another.denied.prefix で始まる名前を持つすべての観測が禁止されます。

Spring Security が観測を報告しないようにするには、プロパティ management.observations.enable.spring.security を false に設定します。

監視の防止をより詳細に制御する必要がある場合は、型 ObservationPredicate の Bean を登録できます。観測は、すべての ObservationPredicate Bean がその観測に対して true を返した場合にのみ報告されます。

import io.micrometer.observation.Observation.Context;
import io.micrometer.observation.ObservationPredicate;

import org.springframework.stereotype.Component;

@Component
class MyObservationPredicate implements ObservationPredicate {

	@Override
	public boolean test(String name, Context context) {
		return !name.contains("denied");
	}

}

前述の例では、名前に "denied" が含まれるすべての観測が禁止されます。

OpenTelemetry サポート

アプリケーションで OpenTelemetry (英語) をサポートするには、いくつかの方法があります。OTel コミュニティでサポートされている OpenTelemetry Java エージェント (英語) または OpenTelemetry Spring Boot スターター (英語) を使用できます。メトリクスとトレースは、OTel ライブラリで定義されたセマンティック規則を使用します。このドキュメントでは、Micrometer と OTLP エクスポーターを使用して、Spring チームによって公式にサポートされている OpenTelemetry について説明します。メトリクスとトレースは、Spring Framework などの Spring プロジェクトのドキュメントで説明されているセマンティック規則を使用します。

Spring Boot のアクチュエーターモジュールには、OpenTelemetry の基本サポートが含まれています。

これは、型 OpenTelemetry の Bean を提供し、アプリケーションコンテキストに型 SdkTracerProvider、ContextPropagators、SdkLoggerProvider または SdkMeterProvider の Bean がある場合、自動的に登録されます。さらに、Resource Bean も提供します。自動構成された Resource の属性は、management.opentelemetry.resource-attributes 構成プロパティを介して構成できます。独自の Resource Bean を定義した場合、これは当てはまりません。

Spring Boot は、OpenTelemetry メトリクスまたはログの自動構成を提供しません。OpenTelemetry トレースは、Micrometer トレースと一緒に使用した場合にのみ自動構成されます。

次のセクションでは、ロギング、メトリクス、トレースについて詳しく説明します。

Micrometer 観測アノテーションのサポート

メトリクスのスキャンと @Timed、@Counted、@MeterTag、@NewSpan アノテーションなどのアノテーションのトレースを有効にするには、management.observations.annotations.enabled プロパティを true に設定する必要があります。この機能は、Micrometer で直接サポートされています。Micrometer (英語) および Micrometer トレース (英語) のリファレンスドキュメントを参照してください。