Application Real-Time Monitoring Service:Pass trace context across asynchronous boundaries in Java

Quando a propagação manual é necessária

O agente do ARMS propaga automaticamente o contexto de rastreamento para os seguintes padrões assíncronos, sem necessidade de alterações no código:

• Pools de threads criados com JDK, Spring ou Netty

• Programação reativa com Reactor ou RxJava

• Anotações @Async do Spring

• Frameworks reativos, como Spring Webflux e Spring Gateway

Para obter a lista completa de frameworks compatíveis, consulte Java components and frameworks supported by ARMS.

A propagação manual é necessária quando threads ou processos se comunicam por meio de intermediários que o agente do ARMS não instrumenta. Dois exemplos comuns:

Pré-requisitos

Antes de começar, certifique-se de ter:

• Application Monitoring do ARMS integrado. Para mais informações, consulte Application Monitoring overview.

• Agente do ARMS V4.x ou posterior instalado. Para verificar ou atualizar a sua versão, consulte Atualize o agente do ARMS.

Adicione dependências

Adicione as seguintes dependências do Maven ao seu projeto. Para mais informações, consulte a official OpenTelemetry documentation.

<dependencies>
    <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
    </dependency>
    <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk-trace</artifactId>
    </dependency>
    <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk</artifactId>
    </dependency>
</dependencies>
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-bom</artifactId>
      <version>1.23.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Propague o contexto entre limites assíncronos

Este padrão tem duas partes:

1. Captura: no lado do remetente, chame Context.current() para capturar o contexto de rastreamento ativo e armazená-lo junto com os dados transmitidos.

2. Restauração: no lado do receptor, chame context.makeCurrent() para restaurar o contexto capturado antes do processamento.

import io.opentelemetry.context.Context;
import io.opentelemetry.context.Scope;
import java.util.concurrent.LinkedBlockingQueue;

// Wrap both the message and its trace context
class Event {
    private final Context context;
    private final String msg;

    public Event(Context context, String msg) {
        this.context = context;
        this.msg = msg;
    }

    public Context getContext() {
        return context;
    }

    public String getMsg() {
        return msg;
    }
}

// Shared queue between producer and consumer threads
private final LinkedBlockingQueue<Event> queue = new LinkedBlockingQueue<>();

// Producer: capture the current trace context
public void produce(String msg) {
    queue.add(new Event(Context.current(), msg));
}

// Consumer: restore the trace context before processing
public void consume() throws InterruptedException {
    Event event = queue.take();
    // makeCurrent() sets the captured context as the active context.
    // The try-with-resources block ensures the context is cleaned up after processing.
    try (Scope scope = event.getContext().makeCurrent()) {
        processEvent(event);
    }
}

public void processEvent(Event event) {
    // Any spans created here automatically become children
    // of the producer's trace.
}

Próximos passos

Associe os IDs de rastreamento aos logs da aplicação para agilizar a análise de erros. Consulte Associate trace IDs with logs for a Java application.