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

When you need manual propagation

The ARMS agent automatically propagates trace context for the following async patterns without code changes:

• Thread pools created with JDK, Spring, or Netty

• Reactive programming with Reactor or RxJava

• Spring @Async annotations

• Reactive frameworks such as Spring Webflux and Spring Gateway

For the full list of supported frameworks, see Java components and frameworks supported by ARMS.

Manual propagation is required when threads or processes communicate through intermediaries that the ARMS agent does not instrument. Two common examples:

Add dependencies

Add the following Maven dependencies to introduce OpenTelemetry SDK for Java. For more information, see Instrumentation.

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

Pass context across async boundaries

The pattern has two parts:

1. Capture: On the sender side, call Context.current() to capture the active trace context and store it alongside the data being passed.

2. Restore: On the receiver side, call context.makeCurrent() to restore the captured context before processing.

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

What to do next

Associate trace IDs with application logs to streamline error analysis. See Associate trace IDs with logs for a Java application.