You can inject OpenTelemetry Tracer using the regular @Inject annotation and use SpanBuilder to manually create, star and stop spans.

@Path("/")
public class HelidonEndpoint {

    @Inject
    Tracer tracer; 

    @GET
    @Path("/span")
    public Response span() {
        Span span = tracer.spanBuilder("new") 
                .setSpanKind(SpanKind.CLIENT)
                .setAttribute("someAttribute", "someValue")
                .startSpan();

        span.end();

        return Response.ok().build();
    }
}

• Inject Tracer.
• Use Tracer.spanBuilder to create and start new Span.

Helidon Microprofile Telemetry is integrated with Helidon Tracing API. This means that both APIs can be mixed, and all parent hierarchies will be kept. In the case below, @WithSpan annotated method is mixed with manually created io.helidon.tracing.Span:

private io.helidon.tracing.Tracer helidonTracerInjected;

@Inject
GreetResource(io.helidon.tracing.Tracer helidonTracerInjected) {
    this.helidonTracerInjected = helidonTracerInjected; 
}

@GET
@Path("mixed_injected")
@Produces(MediaType.APPLICATION_JSON)
@WithSpan("mixed_parent_injected")
public GreetingMessage mixedSpanInjected() {
    io.helidon.tracing.Span mixedSpan = helidonTracerInjected.spanBuilder("mixed_injected") 
            .kind(io.helidon.tracing.Span.Kind.SERVER)
            .tag("attribute", "value")
            .start();
    mixedSpan.end();

    return new GreetingMessage("Mixed Span Injected" + mixedSpan);
}

• Inject io.helidon.tracing.Tracer.
• Use the injected tracer to create io.helidon.tracing.Span using the spanBuilder() method.

The span is then started and ended manually. Span parent relations will be preserved. This means that span named "mixed_injected" with have parent span named "mixed_parent_injected", which will have parent span named "mixed_injected".

Another option is to use the Global Tracer:

@GET
@Path("mixed")
@Produces(MediaType.APPLICATION_JSON)
@WithSpan("mixed_parent")
public GreetingMessage mixedSpan() {
    io.helidon.tracing.Tracer helidonTracer = io.helidon.tracing.Tracer.global(); 
    io.helidon.tracing.Span mixedSpan = helidonTracer.spanBuilder("mixed") 
            .kind(io.helidon.tracing.Span.Kind.SERVER)
            .tag("attribute", "value")
            .start();
    mixedSpan.end();

    return new GreetingMessage("Mixed Span" + mixedSpan);
}

• Obtain tracer using the io.helidon.tracing.Tracer.global() method;
• Use the created tracer to create a span.

The span is then started and ended manually. Span parent relations will be preserved.

To obtain the current span, it can be injected by CDI. The current span can also be obtained using the static method Span.current().

@Path("/")
public class HelidonEndpoint {
    @Inject
    Span span; 

    @GET
    @Path("/current")
    public Response currentSpan() {
        return Response.ok(span).build(); 
    }

    @GET
    @Path("/current/static")
    public Response currentSpanStatic() {
        return Response.ok(Span.current()).build(); 
    }
}

• Inject the current span.
• Use the injected span.
• Use Span.current() to access the current span.

The same functionality is available for the Baggage API:

@Path("/")
public class HelidonEndpoint {
    @Inject
    Baggage baggage; 

    @GET
    @Path("/current")
    public Response currentBaggage() {
        return Response.ok(baggage.getEntryValue("baggageKey")).build(); 
    }

    @GET
    @Path("/current/static")
    public Response currentBaggageStatic() {
        return Response.ok(Baggage.current().getEntryValue("baggageKey")).build(); 
    }
}

• Inject the current baggage.
• Use the injected baggage.
• Use Baggage.current() to access the current baggage.

Applications and libraries can register listeners to be notified at several moments during the lifecycle of every span:

• Before a new span starts

• After a new span has started

• After a span ends

• After a span is activated (creating a new scope)

• After a scope is closed

The next sections explain how you can write and add a listener and what it can do. See the SpanListener Javadoc for more information.

