Konfigurasikan OpenTelemetry untuk mengembalikan ID jejak di header respons HTTP untuk Java dan Node.js - Application Real-Time Monitoring Service

Secara default, Agen OpenTelemetry hanya menyertakan ID jejak dalam header permintaan HTTP. Dengan mengembalikan ID jejak dalam header respons HTTP, konsumen API dan sistem antarmuka depan dapat menghubungkan respons HTTP tertentu dengan jejak terdistribusi di backend—mempermudah debugging masalah yang dilaporkan pengguna serta pelacakan permintaan dari ujung ke ujung.

Topik ini mencakup implementasi untuk Java dan Node.js:

Bahasa	Pendekatan	Upaya	Kapan digunakan
Java	Ekstensi JAR siap pakai	Rendah	Pilihan default. Berfungsi langsung tanpa kode kustom.
Java	Ekstensi agen kustom	Sedang	Ekstensi siap pakai tidak memenuhi kebutuhan Anda.
Node.js	`responseHook` dalam `HttpInstrumentation`	Rendah	Pendekatan standar untuk aplikasi Node.js.

Java

Kedua metode berikut menggunakan mekanisme ekstensi Agen OpenTelemetry Java untuk menyisipkan header TraceId dan SpanId ke dalam respons HTTP.

Metode 1: Gunakan ekstensi siap pakai

Managed Service for OpenTelemetry menyediakan file JAR ekstensi siap pakai yang secara otomatis menambahkan header TraceId dan SpanId ke setiap respons HTTP tanpa memerlukan kode kustom.

Unduh file JAR ekstensi: ot-java-agent-extension-1.28.0.jar.

Tambahkan -Dotel.javaagent.extensions ke perintah startup, mengarahkan ke file JAR yang telah diunduh. Ganti placeholder berikut dengan nilai aktual:

Placeholder	Deskripsi
`<token>`	Token autentikasi untuk eksporter OTLP
`<endpoint>`	URL endpoint OTLP dari instans Managed Service for OpenTelemetry Anda

   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

Metode 2: Buat ekstensi kustom

Jika ekstensi siap pakai tidak memenuhi kebutuhan Anda, buat ekstensi kustom Agen OpenTelemetry Java dan kemas sebagai file JAR.

Prasyarat

Sebelum memulai, pastikan Anda telah memiliki:

Agen OpenTelemetry Java yang telah dikonfigurasi
Versi Agen OpenTelemetry Java 1.24.0 atau lebih baru

Prosedur

Buat proyek dan tambahkan dependensi. Tambahkan konten berikut ke file pom.xml:

Penting

Versi dependensi opentelemetry-javaagent harus sesuai dengan versi Agen OpenTelemetry Java yang digunakan oleh aplikasi Anda.

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

Buat kelas AgentHttpResponseCustomizer. Kelas ini mengimplementasikan HttpServerResponseCustomizer untuk menyisipkan ID jejak dan ID rentang ke dalam respons 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();

     // Tambahkan ID jejak dan ID rentang ke header respons HTTP.
     // Ubah nama header sesuai kebutuhan Anda.
     responseMutator.appendHeader(response, "TraceId", traceId);
     responseMutator.appendHeader(response, "SpanId", spanId);
    }
   }

Buat file JAR ekstensi. File JAR akan dihasilkan di direktori target.
```
   mvn clean package
```

Jalankan aplikasi dengan ekstensi tersebut. Tambahkan -Dotel.javaagent.extensions ke perintah startup, mengarahkan ke file JAR yang telah dibuat:

   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

Untuk aplikasi Node.js, tambahkan responseHook ke HttpInstrumentation guna menyisipkan ID jejak ke dalam header respons HTTP.

Prosedur

(Opsional) Jika aplikasi Node.js belum terintegrasi dengan OpenTelemetry, unduh proyek demo Node.js dan ikuti panduannya untuk menyiapkan integrasi terlebih dahulu.

Modifikasi inisialisasi HttpInstrumentation agar menyertakan responseHook. Panggilan balik ini menambahkan ID jejak dan ID rentang ke setiap respons HTTP:

   // Ganti inisialisasi HttpInstrumentation default:
   //
   // registerInstrumentations({
   //   tracerProvider: provider,
   //   instrumentations: [new HttpInstrumentation(), ExpressInstrumentation],
   // });

   // Buat HttpInstrumentation dengan responseHook kustom:
   const httpInstrumentation = new HttpInstrumentation({
    responseHook: (span, response) => {
     // Dapatkan ID jejak dan ID rentang dari konteks span
     const traceId = span.spanContext().traceId;
     const spanId = span.spanContext().spanId;

     // Tambahkan ID jejak dan ID rentang ke header respons HTTP
     response.setHeader('TraceId', traceId);
     response.setHeader('SpanId', spanId);

     return response;
    },
   });

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