Using Request Tracing in Applications

Terminology

Using the @WithSpan Annotation

The io.opentelemetry.instrumentation.annotations.WithSpan annotation can be placed on CDI bean methods to automatically create a tracing span for each invocation of that method.

The @WithSpan annotation accepts one optional parameter:

value: defines the name of the span. If left blank it defaults to ClassName.methodName.

 
import io.opentelemetry.instrumentation.annotations.WithSpan;

@RequestScoped
public class TracedExample {

    @WithSpan
    public String method1() {
        return "anon1";
    }

    @WithSpan("tracingTest")
    public String method2() {
        return "anon2";
    }

}

The @WithSpan annotation operates as a CDI Interceptor, so for the decorated methods to be traced they must be a) not static or private, and b) invoked through the CDI proxy (i.e. accessed from an injected reference, not via new or this). In the following example, method1 of the above class would be traced and method2 would not:

 
@Path("/")
@RequestScoped
public class JaxrsEndpoints {

    @Inject
    TracedExample tracedExample;

    @GET
    public String method1Traced() {
        return tracedExample.method1();  // traced — invoked via CDI proxy
    }

    @GET
    public String method2NotTraced() {
        return new TracedExample().method2();  // NOT traced — bypasses CDI proxy
    }

}

 
[fully.qualified.ClassName]/[methodName]/WithSpan/enabled=false

 
fish.example.TracedExample/method1/WithSpan/enabled=false

Using the OpenTelemetry Tracer API

The OpenTelemetry io.opentelemetry.api.trace.Tracer API allows you to manually start, finish, and add information to Spans for fine-grained control over span boundaries and attributes.

To access the tracer in your application, inject it from the CDI container:

 
import io.opentelemetry.api.trace.Tracer;

@RequestScoped
public class TracedComponent {

    @Inject
    Tracer tracer;
}

Starting a Span, making it the active (current) Span, and ending it is done with a try-with-resources scope block:

 
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.api.trace.Tracer;

@RequestScoped
public class TracedComponent {

    @Inject
    Tracer tracer;

    public void tracedMethod() {
        var span = tracer.spanBuilder("tracedTask").startSpan();

        try (var scope = span.makeCurrent()) {
            // do work, add attributes or events to span
            if (span.isRecording()) {
                // compute expensive attributes only if the span is being sampled
                span.setAttribute("exampleKey", "exampleValue");
            }
        } finally {
            span.setStatus(StatusCode.OK);
            span.end();
        }
    }
}

The Tracer API also gives you access to context propagation across threads and processes. For asynchronous tasks it is recommended to use a Managed Executor Service; for outbound JAX-RS calls use the default JAX-RS client implementation or MicroProfile REST Client, as these propagate trace context automatically.

For more information on configuring OpenTelemetry in your application, see OpenTelemetry Support and Server-Emitted Telemetry Signals.

Disabling Automatic Tracing of JAX-RS Methods and MicroProfile REST Client Calls

By default, calls to JAX-RS endpoints and any calls made through a MicroProfile REST Client are automatically traced by the server’s OpenTelemetry instrumentation.