Understanding What Listeners Do

Adding a Listener

The OpenTelemetry Java Agent may influence the work of MicroProfile Telemetry, on how the objects are created and configured. Helidon will do "best effort" to detect the use of the agent. But if there is a decision to run the Helidon app with the agent, a configuration property should be set:

otel.agent.present=true

This way, Helidon will explicitly get all the configuration and objects from the Agent, thus allowing correct span hierarchy settings.

For example, Jaeger will be used for gathering of the tracing information.

docker run -d --name jaeger \
  -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 6831:6831/udp \
  -p 6832:6832/udp \
  -p 5778:5778 \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 14250:14250 \
  -p 14268:14268 \
  -p 14269:14269 \
  -p 9411:9411 \
  jaegertracing/all-in-one:1.50

All the tracing information gathered from the examples runs is accessible from the browser in the Jaeger UI under http://localhost:16686/

Together with Helidon Telemetry dependency, an OpenTelemetry Exporter dependency should be added to project’s pom.xml file.

<dependencies>
    <dependency>
        <groupId>io.helidon.microprofile.telemetry</groupId>
        <artifactId>helidon-microprofile-telemetry</artifactId> 
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-jaeger</artifactId>  
    </dependency>
</dependencies>

• Helidon Telemetry dependency.
• OpenTelemetry Jaeger exporter.

Add these lines to META-INF/microprofile-config.properties:

otel.sdk.disabled=false     
otel.traces.exporter=jaeger 
otel.exporter.name=greeting-service 

• Enable MicroProfile Telemetry.
• Set exporter to Jaeger.
• Name of our service.

Here we enable MicroProfile Telemetry, set tracer to "jaeger" and give a name, which will be used to identify our service in the tracer.

<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-zipkin</artifactId>
</dependency>

To create simple services, use @WithSpan and Tracer to create span and let MicroProfile OpenTelemetry handle them.

@Path("/greet")
public class GreetResource {

    @GET
    @WithSpan("default") 
    public String getDefaultMessage() {
        return "Hello World";
    }
}

• Use of @WithSpan with name "default".

Now let’s call the Greeting endpoint:

curl localhost:8080/greet
Hello World

Next, launch the Jaeger UI at http://localhost:16686/. The expected output is:

@Inject
private Tracer tracer; 

@GET
@Path("custom")
@Produces(MediaType.APPLICATION_JSON)
@WithSpan 
public JsonObject useCustomSpan() {
    Span span = tracer.spanBuilder("custom") 
            .setSpanKind(SpanKind.INTERNAL)
            .setAttribute("attribute", "value")
            .startSpan();
    span.end(); 

    return Json.createObjectBuilder()
            .add("Custom Span", span.toString())
            .build();
}

• Inject OpenTelemetry Tracer.
• Create a span around the method useCustomSpan().
• Create a custom INTERNAL span and start it.
• End the custom span.

Let us call the custom endpoint:

curl localhost:8080/greeting/custom

Again you can launch the Jaeger UI at http://localhost:16686/. The expected output is:

Now let us use multiple services calls. In the example below our main service will call the secondary services. Each method in each service will be annotated with @WithSpan annotation.

@Uri("http://localhost:8081/secondary")
private WebTarget target; 

@GET
@Path("/outbound")
@WithSpan("outbound") 
public String outbound() {
    return target.request().accept(MediaType.TEXT_PLAIN).get(String.class); 
}

• Inject WebTarget pointing to Secondary service.
• Wrap method using WithSpan.
• Call the secondary service.

The secondary service is basic; it has only one method, which is also annotated with @WithSpan.

@GET
@WithSpan 
public String getSecondaryMessage() {
    return "Secondary"; 
}

• Wrap method in a span.
• Return a string.

Let us call the Outbound endpoint:

curl localhost:8080/greet/outbound
Secondary

The greeting-service call secondary-service. Each service will create spans with corresponding names, and a service class hierarchy will be created.

Launch the Jaeger UI at http://localhost:16686/ to see the expected output (shown below).

This example is available at the Helidon official GitHub repository.