Package brave

Class Tracing

java.lang.Object
brave.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 Details

    • newBuilder

      public static Tracing.Builder newBuilder()

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

    • propagationFactory

      @Deprecated public abstract Propagation.Factory propagationFactory()
      Deprecated.
      Since 5.12 use propagation() as non-string keys are unsupported.

    • 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