Module brave
Package brave.handler

Class FinishedSpanHandler

  • Direct Known Subclasses:
    ZipkinFinishedSpanHandler
    public abstract class FinishedSpanHandler
extends java.lang.Object
    Triggered on each finished span except when spans that are no-op.

    Sampled spans hit this stage before reporting to Zipkin. This means changes to the mutable span will reflect in reported data.

    When Zipkin's reporter is Reporter.NOOP or the context is unsampled, this will still receive spans where SamplingFlags.sampledLocal() is true.

    See Also:
    alwaysSampleLocal()

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static FinishedSpanHandler NOOP
      Use to avoid comparing against null references

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      boolean alwaysSampleLocal()
      When true, all spans become real spans even if they aren't sampled remotely.
      abstract boolean handle​(TraceContext context, MutableSpan span)
      This is invoked after a span is finished, allowing data to be modified or reported out of process.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • NOOP

        public static final FinishedSpanHandler NOOP
        Use to avoid comparing against null references

    • Constructor Detail

      • FinishedSpanHandler

        public FinishedSpanHandler()

    • Method Detail

      • handle

        public abstract boolean handle​(TraceContext context,
                               MutableSpan span)
        This is invoked after a span is finished, allowing data to be modified or reported out of process. A return value of false means the span should be dropped completely from the stream.

        Changes to the input span are visible by later finished span handlers. One reason to change the input is to align tags, so that correlation occurs. For example, some may clean the tag "http.path" knowing downstream handlers such as zipkin reporting have the same value.

        Returning false is the same effect as if Span.abandon() was called. Implementations should be careful when returning false as it can lead to broken traces. Acceptable use cases are when the span is a leaf, for example a client call to an uninstrumented database, or a server call which is known to terminate in-process (for example, health-checks). Prefer an instrumentation policy approach to this mechanism as it results in less overhead.

        Implementations should not hold a reference to it after this method returns. This is to allow object recycling.

        Parameters:
        context - the trace context which is SamplingFlags.sampled() or SamplingFlags.sampledLocal(). This includes identifiers and potentially extra propagated data such as extended sampling configuration.
        span - a mutable object including all data recorded with span apis. Modifications are visible to later handlers, including Zipkin.
        Returns:
        true retains the span, and should almost always be used. false drops the span, making it invisible to later handlers such as Zipkin.

      • alwaysSampleLocal

        public boolean alwaysSampleLocal()
        When true, all spans become real spans even if they aren't sampled remotely. This allows firehose instances (such as metrics) to consider attributes that are not always visible before-the-fact, such as http paths. Defaults to false and affects SamplingFlags.sampledLocal().
        See Also:
        handle(TraceContext, MutableSpan)