Package brave.handler

Enum SpanHandler.Cause

java.lang.Object
java.lang.Enum<SpanHandler.Cause>
brave.handler.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>
What ended the data collection?
Since:
5.12

  • Enum Constant Details

    • ABANDONED

      public static final SpanHandler.Cause ABANDONED
      Called on Span.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

      public static final SpanHandler.Cause FINISHED
      Called on Span.finish() and is the simplest cause to reason with. When MutableSpan.startTimestamp() is present, you can assume with high confidence you have all recorded data for this span.

    • FLUSHED

      public static final SpanHandler.Cause FLUSHED
      Called on Span.flush().

      Even though the span here is incomplete (missing MutableSpan.finishTimestamp(), it is reported to the tracing system unless a SpanHandler returns false.

    • ORPHANED

      public static final SpanHandler.Cause 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) or Span.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 calling Span.finish(), or calling Tracer.nextSpan() yet never using the result. To track down bugs like this, set the logger Tracer 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 to SpanHandler.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 a MutableSpan.startTimestamp() for example.

  • Method Details

    • values

      public static SpanHandler.Cause[] 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

      public static SpanHandler.Cause valueOf​(String name)
      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 name
      NullPointerException - if the argument is null