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

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

OpenTelemetry SDK を使用して構成するか、OpenTelemetry 互換エージェントを使用して、Azureクライアント ライブラリでトレースを有効にすることができます。 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 エージェントを使用する場合、Azure SDKインストルメンテーションはバージョン 1.12.0 以降で有効になります。

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

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 Identity を使用した Azure 認証を参照して、安全なアプリケーションを作成する方法を学習してください。