Package brave

Class Tracing

  • All Implemented Interfaces:
    Closeable, AutoCloseable
    public abstract class Tracing
extends Object
implements Closeable
    This provides utilities needed for trace instrumentation. For example, a Tracer.

    Instances built via newBuilder() are registered automatically such that statically configured instrumentation like JDBC drivers can use current().

    This type can be extended so that the object graph can be built differently or overridden, for example via spring or when mocking.

    • Method Detail

      • tracer

        public abstract Tracer tracer()
        All tracing commands start with a Span. Use a tracer to create spans.

      • propagation

        public abstract Propagation<String> propagation()
        When a trace leaves the process, it needs to be propagated, usually via headers. This utility is used to inject or extract a trace context from remote requests.

      • sampler

        public abstract Sampler sampler()
        Sampler is responsible for deciding if a particular trace should be "sampled", i.e. whether the overhead of tracing will occur and/or if a trace will be reported to Zipkin.
        See Also:
        for temporary overrides

      • currentTraceContext

        public abstract CurrentTraceContext currentTraceContext()
        This supports in-process propagation, typically across thread boundaries. This includes utilities for concurrent types like ExecutorService.

      • clock

        public final Clock clock​(TraceContext context)
        This exposes the microsecond clock used by operations such as Span.finish(). This is helpful when you want to time things manually. Notably, this clock will be coherent for all child spans in this trace (that use this tracing component). For example, NTP or system clock changes will not affect the result.
        Parameters:
        context - references a potentially unstarted span you'd like a clock correlated with

      • errorParser

        @Deprecated
public abstract ErrorParser errorParser()
        Deprecated.
        This is only used in Zipkin reporting. Since 5.12, use ZipkinSpanHandler.Builder.errorTag(Tag)

      • current

        @Nullable
public static Tracing current()
        Returns the most recently created tracing component iff it hasn't been closed. null otherwise.

        This object should not be cached.

      • currentTracer

        @Nullable
public static Tracer currentTracer()
        Returns the most recently created tracer if its component hasn't been closed. null otherwise.

        This object should not be cached.

      • isNoop

        public abstract boolean isNoop()
        When true, no recording is done and nothing is reported to zipkin. However, trace context is still injected into outgoing requests.
        See Also:
        Span.isNoop()

      • setNoop

        public abstract void setNoop​(boolean noop)
        Set true to drop data and only return noop spans regardless of sampling policy. This allows operators to stop tracing in risk scenarios.
        See Also:
        isNoop()

      • close

        public abstract void close()
        Ensures this component can be garbage collected, by making it not current()
        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Closeable