Java および Node.js の HTTP レスポンスヘッダーに trace ID を返すように OpenTelemetry を設定 - Application Real-Time Monitoring Service

デフォルトでは、OpenTelemetry エージェントは HTTP リクエストヘッダーにのみトレース ID を含めます。HTTP レスポンスヘッダーでトレース ID を返却することで、API コンシューマーとフロントエンドシステムは、特定の HTTP レスポンスをバックエンドの分散トレースと関連付けることができます。これにより、ユーザーから報告された問題のデバッグや、リクエストのエンドツーエンドでのトレースが簡単になります。

このトピックでは、Java および Node.js の実装について説明します。

言語	アプローチ	工数	使用するケース
Java	ビルド済み拡張 JAR	低	デフォルトの選択肢です。カスタムコードは不要で、追加設定なしで動作します。
Java	カスタムエージェント拡張	中	ビルド済み拡張が要件を満たさない場合。
Node.js	`HttpInstrumentation` の `responseHook`	低	Node.js アプリケーション向けの標準的なアプローチです。

Java

以下の両方のメソッドは、OpenTelemetry Java エージェントの拡張メカニズムを使用して、TraceId および SpanId ヘッダーを HTTP レスポンスに挿入します。

方法 1: 組み込み拡張機能の使用

OpenTelemetry 向けマネージドサービスは、すべての HTTP レスポンスに TraceId および SpanId ヘッダーを自動的に追加する組み込み拡張 JAR を提供します。カスタムコードは不要です。

拡張 JAR をダウンロードします。 ot-java-agent-extension-1.28.0.jar。

-Dotel.javaagent.extensions を起動コマンドに追加し、ダウンロードした JAR を指すようにします。以下のプレースホルダーを実際の値に置き換えてください。

プレースホルダー	説明
`<token>`	OTLP エクスポーターの認証トークン
`<endpoint>`	ご利用の OpenTelemetry 向けマネージドサービスインスタンスの OTLP エンドポイント URL

   java -javaagent:path/to/opentelemetry-javaagent.jar \
    -Dotel.javaagent.extensions=path/to/opentelemetry-java-agent-extension.jar \
    -Dotel.exporter.otlp.headers=Authentication=<token> \
    -Dotel.exporter.otlp.endpoint=<endpoint> \
    -Dotel.metrics.exporter=none \
    -jar your-app.jar

方法 2: カスタム拡張機能の構築

組み込み拡張機能が要件を満たさない場合は、カスタムの OpenTelemetry Java エージェント拡張機能を構築し、JAR ファイルとしてパッケージ化します。

前提条件

開始する前に、以下を確認してください。

OpenTelemetry Java エージェントが設定済みであること
OpenTelemetry Java エージェントのバージョンが 1.24.0 以降であること

手順

プロジェクトを作成し、依存関係を追加します。pom.xml ファイルに以下を追加します。

重要

opentelemetry-javaagent の依存関係のバージョンは、ご利用のアプリケーションが使用する OpenTelemetry Java エージェントのバージョンと一致している必要があります。

   <dependencies>
    <dependency>
     <groupId>com.google.auto.service</groupId>
     <artifactId>auto-service</artifactId>
     <version>1.1.1</version>
    </dependency>

    <dependency>
     <groupId>io.opentelemetry.javaagent</groupId>
     <artifactId>opentelemetry-javaagent</artifactId>
     <version>1.28.0</version>
     <scope>compile</scope>
    </dependency>
   </dependencies>

AgentHttpResponseCustomizer クラスを作成します。このクラスは HttpServerResponseCustomizer を実装し、トレース ID とスパン ID を HTTP レスポンスに挿入します。

   package org.example;

   import com.google.auto.service.AutoService;
   import io.opentelemetry.javaagent.shaded.io.opentelemetry.api.trace.Span;
   import io.opentelemetry.javaagent.shaded.io.opentelemetry.api.trace.SpanContext;
   import io.opentelemetry.javaagent.shaded.io.opentelemetry.context.Context;
   import io.opentelemetry.javaagent.bootstrap.http.HttpServerResponseCustomizer;
   import io.opentelemetry.javaagent.bootstrap.http.HttpServerResponseMutator;

   @AutoService(HttpServerResponseCustomizer.class)
   public class AgentHttpResponseCustomizer implements HttpServerResponseCustomizer {
    @Override
    public <RESPONSE> void customize(
        Context context,
        RESPONSE response,
        HttpServerResponseMutator<RESPONSE> responseMutator) {

     SpanContext spanContext = Span.fromContext(context).getSpanContext();
     String traceId = spanContext.getTraceId();
     String spanId = spanContext.getSpanId();

     // HTTP レスポンスヘッダーにトレース ID とスパン ID を追加します。
     // 要件に合わせてヘッダー名を変更してください。
     responseMutator.appendHeader(response, "TraceId", traceId);
     responseMutator.appendHeader(response, "SpanId", spanId);
    }
   }

拡張 JAR を構築します。JAR ファイルは target ディレクトリに生成されます。
```
   mvn clean package
```

拡張機能を使用してアプリケーションを起動します。 -Dotel.javaagent.extensions を起動コマンドに追加し、構築した JAR を指すようにします。

   java -javaagent:path/to/opentelemetry-javaagent.jar \
    -Dotel.javaagent.extensions=path/to/opentelemetry-java-agent-extension.jar \
    -Dotel.exporter.otlp.headers=Authentication=<token> \
    -Dotel.exporter.otlp.endpoint=<endpoint> \
    -Dotel.metrics.exporter=none \
    -jar yourapp.jar

Node.js

Node.js アプリケーションの場合、HTTP レスポンスヘッダーにトレース ID を挿入するには、responseHook を HttpInstrumentation に追加します。

操作手順

(オプション) Node.js アプリケーションがまだ OpenTelemetry と統合されていない場合は、Node.js デモプロジェクトをダウンロードし、それに従って最初に統合をセットアップします。

HttpInstrumentation の初期化を変更して、responseHook を含めます。このフックは、すべての HTTP 応答にトレース ID とスパン ID を追加します。

   // デフォルトの HttpInstrumentation 初期化を置換します。
   //
   // registerInstrumentations({
   //   tracerProvider: provider,
   //   instrumentations: [new HttpInstrumentation(), ExpressInstrumentation],
   // });

   // カスタム responseHook を使用して HttpInstrumentation を作成します。
   const httpInstrumentation = new HttpInstrumentation({
    responseHook: (span, response) => {
     // スパンコンテキストからトレース ID とスパン ID を取得します。
     const traceId = span.spanContext().traceId;
     const spanId = span.spanContext().spanId;

     // HTTP レスポンスヘッダーにトレース ID とスパン ID を追加します。
     response.setHeader('TraceId', traceId);
     response.setHeader('SpanId', spanId);

     return response;
    },
   });

   registerInstrumentations({
    tracerProvider: provider,
    instrumentations: [httpInstrumentation, ExpressInstrumentation],
   });