How to automatically write a TraceId to the HTTP Response Header for Java and Node.js applications - Managed Service for OpenTelemetry: Central de Documentação do Alibaba Cloud

Por padrão, o agente OpenTelemetry inclui IDs de rastreamento apenas nos cabeçalhos de requisição HTTP. Incluir esses IDs nos cabeçalhos de resposta HTTP permite que consumidores de API e sistemas de frontend correlacionem respostas específicas aos respectivos rastreamentos distribuídos de backend. Essa prática simplifica a depuração de problemas reportados por usuários e o rastreamento de requisições de ponta a ponta.

Este tópico aborda as implementações para Java e Node.js:

Linguagem	Abordagem	Esforço	Quando usar
Java	JAR de extensão pré-compilado	Baixo	Opção padrão. Funciona imediatamente sem código personalizado.
Java	Extensão personalizada do agente	Médio	A extensão pré-compilada não atende aos requisitos.
Node.js	`responseHook` em `HttpInstrumentation`	Baixo	Abordagem padrão para aplicações Node.js.

Java

Os métodos abaixo utilizam o mecanismo de extensão do agente OpenTelemetry Java para injetar os cabeçalhos TraceId e SpanId nas respostas HTTP.

Método 1: Usar a extensão pré-compilada

O Managed Service for OpenTelemetry fornece um JAR de extensão pré-compilado que adiciona automaticamente os cabeçalhos TraceId e SpanId a todas as respostas HTTP, sem necessidade de código personalizado.

Baixe o JAR da extensão: ot-java-agent-extension-1.28.0.jar.

Adicione -Dotel.javaagent.extensions ao comando de inicialização, apontando para o JAR baixado. Substitua os espaços reservados pelos valores reais:

Espaço reservado	Descrição
`<token>`	Token de autenticação do exportador OTLP
`<endpoint>`	URL do endpoint OTLP da instância do 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: Crie uma extensão personalizada

Se a extensão pré-compilada não atender às necessidades, crie uma extensão personalizada do agente OpenTelemetry Java e empacote-a como um arquivo JAR.

Pré-requisitos

Antes de começar, verifique se você tem:

O agente OpenTelemetry Java configurado
A versão 1.24.0 ou superior do agente OpenTelemetry Java

Procedimento

Crie um projeto e adicione as dependências. Inclua o seguinte conteúdo no arquivo pom.xml:

Importante

A versão da dependência opentelemetry-javaagent deve corresponder à versão do agente OpenTelemetry Java usada pela aplicação.

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

Crie a classe AgentHttpResponseCustomizer. Ela implementa HttpServerResponseCustomizer para injetar o ID de rastreamento e o ID do span nas respostas 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 o JAR da extensão. O arquivo JAR será gerado no diretório target.
```
   mvn clean package
```

Inicie a aplicação com a extensão. Adicione -Dotel.javaagent.extensions ao comando de inicialização, apontando para o 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 aplicações Node.js, adicione um responseHook ao HttpInstrumentation para injetar IDs de rastreamento nos cabeçalhos de resposta HTTP.

Procedimento

(Opcional) Se a aplicação Node.js ainda não estiver integrada ao OpenTelemetry, baixe o projeto de demonstração Node.js e siga as instruções para configurar a integração.

Modifique a inicialização do HttpInstrumentation para incluir um responseHook. Esse hook adiciona o ID de rastreamento e o ID do span a cada resposta 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],
   });