Enum SpanHandler.Cause
- All Implemented Interfaces:
Serializable
,Comparable<SpanHandler.Cause>
,java.lang.constant.Constable
- Enclosing class:
- SpanHandler
public static enum SpanHandler.Cause extends Enum<SpanHandler.Cause>
- Since:
- 5.12
-
Nested Class Summary
-
Enum Constant Summary
Enum Constants Enum Constant Description ABANDONED
Called onSpan.abandon()
.FINISHED
Called onSpan.finish()
and is the simplest cause to reason with.FLUSHED
Called onSpan.flush()
.ORPHANED
Called when the trace context was garbage collected prior to completion. -
Method Summary
Modifier and Type Method Description static SpanHandler.Cause
valueOf(String name)
Returns the enum constant of this type with the specified name.static SpanHandler.Cause[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
Enum Constant Details
-
ABANDONED
Called onSpan.abandon()
.This is useful when counting children. Decrement your counter when this occurs as the span will not be reported.
Note:Abandoned spans should be ignored as they aren't indicative of an error. Some instrumentation speculatively create a span for possible outcomes such as retry.
-
FINISHED
Called onSpan.finish()
and is the simplest cause to reason with. WhenMutableSpan.startTimestamp()
is present, you can assume with high confidence you have all recorded data for this span. -
FLUSHED
Called onSpan.flush()
.Even though the span here is incomplete (missing
MutableSpan.finishTimestamp()
, it is reported to the tracing system unless aSpanHandler
returns false. -
ORPHANED
Called when the trace context was garbage collected prior to completion.Normally,
SpanHandler.end(TraceContext, MutableSpan, Cause)
is only called upon explicit termination of a span:Span.finish()
,Span.finish(long)
orSpan.flush()
. Upon this cause, the callback will also receive data orphaned due to spans being never terminated or data added after termination.Note: If you are doing redaction, you should redact for all causes, not just
FINISHED
, as orphans may have sensitive data also.What is an orphaned span?
An orphan is when data remains associated with a span when it is garbage collected. This is almost always a bug. For example, calling
Span.tag(String, String)
after callingSpan.finish()
, or callingTracer.nextSpan()
yet never using the result. To track down bugs like this, set the loggerTracer
to FINE level.Why handle orphaned spans?
Use cases for handling orphans logging a different way than default, or incrementing bug counters. For example, you could use the same credit card cleaner here as you do on the success path.
What shouldn't handle orphaned spans?
As this is related to bugs, no assumptions can be made about span count etc. For example, one span context can result in many calls to this handler, unrelated to the actual operation performed. Handlers that redact or clean data work for normal spans and orphans. However, aggregation handlers, such as dependency linkers or success/fail counters, can create problems if used against orphaned spans.
Implementation
The
MutableSpan
parameter toSpanHandler.end(TraceContext, MutableSpan, Cause)
includes data configured by default and any state that was was orphaned (ex a tag). You cannot assume the span has aMutableSpan.startTimestamp()
for example.
-
-
Method Details
-
values
Returns an array containing the constants of this enum type, in the order they are declared.- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
valueOf
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
IllegalArgumentException
- if this enum type has no constant with the specified nameNullPointerException
- if the argument is null
-