io.opentracing

Interface ActiveSpan

All Superinterfaces:

AutoCloseable, BaseSpan<ActiveSpan>, Closeable

public interface ActiveSpan
extends Closeable, BaseSpan<ActiveSpan>

ActiveSpan inherits all of the OpenTracing functionality in BaseSpan and layers on in-process propagation capabilities.

In any given thread there is at most one "active" span primarily responsible for the work accomplished by the surrounding application code. That ActiveSpan may be accessed via the ActiveSpanSource.activeSpan() method. If the application needs to defer work that should be part of the same Span, the Source provides a capture() method that returns a ActiveSpan.Continuation; this continuation may be used to re-activate and continue the Span in that other asynchronous executor and/or thread.

ActiveSpans are created via Tracer.SpanBuilder.startActive() or, less commonly, ActiveSpanSource.makeActive(io.opentracing.Span). Per the above, they can be capture()ed as ActiveSpan.Continuations, then re-ActiveSpan.Continuation.activate()d later.

NOTE: ActiveSpan extends Closeable rather than AutoCloseable in order to preserve support for JDK1.6.

See Also:

Tracer.SpanBuilder.startActive(), ActiveSpan.Continuation.activate(), ActiveSpanSource, BaseSpan, Span

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ActiveSpan.Continuation A ActiveSpan.Continuation can be used once to activate a Span along with any non-OpenTracing execution context (e.g., MDC), then deactivate when processing activity moves on to another Span.

Method Summary

Modifier and Type	Method and Description
ActiveSpan.Continuation	capture() "Capture" a new ActiveSpan.Continuation associated with this ActiveSpan and Span, as well as any 3rd-party execution context of interest.
void	close() A synonym for deactivate() that can be used in try-with-resources blocks.
void	deactivate() Mark the end of the active period for the current thread and ActiveSpan.

Methods inherited from interface io.opentracing.BaseSpan

context, getBaggageItem, log, log, log, log, log, log, setBaggageItem, setOperationName, setTag, setTag, setTag

Method Detail

deactivate

void deactivate()

Mark the end of the active period for the current thread and ActiveSpan. When the last ActiveSpan is deactivated for a given Span, it is automatically Span.finish()ed.

NOTE: Calling deactivate() more than once on a single ActiveSpan instance leads to undefined behavior.

See Also:

{@link ActiveSpan}s are auto-closeable and may be used in try-with-resources blocks

close

void close()

A synonym for deactivate() that can be used in try-with-resources blocks.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

capture

ActiveSpan.Continuation capture()

"Capture" a new ActiveSpan.Continuation associated with this ActiveSpan and Span, as well as any 3rd-party execution context of interest. The ActiveSpan.Continuation may be used as data in a closure or callback function where the ActiveSpan may be resumed and reactivated.

IMPORTANT: the caller MUST ActiveSpan.Continuation.activate() and deactivate() the returned ActiveSpan.Continuation or the associated Span will never automatically Span.finish(). That is, calling capture() increments a refcount that must be decremented somewhere else.

The associated Span will not Span.finish() while a ActiveSpan.Continuation is outstanding; in this way, it provides a reference/pin just like an ActiveSpan does.

Returns:

a new ActiveSpan.Continuation to ActiveSpan.Continuation.activate() at the appropriate time.