Devolver ID de rastreo en encabezados de respuesta HTTP - Managed Service for OpenTelemetry

De forma predeterminada, el agente de OpenTelemetry incluye los ID de rastreo únicamente en los encabezados de solicitud HTTP. Incluir estos ID en los encabezados de respuesta HTTP permite a los consumidores de API y a los sistemas frontend correlacionar respuestas HTTP específicas con sus trazas distribuidas de backend. Esto facilita la depuración de problemas reportados por usuarios y el seguimiento de solicitudes de extremo a extremo.

Este tema aborda las implementaciones para Java y Node.js:

Lenguaje	Enfoque	Esfuerzo	Cuándo utilizarlo
Java	JAR de extensión precompilado	Bajo	Opción predeterminada. Funciona de inmediato sin código personalizado.
Java	Extensión de agente personalizada	Medio	Cuando la extensión precompilada no cumple con sus requisitos.
Node.js	`responseHook` en `HttpInstrumentation`	Bajo	Enfoque estándar para aplicaciones Node.js.

Java

Los dos métodos siguientes utilizan el mecanismo de extensión del agente Java de OpenTelemetry para inyectar los encabezados TraceId y SpanId en las respuestas HTTP.

Método 1: Usar la extensión precompilada

Managed Service for OpenTelemetry proporciona un JAR de extensión precompilado que agrega automáticamente los encabezados TraceId y SpanId a cada respuesta HTTP. No se requiere código personalizado.

Descargue el JAR de extensión: ot-java-agent-extension-1.28.0.jar.
Agregue -Dotel.javaagent.extensions al comando de inicio y especifique la ruta del JAR descargado. Reemplace los marcadores de posición a continuación con los valores reales:

Marcador de posición

Descripción

<token>

Token de autenticación para el exportador OTLP

<endpoint>

URL del endpoint OTLP de su instancia de 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étodo 2: Compilar una extensión personalizada

Si la extensión precompilada no satisface sus necesidades, compile una extensión personalizada del agente Java de OpenTelemetry y empaquételela como un archivo JAR.

Requisitos previos

Antes de empezar, asegúrese de contar con lo siguiente:

El agente Java de OpenTelemetry configurado
La versión 1.24.0 o posterior del agente Java de OpenTelemetry

Procedimiento

Cree un proyecto y agregue las dependencias. Añada lo siguiente al archivo pom.xml:

Importante

La versión de la dependencia opentelemetry-javaagent debe coincidir con la versión del agente Java de OpenTelemetry que utiliza su aplicación.

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

Cree la clase AgentHttpResponseCustomizer. Esta clase implementa HttpServerResponseCustomizer para inyectar el ID de rastreo y el ID de span en las respuestas 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);
    }
   }

Compile el JAR de extensión. El archivo JAR se genera en el directorio target.
```
   mvn clean package
```

Inicie la aplicación con la extensión. Agregue -Dotel.javaagent.extensions al comando de inicio y especifique la ruta del JAR compilado:

   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

Para aplicaciones Node.js, agregue un responseHook a HttpInstrumentation para inyectar los ID de rastreo en los encabezados de respuesta HTTP.

Procedimiento

(Opcional) Si la aplicación Node.js aún no está integrada con OpenTelemetry, descargue el proyecto de demostración de Node.js y siga sus instrucciones para configurar primero la integración.

Modifique la inicialización de HttpInstrumentation para incluir un responseHook. Este hook agrega el ID de rastreo y el ID de span a cada respuesta 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],
   });

Marcador de posición	Descripción
`<token>`	Token de autenticación para el exportador OTLP
`<endpoint>`	URL del endpoint OTLP de su instancia de Managed Service for OpenTelemetry