Package brave.handler

Class SpanHandler

java.lang.Object

brave.handler.SpanHandler

Direct Known Subclasses:

FinishedSpanHandler

public abstract class SpanHandler
extends Object

This tracks one recording of a TraceContext. Common implementations include span reporting (ex to Zipkin) and data manipulation, such as redaction for security purposes.

Relationship to Span lifecycle

The pair of begin(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 against null 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.

Methods inherited from class java.lang.Object

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

Field Details

NOOP

public static final SpanHandler NOOP

Use to avoid comparing against null references.

Since:

5.12

Constructor Details

SpanHandler

public SpanHandler()

Method Details

begin

public boolean begin(TraceContext context, MutableSpan span, @Nullable TraceContext parent)

This is called when a span is sampled, but before it is started.

Parameters:

context - the trace context which is SamplingFlags.sampledLocal(). This includes identifiers and potentially extra 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 be null 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

public boolean end(TraceContext context, MutableSpan span, SpanHandler.Cause cause)

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 between begin(brave.propagation.TraceContext, brave.handler.MutableSpan, brave.propagation.TraceContext) and here, you should consider overriding handlesAbandoned() so that you have parity for all cases.

Parameters:

context - same instance as passed to begin(brave.propagation.TraceContext, brave.handler.MutableSpan, brave.propagation.TraceContext)

span - same instance as passed to begin(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 with SpanHandler.Cause.ABANDONED.

Note: SpanHandler.Cause.ABANDONED means the data is not intended to be recorded!