Managed Service for OpenTelemetry:Java アプリケーションと Node.js アプリケーションの HTTP 応答ヘッダーでトレース ID を返す

Java アプリケーション

デフォルトでは、トレース ID は HTTP リクエストヘッダーでのみ指定されます。トレース ID を HTTP 応答ヘッダーで返す場合は、このトピックに記載されている手順に従って、OpenTelemetry Java エージェントの拡張機能を追加できます。この拡張機能は、OpenTelemetry Java エージェントに基づいて追加機能を提供します。

次のいずれかの方法を使用できます。

• 方法 1: すぐに使えるサービスを使用する。Managed Service for OpenTelemetry によってパッケージ化された OpenTelemetry Java エージェントの拡張機能を使用できます。この方法では、トレース ID を HTTP 応答ヘッダーで簡単に返すことができます。

• 方法 2: OpenTelemetry Java エージェントの拡張機能を作成する。Managed Service for OpenTelemetry によって提供される OpenTelemetry Java エージェントの拡張機能がビジネス要件を満たせない場合は、この方法を使用して OpenTelemetry Java エージェントの拡張機能を作成し、拡張機能を JAR ファイルとしてパッケージ化できます。

方法 1: すぐに使えるサービスを使用する

拡張機能のダウンロード URL: ot-java-agent-extension-1.28.0.jar。

Managed Service for OpenTelemetry は、OpenTelemetry Java エージェントの基本的な拡張機能を提供します。トレース ID とスパン ID が HTTP 応答ヘッダーで返されるようにするには、起動パラメーターを変更して JAR ファイルのフルパスを追加するだけで済みます。

起動パラメーターの変更方法

次のコマンドを実行して、otel.javaagent.extensions パラメーターを元の起動パラメーターに追加します: -Dotel.javaagent.extensions=/path/to/opentelemetry-java-agent-extension.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 your-app.jar

方法 2: OpenTelemetry Java エージェントの拡張機能を作成する

前提条件

• OpenTelemetry Java エージェントが構成されている。

• OpenTelemetry Java エージェントのバージョンが 1.24.0 以降である。

1. OpenTelemetry Java エージェントの拡張機能を作成する。

   1. 新しいプロジェクトを作成する。

   2. 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>

   3. AgentHttpResponseCustomizer クラスを作成して HttpServerResponseCustomizer を実装する。

      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();
      
       // トレース ID とスパン ID を HTTP 応答ヘッダーに追加します。要件に基づいてヘッダーのフィールド名を変更できます。
       responseMutator.appendHeader(response, "TraceId", traceId);
       responseMutator.appendHeader(response, "SpanId", spanId);
       }
      }

2. OpenTelemetry Java エージェントの拡張機能をビルドする。

   プロジェクトを JAR ファイルにパッケージ化し、JAR ファイルを target ディレクトリに保存する。

   mvn clean package

3. アプリケーションの起動時に OpenTelemetry Java エージェントの拡張機能を読み込む。

   次のコマンドを実行して、otel.javaagent.extensions パラメーターを元の起動パラメーターに追加します: -Dotel.javaagent.extensions=/path/to/opentelemetry-java-agent-extension.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 アプリケーション

1. (オプション) デモプロジェクトを実行して、Node.js アプリケーションを OpenTelemetry と統合します。ダウンロード URL: node.js-demo。

   Node.js アプリケーションが OpenTelemetry と統合されている場合は、デモプロジェクトをダウンロードする必要はありません。次の手順に従って、Node.js アプリケーションのコードを変更できます。

2. コードを変更して HTTP インストルメンテーションを作成する。

   HTTP インストルメンテーションを作成するときに、responseHook パラメーターなどの HttpInstrumentationConfig パラメーターを指定できます。 responseHook パラメーターは、応答生成手順を変更するのに役立ちます。このパラメーターを使用して、応答が返される前に、カスタムコンテンツを応答ヘッダーに追加できます。たとえば、トレース ID を応答ヘッダーに追加できます。

   ...
   
   // 置換されるコンテンツ。
   // registerInstrumentations({
   // tracerProvider: provider,
   // instrumentations: [new HttpInstrumentation(), ExpressInstrumentation],
   // });
   
   
   
   
   const httpInstrumentation = new HttpInstrumentation({
    // カスタム応答フックを追加します。
    responseHook: (span, response) => {
   
    // コンテキストからトレース ID とスパン ID を取得します。
    const traceId = span.spanContext().traceId;
    const spanId = span.spanContext().spanId;
   
    // トレース ID とスパン ID を HTTP 応答ヘッダーに追加します。
    response.setHeader('TraceId', traceId);
    response.setHeader('SpanId', spanId);
    // 応答オブジェクトを返します。
    return response;
    },
   });
   
   
   registerInstrumentations({
    tracerProvider: provider,
    instrumentations: [httpInstrumentation, ExpressInstrumentation],
   });
   
   ...