opentracing.io API implementation

The inspectIT provides the opentracing.io API implementation as part of it's inspectit.agent.java.sdk project. This page provides user guide and implementation details.

Implementation details

Thread context aware

The most important property of the inspectIT Tracer implementation is that it's thread context aware. This means that consecutive spans created by same thread will have parent - child relationship by default. Thus, in most cases the users don't need to explicitly connect spans using asChildOf methods if two spans are created by same thread.

If you following the API note that using the asChildOf is safe and will have no side effects if the relationship between spans has already been made by the Tracer itself. 

No sample rate

inspectIT at the moment does not provide an option to set a sample rate. This means that all of the spans will be "sampled" and reported. The opentracing.io API does not specify a need for a sampling rate, but the inspectIT will in the future add this feature to the implementation.

Log events are ignored

Any events logged using the Span.log() methods are ignored and will not be reported nor visualized in any form in the inspectIT UI.

Single parent context reference possible

The opentracing.io specification allows a span to reference more than one parent span. This is currently limited in inspectIT implementation as span always have one direct parent reference and it will be the one to the first referred parent. However, the baggage from all referred parent contexts is propagated with the span as expected. The inspectIT Tracer may change this in future in order to align with to the specification.

Overview on main interfaces / classes

The following table provides information on the most important interfaces and classes provided by the implementation:

Usage

SDK dependency

In order to use inspectIT implementation of the opentracing.io API please add the dependency to the inspectIT Java SDK to your project. The SDK library is hosted on the maven repository (TODO link).

Acquire the Tracer

Tracer can be obtained by calling one of the get methods in the rocks.inspectit.agent.java.sdk.opentracing.TracerProvider. If the inspectIT agent is running with the application where TracerProvider is used, the get methods will always returned correctly initialized Tracer implementation. If the inspectIT is not running, then the caller can control if the returned tracer is no-operation tracer or null.

The tracer provider returns the rocks.inspectit.agent.java.sdk.opentracing.ExtendedTracer instance. This interface defines additional methods that inspectIT tracer provides for usage on top of the opentracing.io API. It's up to user to decide to code against the io.opentracing interfaces or use directly ExtendedTracer which provides some additional control.

Typical usage

Following code block describes the typical usage. You can find more example of API usage on opentracing.io Java API project.

// get the tracer from the inspectIT TracerProvider
Tracer tracer = TracerProvider.get();
// build new span with some optional custom  tags
Span span = tracer.buildSpan("my operation").withTag("key", "value").start();
// optionally attach some baggage to the span
// these are propagated with next remote call
span.setBaggageItem("user-id", "123"); 
try {
// then do some actual work
} finally {
	// finish span at the end so it's reported
	span.finish();
}

Additional options

The rocks.inspectit.agent.java.sdk.opentracing.ExtendedTracer interface provides some additional methods that users can use in order to do following:

Usage without inspectIT agent

It's possible to use inspectIT Tracer implementation also without the inspectIT agent running with the application. However, then the user must provide the rocks.inspectit.agent.java.sdk.opentracing.Reporter implementation when constructing the Tracer, which is notified about each finished span. It's up to user to define what will reporter to do with the finished spans (store them somehow, log them or something else):

public class LoggingReporter implements Reporter {


	// just log the finished span
	public void report(Span span) {
		log(span.toString())
	}
}