Class SpanHandler
- Direct Known Subclasses:
FinishedSpanHandler
public abstract class SpanHandler extends Object
TraceContext
. Common implementations include span
reporting (ex to Zipkin) and data manipulation, such as redaction for security purposes.
Relationship to Span lifecycle
The pair ofbegin(brave.propagation.TraceContext, brave.handler.MutableSpan, brave.propagation.TraceContext)
and end(brave.propagation.TraceContext, brave.handler.MutableSpan, brave.handler.SpanHandler.Cause)
seems the same as the span lifecycle. In most cases
it will be the same, but you cannot assume this.
A TraceContext
could be recorded twice, for example, if a long operation
began, called Span.flush()
(recording 1) and later called Span.finish()
(recording 2). A TraceContext
could be abrupted by garbage collection resulting in a
SpanHandler.Cause.ABANDONED
. A user could even abandon a span without
recording anything!
Collectors that process finished spans will need to look at the {link Cause} and MutableSpan
collected. For example, SpanHandler.Cause.FINISHED
is usually a good enough heuristic to
find complete spans.
Advanced Notes
It is important to do work quickly as callbacks are run on the same thread as application
code. However, do not mutate MutableSpan
between callbacks, as it is not thread safe.
The TraceContext
and MutableSpan
parameter from begin(brave.propagation.TraceContext, brave.handler.MutableSpan, brave.propagation.TraceContext)
will be
the same reference for end(brave.propagation.TraceContext, brave.handler.MutableSpan, brave.handler.SpanHandler.Cause)
.
If caching the context or span parameters between callbacks, consider a WeakReference
to avoid holding up garbage collection.
The begin(brave.propagation.TraceContext, brave.handler.MutableSpan, brave.propagation.TraceContext)
callback primarily supports tracking of children, or partitioning of
data for backend that needs to see an entire local root.
- Since:
- 5.12
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
SpanHandler.Cause
What ended the data collection? -
Field Summary
Fields Modifier and Type Field Description static SpanHandler
NOOP
Use to avoid comparing againstnull
references. -
Constructor Summary
Constructors Constructor Description SpanHandler()
-
Method Summary
Modifier and Type Method Description boolean
begin(TraceContext context, MutableSpan span, TraceContext parent)
This is called when a span is sampled, but before it is started.boolean
end(TraceContext context, MutableSpan span, SpanHandler.Cause cause)
Called when data collection complete.boolean
handlesAbandoned()
Span.abandon()
means the data is not intended to be recorded.
-
Field Details
-
NOOP
Use to avoid comparing againstnull
references.- Since:
- 5.12
-
-
Constructor Details
-
SpanHandler
public SpanHandler()
-
-
Method Details
-
begin
This is called when a span is sampled, but before it is started.- Parameters:
context
- the trace context which isSamplingFlags.sampledLocal()
. This includes identifiers and potentiallyextra propagated data
such as baggage or extended sampling configuration.span
- a mutable object that stores data recorded with span apis. Modifications are visible to later collectors.parent
- can benull
only when the new context is a local root.- Returns:
true
retains the span, and should almost always be used.false
makes it invisible to later handlers such as Zipkin.- Since:
- 5.12
- See Also:
Tracing.Builder.alwaysSampleLocal()
,end(TraceContext, MutableSpan, Cause)
-
end
Called when data collection complete.Advanced Note
By default, this only receives callbacks when data is intended to be recorded. If you are implementing tracking betweenbegin(brave.propagation.TraceContext, brave.handler.MutableSpan, brave.propagation.TraceContext)
and here, you should consider overridinghandlesAbandoned()
so that you have parity for all cases.- Parameters:
context
- same instance as passed tobegin(brave.propagation.TraceContext, brave.handler.MutableSpan, brave.propagation.TraceContext)
span
- same instance as passed tobegin(brave.propagation.TraceContext, brave.handler.MutableSpan, brave.propagation.TraceContext)
cause
- why the data collection stopped.- Returns:
true
retains the span, and should almost always be used.false
drops the span, making it invisible to later handlers such as Zipkin.- Since:
- 5.12
- See Also:
begin(TraceContext, MutableSpan, TraceContext)
,SpanHandler.Cause
-
handlesAbandoned
public boolean handlesAbandoned()Span.abandon()
means the data is not intended to be recorded. It results in an end callback withSpanHandler.Cause.ABANDONED
.Note:
SpanHandler.Cause.ABANDONED
means the data is not intended to be recorded!
-