io.opentracing.v_030.util

Class GlobalTracer

java.lang.Object

io.opentracing.v_030.util.GlobalTracer

All Implemented Interfaces:

ActiveSpanSource, Tracer

public final class GlobalTracer
extends Object
implements Tracer

Global tracer that forwards all methods to another tracer that can be configured by calling register(Tracer).

The register method should only be called once during the application initialization phase.
If the register method is never called, the default NoopTracer is used.

Where possible, use some form of dependency injection (of which there are many) to access the `Tracer` instance. For vanilla application code, this is often reasonable and cleaner for all of the usual DI reasons.

That said, instrumentation for packages that are themselves statically configured (e.g., JDBC drivers) may be unable to make use of said DI mechanisms for Tracer access, and as such they should fall back on GlobalTracer. By and large, OpenTracing instrumentation should always allow the programmer to specify a Tracer instance to use for instrumentation, though the GlobalTracer is a reasonable fallback or default value.

Nested Class Summary

Nested classes/interfaces inherited from interface io.opentracing.v_030.Tracer

Tracer.SpanBuilder

Method Summary

Modifier and Type	Method and Description
ActiveSpan	activeSpan() Return the active span.
Tracer.SpanBuilder	buildSpan(String operationName) Return a new SpanBuilder for a Span with the given `operationName`.
<C> SpanContext	extract(Format<C> format, C carrier) Extract a SpanContext from a `carrier` of a given type, presumably after propagation across a process boundary.
static Tracer	get() Returns the constant GlobalTracer.
<C> void	inject(SpanContext spanContext, Format<C> format, C carrier) Inject a SpanContext into a `carrier` of a given type, presumably for propagation across process boundaries.
static boolean	isRegistered() Identify whether a Tracer has previously been registered.
ActiveSpan	makeActive(Span span) Wrap and "make active" a Span by encapsulating it – and any active state (e.g., MDC state) in the current thread – in a new ActiveSpan.
static void	register(Tracer tracer) Register a Tracer to back the behaviour of the global tracer.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

get

public static Tracer get()

Returns the constant GlobalTracer.

All methods are forwarded to the currently configured tracer.
Until a tracer is explicitly configured, the NoopTracer is used.

Returns:

The global tracer constant.

See Also:

register(Tracer)

register

public static void register(Tracer tracer)

Register a Tracer to back the behaviour of the global tracer.

Registration is a one-time operation, attempting to call it more often will result in a runtime exception.

Every application intending to use the global tracer is responsible for registering it once during its initialization.

Parameters:

tracer - Tracer to use as global tracer.

Throws:

RuntimeException - if there is already a current tracer registered

isRegistered

public static boolean isRegistered()

Identify whether a Tracer has previously been registered.

This check is useful in scenarios where more than one component may be responsible for registering a tracer. For example, when using a Java Agent, it will need to determine if the application has already registered a tracer, and if not attempt to resolve and register one itself.

Returns:

Whether a tracer has been registered

buildSpan

public Tracer.SpanBuilder buildSpan(String operationName)

Description copied from interface: Tracer

Return a new SpanBuilder for a Span with the given `operationName`.

You can override the operationName later via BaseSpan.setOperationName(String).

A contrived example:

   Tracer tracer = ...

   // Note: if there is a `tracer.activeSpan()`, it will be used as the target of an implicit CHILD_OF
   // Reference for "workSpan" when `startActive()` is invoked.
   try (ActiveSpan workSpan = tracer.buildSpan("DoWork").startActive()) {
       workSpan.setTag("...", "...");
       // etc, etc
   }

   // It's also possible to create Spans manually, bypassing the ActiveSpanSource activation.
   Span http = tracer.buildSpan("HandleHTTPRequest")
                     .asChildOf(rpcSpanContext)  // an explicit parent
                     .withTag("user_agent", req.UserAgent)
                     .withTag("lucky_number", 42)
                     .startManual();
 

Specified by:

buildSpan in interface Tracer

inject

public <C> void inject(SpanContext spanContext,
                       Format<C> format,
                       C carrier)

Description copied from interface: Tracer

Inject a SpanContext into a `carrier` of a given type, presumably for propagation across process boundaries.

Example:

 Tracer tracer = ...
 Span clientSpan = ...
 TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
 tracer.inject(span.context(), Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
 

Specified by:

inject in interface Tracer

Type Parameters:

C - the carrier type, which also parametrizes the Format.

Parameters:

spanContext - the SpanContext instance to inject into the carrier

format - the Format of the carrier

carrier - the carrier for the SpanContext state. All Tracer.inject() implementations must support io.opentracing.propagation.TextMap and java.nio.ByteBuffer.

See Also:

Format, Format.Builtin

extract

public <C> SpanContext extract(Format<C> format,
                               C carrier)

Description copied from interface: Tracer

Extract a SpanContext from a `carrier` of a given type, presumably after propagation across a process boundary.

Example:

 Tracer tracer = ...
 TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
 SpanContext spanCtx = tracer.extract(Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
 ... = tracer.buildSpan('...').asChildOf(spanCtx).startActive();
 

If the span serialized state is invalid (corrupt, wrong version, etc) inside the carrier this will result in an IllegalArgumentException.

Specified by:

extract in interface Tracer

Type Parameters:

C - the carrier type, which also parametrizes the Format.

Parameters:

format - the Format of the carrier

carrier - the carrier for the SpanContext state. All Tracer.extract() implementations must support io.opentracing.propagation.TextMap and java.nio.ByteBuffer.

Returns:

the SpanContext instance holding context to create a Span.

See Also:

Format, Format.Builtin

toString

public String toString()

Overrides:

toString in class Object

activeSpan

public ActiveSpan activeSpan()

Description copied from interface: ActiveSpanSource

Return the active span. This does not affect the internal reference count for the ActiveSpan.

If there is an active span, it becomes an implicit parent of any newly-created span at Tracer.SpanBuilder.startActive() time (rather than at Tracer.buildSpan(String) time).

Specified by:

activeSpan in interface ActiveSpanSource

Returns:

the active span, or null if none could be found.

makeActive

public ActiveSpan makeActive(Span span)

Description copied from interface: ActiveSpanSource

Wrap and "make active" a Span by encapsulating it – and any active state (e.g., MDC state) in the current thread – in a new ActiveSpan.

Specified by:

makeActive in interface ActiveSpanSource

Parameters:

span - the Span to wrap in an ActiveSpan

Returns:

an ActiveSpan that encapsulates the given Span and any other ActiveSpanSource-specific context (e.g., the MDC context map)