How to automatically write a TraceId to the HTTP Response Header for Java and Node.js applications - Managed Service for OpenTelemetry

OpenTelemetry aracı, varsayılan olarak izleme kimliklerini yalnızca HTTP istek üst bilgilerine ekler. İzleme kimliklerini HTTP yanıt üst bilgilerinde döndürmek, API tüketicilerinin ve ön uç sistemlerinin belirli HTTP yanıtlarını bunların arka uç dağıtık izleriyle ilişkilendirmesine olanak tanır; bu sayede kullanıcıların bildirdiği sorunları hata ayıklamak ve istekleri uçtan uca izlemek kolaylaşır.

Bu konu, Java ve Node.js uygulamalarını kapsar:

Dil	Yaklaşım	Çaba	Ne zaman kullanılır
Java	Hazır uzantı JAR dosyası	Düşük	Varsayılan seçimdir. Özel kod gerektirmeden çalışmaya hazırdır.
Java	Özel aracı uzantısı	Orta	Hazır uzantı gereksinimlerinizi karşılamaz.
Node.js	`HttpInstrumentation` içindeki `responseHook`	Düşük	Node.js uygulamaları için standart yaklaşımdır.

Java

Aşağıdaki iki yöntem de OpenTelemetry Java aracı uzantı mekanizmasını kullanarak TraceId ve SpanId üst bilgilerini HTTP yanıtlarına enjekte eder.

Yöntem 1: Hazır uzantıyı kullanın

Managed Service for OpenTelemetry, her HTTP yanıtına otomatik olarak TraceId ve SpanId üst bilgilerini ekleyen hazır bir uzantı JAR dosyası sağlar. Özel kod gerekmez.

Uzantı JAR dosyasını indirin: ot-java-agent-extension-1.28.0.jar.

Başlatma komutuna indirilen JAR dosyasını işaret eden -Dotel.javaagent.extensions parametresini ekleyin. Aşağıdaki yer tutucuları gerçek değerlerle değiştirin:

Yer Tutucu	Açıklama
`<token>`	OTLP dışa aktarıcısı için kimlik doğrulama belirteci
`<endpoint>`	Managed Service for OpenTelemetry örneğinizin OTLP uç noktası URL'si

   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

Yöntem 2: Özel bir uzantı oluşturun

Hazır uzantı gereksinimlerinizi karşılamıyorsa özel bir OpenTelemetry Java aracı uzantısı oluşturup bunu bir JAR dosyası olarak paketleyin.

Ön koşullar

Başlamadan önce şunlara sahip olduğunuzdan emin olun:

Yapılandırılmış OpenTelemetry Java aracı
OpenTelemetry Java aracı sürüm 1.24.0 veya üzeri

Yordam

Bir proje oluşturun ve bağımlılıkları ekleyin. pom.xml dosyasına aşağıdakileri ekleyin:

Önemli

opentelemetry-javaagent bağımlılık sürümü, uygulamanızın kullandığı OpenTelemetry Java aracı sürümüyle eşleşmelidir.

   <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 sınıfını oluşturun. Bu sınıf, izleme kimliğini ve span kimliğini HTTP yanıtlarına enjekte etmek için HttpServerResponseCustomizer arayüzünü uygular:

   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();

     // Add trace ID and span ID to the HTTP response header.
     // Change the header names to match your requirements.
     responseMutator.appendHeader(response, "TraceId", traceId);
     responseMutator.appendHeader(response, "SpanId", spanId);
    }
   }

Uzantı JAR dosyasını derleyin. JAR dosyası target dizininde oluşturulur.
```
   mvn clean package
```

Uygulamayı uzantıyla birlikte başlatın. Başlatma komutuna derlenen JAR dosyasını işaret eden -Dotel.javaagent.extensions parametresini ekleyin:

   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 uygulamaları için, izleme kimliklerini HTTP yanıt üst bilgilerine enjekte etmek amacıyla HttpInstrumentation öğesine bir responseHook ekleyin.

Yordam

(İsteğe bağlı) Node.js uygulaması henüz OpenTelemetry ile entegre edilmemişse Node.js demo projesini indirin ve entegrasyonu kurmak için bu projeyi takip edin.

Her HTTP yanıtına izleme kimliğini ve span kimliğini ekleyen bu hook'u içerecek şekilde HttpInstrumentation başlatmasını bir responseHook ile değiştirin:

   // Replace the default HttpInstrumentation initialization:
   //
   // registerInstrumentations({
   //   tracerProvider: provider,
   //   instrumentations: [new HttpInstrumentation(), ExpressInstrumentation],
   // });

   // Create HttpInstrumentation with a custom responseHook:
   const httpInstrumentation = new HttpInstrumentation({
    responseHook: (span, response) => {
     // Get the trace ID and span ID from the span context
     const traceId = span.spanContext().traceId;
     const spanId = span.spanContext().spanId;

     // Add trace ID and span ID to the HTTP response header
     response.setHeader('TraceId', traceId);
     response.setHeader('SpanId', spanId);

     return response;
    },
   });

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