Module io.helidon.tracing
Package io.helidon.tracing

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
    enabled()
    Whether this tracer is enabled or not.
    Optional<SpanContext>
    extract(HeaderProvider headersProvider)
    Extract parent span context from inbound request, such as from HTTP headers.
    static Tracer
    global()
    Deprecated, for removal: This API element is subject to removal in a future version.
    we are switching to service registry for global instances, kindly use Services.get(Class) instead
    static void
    global(Tracer tracer)
    Deprecated, for removal: This API element is subject to removal in a future version.
    we are switching to Service registry for global instances, kindly use Services.set(Class, Object[]) before using tracing instead of calling this method
    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
    noOp()
    Create a no-op tracer.
    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.
    Span.Builder<?>
    spanBuilder(String name)
    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

      @Deprecated(forRemoval=true, since="4.4.0") static Tracer global()
      Deprecated, for removal: This API element is subject to removal in a future version.
      we are switching to service registry for global instances, kindly use Services.get(Class) instead
      Get the currently registered global tracer.
      Returns:
      global tracer

    • global

      @Deprecated(forRemoval=true, since="4.4.0") static void global(Tracer tracer)
      Deprecated, for removal: This API element is subject to removal in a future version.
      we are switching to Service registry for global instances, kindly use Services.set(Class, Object[]) before using tracing instead of calling this method
      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