Interface Tracer


public interface Tracer
Tracer abstraction. Tracer is the central point that collects tracing spans, and (probably) pushes them to backend.
  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    Whether this tracer is enabled or not.
    extract(HeaderProvider headersProvider)
    Extract parent span context from inbound request, such as from HTTP headers.
    static Tracer
    Get the currently registered global tracer.
    static void
    global(Tracer tracer)
    Register a global tracer, behavior depends on implementation.
    void
    inject(SpanContext spanContext, HeaderProvider inboundHeadersProvider, HeaderConsumer outboundHeadersConsumer)
    Inject current span as a parent for outbound request, such as when invoking HTTP request from a client.
    static Tracer
    Create a no-op tracer.
    Registers with the tracer a lifecycle event listener to receive events from span builders, spans, and scopes derived from this tracer.
    A new span builder to construct Span.
    default <T> T
    unwrap(Class<T> tracerClass)
    Access the underlying tracer by specific type.
  • Method Details

    • noOp

      static Tracer noOp()
      Create a no-op tracer. All spans created from this tracer are not doing anything.
      Returns:
      no-op tracer
    • global

      static Tracer global()
      Get the currently registered global tracer.
      Returns:
      global tracer
    • global

      static void global(Tracer tracer)
      Register a global tracer, behavior depends on implementation.
      Parameters:
      tracer - tracer to use as a global tracer
    • enabled

      boolean enabled()
      Whether this tracer is enabled or not. A no op tracer is disabled.
      Returns:
      true if this tracer is enabled
    • spanBuilder

      Span.Builder<?> spanBuilder(String name)
      A new span builder to construct Span.
      Parameters:
      name - name of the operation
      Returns:
      a new span builder
    • extract

      Optional<SpanContext> extract(HeaderProvider headersProvider)
      Extract parent span context from inbound request, such as from HTTP headers.
      Parameters:
      headersProvider - provider of headers
      Returns:
      span context of inbound parent span, or empty optional if no span context can be found
    • inject

      void inject(SpanContext spanContext, HeaderProvider inboundHeadersProvider, HeaderConsumer outboundHeadersConsumer)
      Inject current span as a parent for outbound request, such as when invoking HTTP request from a client.
      Parameters:
      spanContext - current span context
      inboundHeadersProvider - provider of inbound headers, may be HeaderProvider.empty() or headers from original request (if any)
      outboundHeadersConsumer - consumer of headers that should be propagated to remote endpoint
    • unwrap

      default <T> T unwrap(Class<T> tracerClass)
      Access the underlying tracer by specific type. This is a dangerous operation that will succeed only if the tracer is of expected type. This practically removes abstraction capabilities of this API.
      Type Parameters:
      T - type of the tracer
      Parameters:
      tracerClass - type to access
      Returns:
      instance of the tracer
      Throws:
      IllegalArgumentException - in case the tracer cannot provide the expected type
    • register

      Tracer register(SpanListener listener)
      Registers with the tracer a lifecycle event listener to receive events from span builders, spans, and scopes derived from this tracer.
      Parameters:
      listener - the SpanListener to register
      Returns:
      the updated Tracer