Package brave.handler

Enum SpanHandler.Cause

    • Enum Constant Detail

      • 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.

      • 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 Detail

      • values

        public static SpanHandler.Cause[] values()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows: 
        for (SpanHandler.Cause c : SpanHandler.Cause.values())
    System.out.println(c);
        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