可観測性

可観測性とは、実行中のシステムの内部状態を外部から観察する機能です。これは、ログ、メトリクス、トレースの 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 (Javadoc) Bean を追加で登録できます。

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

コンテキストの伝播

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

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

共通タグ

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

  • プロパティ

  • 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 観測アノテーションのサポート

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

すでにインストルメント化されているメソッドまたはクラス (たとえば、Spring Data リポジトリまたは Spring MVC コントローラー ) にアノテーションを付ける場合、重複した観察結果が取得されます。その場合、プロパティまたは ObservationPredicate (英語) を使用して自動インストルメント化を無効にしてアノテーションに依存するか、アノテーションを削除することができます。