Interface Tracer

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

  • 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

    • 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