Eclipse MicroProfile OpenTracing

Provided version of the API: MicroProfile Open Tracing 2.0

Background

The Open Tracing API was created to allow easier tracing of the flow of a request in microservices environment across service boundaries.

A full overview for the reasoning behind the API can be found in the README of the MicroProfile OpenTracing source code repository.

The complete specification is maintained in the same repository.

Text and Binary Carriers Support

The Payara Platform implementation of the io.opentracing.Tracer interface supports the following carriers:

  • TextMap carriers with HTTP_HEADERS and TEXT_MAP formats

  • ByteBuffer carriers that use the BINARY format

JAX-WS Support

The Payara Platform’s MicroProfile implementation supports tracing of requests that are handled by SOAP Web Services implemented via the JAX-WS API. Since JAX-WS is only supported on Payara Server Full Profile, this support is not covered on Payara Micro.

OpenTracing Configuration

You can configure the notifiers and open tracing service by using the asadmin commands and also using the Administration console.

Using Alternate Opentracing Implementations

If you wish to use an alternative implementation of OpenTracing, i.e. Jaeger, then the alternative implementation must be provided as a jar in the lib directory of your domain. In it must be a file named io.opentracing.Tracer under META-INF/services, with the name of the class implementing io.opentracing.Tracer. That implementation must have a no-argument constructor. Alternate Opentracing implementations will only trace JAX-RS, JAX-WS and classes or methods annotated with @Traced; Payara’s own request tracing service can trace more types of request. Payara’s request tracing service MUST also be enabled, whichever implementation is being used in order for tracing to occur. All other configuration within Payara’s request tracing service will have no effect on the supplied tracer, which must be configured separately to Payara.

Activating Request Tracing is done either via the admin console or using the commands:

set-requesttracing-configuration --enabled=true --dynamic=true
bootstrap-requesttracing
All other options for request tracing are ignored as the created spans are not processed in the server’s runtime.

As an example, see https://github.com/payara/ecosystem-jaeger-tracing, which shows how to integrate a Jaeger client tracer. This can be added as a library to Payara Server with the command add-library jaeger-tracer-lib-with-dependencies. Enabling request tracing in Payara Server is then required, which will then send traces from OpenTracing to a Jaeger collector on the same host.

Upgrading from MicroProfile 3.x to 4.x

MicroProfile 4.0 brings with it a number of changes to MicroProfile OpenTracing, among these changes are some which break previous behaviour. The breaking changes are primarily to do with the removal of a number of methods from the API, and only affect the use of OpenTracing programmatically (the use of the annotations has not changed).

The following methods have all been removed, and the alternative method to use provided if available:

  • ScopeManager.active() - This method no longer returns a Scope, and now returns the active Span.

  • ScopeManager.activate(Span, boolean) - Use ScopeManager.activate(Span)

  • Scope.span() - Use ScopeManager.activeSpan(), Tracer.activeSpan(), or hold the Span reference returned from SpanBuilder.start().

  • SpanBuilder.startActive() - Use Tracer.activateSpan(Span) or ScopeManager.activate(Span)

  • SpanBuilder.startManual() - Use SpanBuilder.start().