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.

If you are not aware with opentracing.io API, please read the specifications and documentation as to easier understand the content of this page.

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

Please note that classes in the rocks.inspectit.agent.java.sdk.opentracing.internal package and all sub-packages and for SDK internal purposes and should not be used by applications directly.

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

Type	Class / Interface	Description
rocks.inspectit.agent.java.sdk.opentracing.ExtendedTracer	Interface	Extends the io.opentracing.Tracer interface and provides additional methods (see usage section).
rocks.inspectit.agent.java.sdk.opentracing.Timer	Interface	Interface for time measuring. Users can provide custom implementation of timers for better precision (see usage section).
rocks.inspectit.agent.java.sdk.opentracing.Reporter	Interface	Reporter interface is used to when spans are finished. If the inspectIT agent is running with the application, then the tracer will be initialized with the reporter implementation that sends spans to the inspectIT CMR.
rocks.inspectit.agent.java.sdk.opentracing.TracerProvider	Class	Utility class that can be used to obtain ExtendedTracer instance.
rocks.inspectit.agent.java.sdk.opentracing.propagation.AbstractPropagator<C>	Class	Abstract class for all the propagators. If users want to develop and register their own propagators they should sub-class this class.

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 implementation is correctly intialized only if the inspectIT agent is running on the JVM where inspectIT SDK is used.

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:

Option	Description
Set custom timer	By default inspectIT tracer uses rocks.inspectit.agent.java.sdk.opentracing.util.SystemTimer that has millisecond start time precision. This done so inspectIT can be compatible with Java 6. Users can provide better timers if they run on higher Java versions or have third party dependencies that could do better.
Register propagator	This option allows overwriting of the tracer default propagators or registration of additional propagators that work with formats that inspectIT tracer is not aware of.
Create span without using current thread context	As described in the implementation details the inspectIT tracer is thread-context aware. If you would like to create spans that don't have a parent relationship to the current thread context span, then you can explicitly do this in ExtendedTracer.

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())
	}
}

Browser not supported