Application Real-Time Monitoring Service:Add custom instrumentation with OpenTelemetry for Java

Key concepts

This section describes only common terms. For more information about other terms, see the OpenTelemetry Specification.

• span: a specific operation in a request, such as a remote call entry point or an internal method call.

• SpanContext: the context of a trace, including information such as the trace ID and span ID.

• attribute: an additional field on a span that records key information.

• Baggage: key-value pairs that are propagated throughout the entire trace.

Use the OpenTelemetry SDK for Java

You can use the OpenTelemetry SDK to perform the following operations:

• Add instrumentation to generate spans.

• Add attributes to spans.

• Propagate Baggage in the trace context.

• Get the current trace context and print information such as the trace ID and span ID.

The following sample code shows how to use the OpenTelemetry SDK to perform these operations.

@RestController
@RequestMapping("/ot")
public class OpenTelemetryController {
    private Tracer tracer;
    private ScheduledExecutorService ses = Executors.newSingleThreadScheduledExecutor();
    @PostConstruct
    public void init() {
	    OpenTelemetrySdk.builder()
			.setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
			.buildAndRegisterGlobal();
		tracer = GlobalOpenTelemetry.get().getTracer("manual-sdk", "1.0.0");
        ses.scheduleAtFixedRate(new Runnable() {
            @Override
            public void run() {
                Span span = tracer.spanBuilder("schedule")
                        .setAttribute("schedule.time", System.currentTimeMillis())
                        .startSpan();
                try (Scope scope = span.makeCurrent()) {
                    System.out.println("scheduled!");
                    Thread.sleep(500L);
                    span.setAttribute("schedule.success", true);
                    System.out.println(Span.current().getSpanContext().getTraceId()); // Get the trace ID
                } catch (Throwable t) {
                    span.setStatus(StatusCode.ERROR, t.getMessage());
                } finally {
                    span.end();
                }
            }
        }, 10, 30, TimeUnit.SECONDS);
    }
    @ResponseBody
    @RequestMapping("/parent")
    public String parent() {
        Span span = tracer.spanBuilder("parent").setSpanKind(SpanKind.SERVER).startSpan();
        try (Scope scope = span.makeCurrent()) {
            // Use Baggage to propagate custom business tags.
            Baggage baggage =  Baggage.current().toBuilder()
                    .put("user.id", "1")
                    .put("user.name", "name")
                    .build();
            try (Scope baggageScope = baggage.storeInContext(Context.current()).makeCurrent()) {
                child();
            }
            span.setAttribute("http.method", "GET");
            span.setAttribute("http.uri", "/parent");
        } finally {
            span.end();
        }
        return "parent";
    }
    private void child() {
        Span span = tracer.spanBuilder("child").startSpan();
        try (Scope scope = span.makeCurrent()) {
            System.out.println("current traceId = " + Span.current().getSpanContext().getTraceId());
            System.out.println("userId in baggage = " + Baggage.current().getEntryValue("user.id"));
            Thread.sleep(1000);
        } catch (Throwable e) {
            span.setStatus(StatusCode.ERROR, e.getMessage());
        } finally {
            span.end();
        }
    }
}

Example walkthrough:

1. In the init method of OpenTelemetryController, a scheduled task starts. A span is created at the beginning of each execution and ended when it finishes.

2. In the parent method of OpenTelemetryController, several OpenTelemetry SDK methods are called.

   1. Each time the method is called, a span named parent is created and is ended when the method finishes.

   2. The Baggage SDK is used to add two Baggage items: user.id and user.name. These items propagate to downstream applications.

   3. Two attributes are added to the span created in step 2.a.

3. The child method of OpenTelemetryController performs the following operations:

   1. Each time the method is called, a span named child is created and is ended when the method finishes. This span is a child of the one created in step 2.a.

   2. The trace ID is retrieved from the trace context and printed.

   3. The Baggage added in step 2.b is retrieved and its value is printed.

Differences between ARMS agent versions

Support for the operations in the preceding code differs between ARMS agent versions.

Instrumentation results