Azure SDK for Java でトレースを構成する

この記事では、トレース機能を統合するために Azure SDK for Java を構成する方法の概要について説明します。

Azure クライアント ライブラリでトレースを有効にするには、OpenTelemetry SDK を使用するか、または OpenTelemetry と互換性のあるエージェントを使用します。 OpenTelemetry は、クラウドネイティブ ソフトウェアのテレメトリ データを生成、キャプチャ、収集するためによく使用されるオープンソースの監視フレームワークです。

トレースに関連する 2 つの重要な概念があります。スパンとトレースです。 スパンは、トレース内の 1 つの操作を表します。 スパンは、HTTP 要求、リモート プロシージャ コール (RPC)、データベース クエリ、またはコードのパスを表すことができます。 トレースは、システムでの作業のパスを示すスパンのツリーです。 TraceID と呼ばれる一意の 16 バイト シーケンスを使用して、トレースをそれ自体で区別できます。 これらの概念、および OpenTelemetry との関係の詳細については、OpenTelemetry のドキュメントを参照してください。

Azure Monitor Java エージェントを使用した Azure SDK のトレース

Azure Monitor Java インプロセス エージェントを使用することで、コードを変更することなく、アプリケーションの監視を有効にできます。 詳しくは、「Java アプリケーションのための Azure Monitor OpenTelemetry ベースの自動インストルメンテーション」を参照してください。 Azure SDK サポートは、エージェント バージョン 3.2 以降では既定で有効になっています。

OpenTelemetry エージェント使用した Azure SDK 呼び出しのトレース

OpenTelemetry Java エージェントを使用する場合、バージョン 1.12.0 以降、Azure SDK インストルメンテーションがすぐに有効になります。

エクスポーターの構成、手動によるインストルメンテーションの追加、またはテレメトリの強化の方法の詳細については、「Java 用の OpenTelemetry のインストルメンテーション」を参照してください。

Note

OpenTelemetry エージェントの成果物は安定していますが、ネットワーク経由のテレメトリの安定性は保証されていません。これにより、Azure SDK によって生成されるスパン名と属性名が、エージェントを更新すると時間の経過に伴い変化する可能性があります。 詳細については、「互換性要件」を参照してください。

OpenTelemetry SDK を使用してアプリケーションを手動でインストルメント化する (プレビュー)

OpenTelemetry SDK を直接使用する場合は、選択したバックエンドに対して SDK とエクスポーターを必ず構成してください。 詳細については、「OpenTelemetry のドキュメント」を参照してください。

Azure SDK のトレースを有効にするには、最新の com.azure:azure-core-tracing-opentelemetry パッケージをアプリケーションに追加します。 たとえば Maven では、pom.xml ファイルに次のエントリを追加します。

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-tracing-opentelemetry</artifactId>
</dependency>

ここでアプリケーションを実行する場合は、バックエンドで Azure SDK のスパンを取得する必要があります。 ただし、非同期呼び出しでは、Azure SDK とアプリケーション スパンの間の相関関係が壊れている可能性があります。

既定では、Azure SDK は OpenTelemetry によって暗黙的に伝達された io.opentelemetry.context.Context.current() を新しいスパンの親として使用します。 非同期呼び出しでは、暗黙的なコンテキストの伝達が中断されます。 OpenTelemetry エージェントはコンテキストの伝達を支援することでこの問題を解決しますが、OpenTelemetry SDK にはこのような機能はありません。

トレース コンテキストを明示的に渡す

Azure SDK では、trace-context キーの下で明示的に com.azure.core.util.Context を介してトレース コンテキストを渡すことができます。 明示的なトレース コンテキストを指定すると、Azure SDK は暗黙的なトレース コンテキストではなく、明示的なトレース コンテキストを使用するため、アプリケーションと Azure SDK スパンの間の相関が可能になります。

次の例では、受信 web 要求が手動でトレースされると、アプリケーション構成クライアント ライブラリがこの要求のスコープ内で非同期に呼び出されます。

Span span = TRACER.spanBuilder("incoming request").startSpan();
io.opentelemetry.context.Context traceContext = io.opentelemetry.context.Context.root().with(span);

// Put the incoming-request span (wrapped into the OpenTelemetry Context) into the Azure SDK Context
// and pass it over to the Application Configuration call.
appConfigClient.setConfigurationSettingWithResponse(settings, true, new com.azure.core.util.Context("trace-context", traceContext));

// You could also pass the context using the reactor `contextWrite` method under the same `trace-context` key.
appConfigAsyncClient.setConfigurationSettingWithResponse(settings)
   .contextWrite(reactor.util.context.Context.of("trace-context", traceContext))

//...

Azure SDK のトレース規則

SDK が生成するスパンと属性については、AZURE SDK セマンティック規則の仕様に関する記事を参照してください。 Azure SDK (および OpenTelemetry) のセマンティック規則は安定しておらず、将来変更される可能性があります。

次のステップ

Azure SDK for Java の主要な分野横断的機能の概要を理解できたので、Java および Azure ID を使用した Azure 認証に関する記事を参照して、セキュリティで保護されたアプリケーションの作成方法を確認してください。