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.
ActiveSpan
s are created via Tracer.SpanBuilder.startActive()
or, less commonly,
ActiveSpanSource.makeActive(io.opentracing.Span)
. Per the above, they can be capture()
ed as
ActiveSpan.Continuation
s, then re-ActiveSpan.Continuation.activate()
d later.
NOTE: ActiveSpan
extends Closeable
rather than AutoCloseable
in order to preserve support
for JDK1.6.
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. |
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 . |
context, getBaggageItem, log, log, log, log, log, log, setBaggageItem, setOperationName, setTag, setTag, setTag
void deactivate()
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.
void close()
deactivate()
that can be used in try-with-resources blocks.close
in interface AutoCloseable
close
in interface Closeable
ActiveSpan.Continuation capture()
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.
ActiveSpan.Continuation
to ActiveSpan.Continuation.activate()
at the appropriate time.Copyright © 2016–2017 OpenTracing. All rights reserved.