OpenTelemetry Java Agent Traceparent Extraction Boundary in Custom Middleware

Minimal configuration

To let custom middleware and asynchronous handlers join the same trace without manual header parsing, the Java agent only needs the default W3C TraceContext propagator to be active and the async instrumentation enabled:

• OTEL_PROPAGATORS=tracecontext (or ensure the variable is not set to exclude tracecontext)
• OTEL_INSTRUMENTATION_COMMON_ASYNC_ENABLED=true (default in recent agent versions)

No additional agent‑side registration or SDK code is required.

How the agent works (confirmed facts)

The OpenTelemetry Java agent installs a servlet filter (OpenTelemetryServletFilter) early in the filter chain. This filter:

1. Extracts the inbound traceparent header using the W3C TraceContext propagator.
2. Stores the resulting Context in the current thread’s ThreadLocal via Context.current().
3. Completes the filter chain so that downstream servlets, filters, and interceptors see the propagated context.

If your custom middleware is a standard javax.servlet.Filter (or Spring interceptor) that runs after the agent’s filter, it automatically receives the correct Context and any outgoing HTTP calls made within it will inherit the trace ID.

Likely explanation for broken propagation

When trace context is lost, the most common causes are:

• The custom filter is placed before the agent’s filter, so it sees the raw header but the context has not yet been stored.
• Async work is submitted to a thread pool or CompletableFuture without wrapping the Runnable/Callable with the current Context.
• The environment variable OTEL_PROPAGATORS overrides the default and omits tracecontext.

Steps to fix for this case

1. Verify filter order: ensure your custom filter has a higher order number (i.e., runs later) than the agent’s filter. In Spring you can add @Order(Ordered.HIGHEST_PRECEDENCE + 1) or set spring.boot.admin.filter.order accordingly.
2. For any asynchronous execution (executor service, CompletableFuture, reactive streams), wrap the task:

Context ctx = Context.current();
Runnable wrapped = Context.wrap(ctx, () -> {
    // your async logic
});
executor.execute(wrapped);

3. Confirm that OTEL_PROPAGATORS is either unset or includes tracecontext. You can check at runtime with:

System.getenv("OTEL_PROPAGATORS");

4. If you are using an agent version older than 1.12.0, verify that OTEL_INSTRUMENTATION_COMMON_ASYNC_ENABLED is set to true; newer agents enable this by default.

What to verify before relying on automatic handling

• Agent version ≥ 1.0.0 for basic Context API; ≥ 1.12.0 for improved async servlet support.
• Servlet container compatibility (Tomcat 9+, Jetty 9.4+, Undertow 2.0+).
• That no custom ContextStorage or ScopeManager replacement has been installed via system properties.
• That the propagator list includes tracecontext (default unless overridden).

Missing diagnostic detail

If you are unsure whether your custom middleware runs before or after the agent’s filter, please confirm the filter order (or the equivalent interceptor order) so we can tell whether a simple re‑ordering suffices or if manual context extraction is required.