JarCasting
OpenTracing API Extensions
This project provides API extensions to the core OpenTracing APIs.
APIs
The APIs can be included using the following:
<dependency>
<groupId>io.opentracing.contrib</groupId>
<artifactId>opentracing-api-extensions</artifactId>
</dependency>
Observer
The Observer API can be used to monitor Span related activity and perform additional tasks.
There are two types of Observer, stateful and stateless.
-
A stateful observer will use identity information supplied with the
SpanData, to maintain state information about a particularSpaninstance - and at the appropriate time perform some action using the accumulated information. -
A stateless observer will not maintain any local state information about the
Spaninstances, and instead perform tasks directly in the callback that provides the event/information of interest (e.g. recording metricsonFinishor logging events whenonLogis called).
The benefit of a stateless approach is that the same observer instance (i.e. singleton) can be used for all Span instances. Whereas the stateful approach will require an observer instance to be instantiated for each call to TracerObserver.onStart().
Registering API extensions
There are several ways an extension API can be registered for use with a Tracer.
- Native support within the
Tracerimplementation
Some Tracer implementations may decide to implement support for the extension APIs directly, by implementing the APIExtensionsManager interface which can be used for registering the API extensions.
- Using the extension
Tracerwrapper
<dependency>
<groupId>io.opentracing.contrib</groupId>
<artifactId>opentracing-api-extensions-tracer</artifactId>
</dependency>
The APIExtensionsTracer provides a single constructor which is supplied the Tracer instance to be wrapped.
This class also implements the APIExtensionsManager interface, which provides addTracerObserver and removeTracerObserver methods to enable a TracerObserver instance to be registered with the tracer wrapper, and perform relevant tasks when new spans are started.
- Spring Auto Configuration
If using Spring, then it is possible to auto-configure the API extensions tracer mentioned above by adding the following dependency:
<dependency>
<groupId>io.opentracing.contrib</groupId>
<artifactId>opentracing-api-extensions-tracer-spring-autoconfigure</artifactId>
</dependency>
Using this approach, any TracerObserver Spring @Beans will be automatically detected and registered with the API extensions tracer.
- Using the tracer resolver mechanism
The tracer resolver is used to obtain a Tracer implementation based on the dependencies and environment variables that have been defined. This means that the application code can remain independent of the specific tracer implementation that is being used.
This mechanism also enables the resolved Tracer to be 'converted' before being returned to the application. The following dependency provides such a 'converter', to automatically wrap the resolved Tracer with the APIExtensionsTracer.
<dependency>
<groupId>io.opentracing.contrib</groupId>
<artifactId>opentracing-api-extensions-tracerconverter</artifactId>
</dependency>
Additionally, TracerObserver instances can automatically be registered with the APIExtensionsTracer by providing a service loadable implementation of the interface io.opentracing.contrib.api.tracer.converter.TracerObserverResolver in the classpath.
Release
Follow instructions in RELEASE
