Managed Service for OpenTelemetry：將TraceId自動寫入HTTP Response Header（Java和Node.js）

Java應用

預設情況下，TraceId只會在儲存在HTTP Requst Header中，如果您需要在HTTP Response Header中設定 TraceId，可參考本文使用OpenTelemetry Java Agent Extension（擴充）以增強OpenTelemetry Java Agent的功能。

本文提供了兩種方法：

• 方法一：開箱即用。直接使用Managed Service for OpenTelemetry已打包好的OpenTelemetry Java Agent擴充，簡單快捷。

• 方法二：自行實現OpenTelemetry Java Agent擴充。如果Managed Service for OpenTelemetry的擴充不滿足您的需求，可以參考此方法實現OpenTelemetry Java Agent擴充並打成JAR包。

方法一：開箱即用

擴充下載地址：ot-java-agent-extension-1.28.0.jar。

Managed Service for OpenTelemetry已經實現了簡單的OpenTelemetry Java Agent擴充，在HTTP Response Header中自動添加TraceId和SpanId欄位，只需要在啟動參數中載入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

方法二：自行實現OpenTelemetry Java Agent擴充

前提條件

• 已使用OpenTelemetry Java Agent。

• OpenTelemetry Java Agent版本為1.24.0或以上。

1. 編寫OpenTelemetry Java Agent擴充

   1. 建立一個專案。

   2. 在pom.xml中添加依賴。

      Opentelemetry-javaagent的版本需要與您使用的OpenTelemetry Java Agent版本一致。

       <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();
      
       // 在 HTTP Response Header中設定 traceId 和 spanId, Header 欄位名可以自訂
       responseMutator.appendHeader(response, "TraceId", traceId);
       responseMutator.appendHeader(response, "SpanId", spanId);
       }
      }

2. 構建OpenTelemetry Java Agent擴充。

   將程式打包成JAR包，構建後儲存在target目錄下。

   mvn clean package

3. 啟動應用時載入OpenTelemetry Java Agent擴充。

   在原有啟動參數上添加 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. （可選）下載樣本Demo：node.js-demo。

   如果您的Node.js應用已經使用OpenTelemetry接入，則無需下載樣本Demo，直接參考下一步修改Node.js應用中的代碼。

2. 修改Demo中HttpInstrumentation的建立代碼。

   建立HttpInstrumentation時可以設定HttpInstrumentationConfig參數，參數包括responseHook，該參數允許使用者傳入一個自訂方法的方法，在響應被處理之前添加自訂內容，例如在HTTP Header中添加TraceId。

   ...
   
   // 要被替換的內容
   // registerInstrumentations({
   // tracerProvider: provider,
   // instrumentations: [new HttpInstrumentation(), ExpressInstrumentation],
   // });
   
   
   
   
   const httpInstrumentation = new HttpInstrumentation({
    // 添加一個自訂的responseHook
    responseHook: (span, response) => {
   
    // 從當前上下文中擷取traceId, spanId
    const traceId = span.spanContext().traceId;
    const spanId = span.spanContext().spanId;
   
    // 將traceId, spanId添加到響應標題中
    response.setHeader('TraceId', traceId);
    response.setHeader('SpanId', spanId);
    // 返迴響應對象
    return response;
    },
   });
   
   
   registerInstrumentations({
    tracerProvider: provider,
    instrumentations: [httpInstrumentation, ExpressInstrumentation],
   });
   
   ...