Comment écrire automatiquement un TraceId dans l'en-tête de la réponse HTTP pour les applications Java et Node.js - Managed Service for OpenTelemetry

Par défaut, l'agent OpenTelemetry inclut les ID de trace uniquement dans les en-têtes de requête HTTP. Le renvoi des ID de trace dans les en-têtes de réponse HTTP permet aux consommateurs d'API et aux systèmes frontend de corréler des réponses HTTP spécifiques avec leurs traces distribuées backend. Cette approche facilite le débogage des problèmes signalés par les utilisateurs et le suivi des requêtes de bout en bout.

Cette rubrique présente les implémentations pour Java et Node.js :

Langage	Approche	Effort	Quand l'utiliser
Java	Extension JAR préconçue	Faible	Choix par défaut. Fonctionne immédiatement sans code personnalisé.
Java	Extension d'agent personnalisée	Moyen	L'extension préconçue ne répond pas à vos exigences.
Node.js	`responseHook` dans `HttpInstrumentation`	Faible	Approche standard pour les applications Node.js.

Java

Les deux méthodes ci-dessous utilisent le mécanisme d'extension de l'agent Java OpenTelemetry pour injecter les en-têtes TraceId et SpanId dans les réponses HTTP.

Méthode 1 : Utiliser l'extension préconçue

Managed Service for OpenTelemetry fournit une extension JAR préconçue qui ajoute automatiquement les en-têtes TraceId et SpanId à chaque réponse HTTP. Aucun code personnalisé n'est requis.

Téléchargez l'extension JAR : ot-java-agent-extension-1.28.0.jar.

Ajoutez -Dotel.javaagent.extensions à la commande de démarrage, en indiquant le chemin vers le fichier JAR téléchargé. Remplacez les espaces réservés suivants par des valeurs réelles :

Espace réservé	Description
`<token>`	Jeton d'authentification pour l'exportateur OTLP
`<endpoint>`	URL du endpoint OTLP de votre instance Managed Service for OpenTelemetry

   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

Méthode 2 : Créer une extension personnalisée

Si l'extension préconçue ne répond pas à vos exigences, créez une extension d'agent Java OpenTelemetry personnalisée et empaquetez-la sous forme de fichier JAR.

Prérequis

Avant de commencer, assurez-vous que vous disposez des éléments suivants :

L'agent Java OpenTelemetry configuré
La version 1.24.0 ou ultérieure de l'agent Java OpenTelemetry

Procédure

Créez un projet et ajoutez les dépendances. Ajoutez ce qui suit au fichier pom.xml :

Important

La version de la dépendance opentelemetry-javaagent doit correspondre à la version de l'agent Java OpenTelemetry utilisée par votre application.

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

Créez la classe AgentHttpResponseCustomizer. Cette classe implémente HttpServerResponseCustomizer pour injecter l'ID de trace et l'ID de span dans les réponses 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();

     // 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);
    }
   }

Générez l'extension JAR. Le fichier JAR est généré dans le répertoire target.
```
   mvn clean package
```

Démarrez l'application avec l'extension. Ajoutez -Dotel.javaagent.extensions à la commande de démarrage, en indiquant le chemin vers le fichier JAR généré :

   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

Pour les applications Node.js, ajoutez un responseHook à HttpInstrumentation pour injecter les ID de trace dans les en-têtes de réponse HTTP.

Procédure

(Facultatif) Si l'application Node.js n'est pas encore intégrée à OpenTelemetry, téléchargez le projet de démo Node.js et suivez les instructions pour configurer l'intégration au préalable.

Modifiez l'initialisation de HttpInstrumentation pour inclure un responseHook. Ce hook ajoute l'ID de trace et l'ID de span à chaque réponse HTTP :

   // 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],
   });