io.opentracing.util

Class GlobalTracer

java.lang.Object

io.opentracing.util.GlobalTracer

All Implemented Interfaces:

Tracer, Closeable, AutoCloseable

public final class GlobalTracer
extends Object
implements Tracer

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

The register method should only be called once during the application initialization phase.
If the registerIfAbsent(Tracer) 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.Tracer

Tracer.SpanBuilder

Method Summary

Modifier and Type	Method and Description
Scope	activateSpan(Span span)
Span	activeSpan()
Tracer.SpanBuilder	buildSpan(String operationName)
void	close()
<C> SpanContext	extract(Format<C> format, C carrier)
static Tracer	get() Returns the constant GlobalTracer.
<C> void	inject(SpanContext spanContext, Format<C> format, C carrier)
static boolean	isRegistered() Identify whether a Tracer has previously been registered.
static void	register(Tracer tracer) Deprecated. Please use registerIfAbsent(Tracer) or registerIfAbsent(Callable) instead.
static boolean	registerIfAbsent(Callable<Tracer> provider) Register a Tracer to back the behaviour of the get().
static boolean	registerIfAbsent(Tracer tracer) Register a Tracer to back the behaviour of the get().
ScopeManager	scopeManager()
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:

and {@link #registerIfAbsent(Callable)}

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

registerIfAbsent

public static boolean registerIfAbsent(Callable<Tracer> provider)

Register a Tracer to back the behaviour of the get().

The tracer is provided through a Callable that will only be called if the global tracer is absent. Registration is a one-time operation. Once a tracer has been registered, all attempts at re-registering will return false.

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

Parameters:

provider - Provider for the tracer to use as global tracer.

Returns:

true if the provided tracer was registered as a result of this call, false otherwise.

Throws:

NullPointerException - if the tracer provider is null or provides a null Tracer.

RuntimeException - any exception thrown by the provider gets rethrown, checked exceptions will be wrapped into appropriate runtime exceptions.

registerIfAbsent

public static boolean registerIfAbsent(Tracer tracer)

Register a Tracer to back the behaviour of the get().

Registration is a one-time operation. Once a tracer has been registered, all attempts at re-registering will return false. Use registerIfAbsent(Callable) for lazy initiation to avoid multiple instantiations of tracer.

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

Parameters:

tracer - tracer to be registered.

Returns:

true if the provided tracer was registered as a result of this call, false otherwise.

Throws:

NullPointerException - if the tracer null.

RuntimeException - any exception thrown by the provider gets rethrown, checked exceptions will be wrapped into appropriate runtime exceptions.

See Also:

registerIfAbsent(Callable)

register

@Deprecated
public static void register(Tracer tracer)

Deprecated. Please use registerIfAbsent(Tracer) or registerIfAbsent(Callable) instead.

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

See Also:

registerIfAbsent(Callable)

scopeManager

public ScopeManager scopeManager()

Specified by:

scopeManager in interface Tracer

buildSpan

public Tracer.SpanBuilder buildSpan(String operationName)

Specified by:

buildSpan in interface Tracer

inject

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

Specified by:

inject in interface Tracer

extract

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

Specified by:

extract in interface Tracer

activeSpan

public Span activeSpan()

Specified by:

activeSpan in interface Tracer

activateSpan

public Scope activateSpan(Span span)

Specified by:

activateSpan in interface Tracer

close

public void close()

Specified by:

close in interface Tracer

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

toString

public String toString()

Overrides:

toString in class Object