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

Interface Span

public interface Span
Tracing span. A span is started by Span.Builder.start() and ended by either end() or end(Throwable). You can obtain SpanContext from context(). Span is the base reporting unit of tracing. Spans can have a parent (Span.Builder.parent(SpanContext), you can add tag(Tag) to it, and you can log addEvent(String, java.util.Map).

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Span.Builder<B extends Span.Builder<B>>
    Fluent API builder to create a new Span.
    static enum 
    Span.Kind
    Span kind.
    static enum 
    Span.Status
    Span status.

  • Method Summary

    Modifier and Type
    Method
    Description
    Scope
    activate()
    Make this span the current active span.
    default void
    addEvent(String logMessage)
    Add a new event to this span.
    void
    addEvent(String name, Map<String,?> attributes)
    Add an event to this span.
    SpanContext
    context()
    Span context can be used to configure a span parent, as is used when a span reference is needed, without the possibility to end such a span.
    static Optional<Span>
    current()
    Provide current span if one is available.
    void
    end()
    End this tag (finish processing) using current timestamp.
    void
    end(Throwable t)
    End with error status and an exception.
    void
    status(Span.Status status)
    Span status, mostly used to configure Span.Status.ERROR.
    default void
    tag(Tag<?> tag)
    Add a tag to this span.
    void
    tag(String key, Boolean value)
    Add a boolean tag.
    void
    tag(String key, Number value)
    Add a numeric tag.
    void
    tag(String key, String value)
    Add a string tag.
    default <T> T
    unwrap(Class<T> spanClass)
    Access the underlying span by specific type.

  • Method Details

    • current

      static Optional<Span> current()
      Provide current span if one is available. This is using a thread local, so it may provide unexpected results in a reactive environment. Please use request methods to obtain request span in Reactive Web Server.
      Returns:
      current span or empty optional if there is no current span
      See Also:

    • tag

      default void tag(Tag<?> tag)
      Add a tag to this span.
      Parameters:
      tag - tag to add

    • tag

      void tag(String key, String value)
      Add a string tag.
      Parameters:
      key - tag key
      value - tag value

    • tag

      void tag(String key, Boolean value)
      Add a boolean tag.
      Parameters:
      key - tag key
      value - tag value

    • tag

      void tag(String key, Number value)
      Add a numeric tag.
      Parameters:
      key - tag key
      value - tag value

    • status

      void status(Span.Status status)
      Span status, mostly used to configure Span.Status.ERROR.
      Parameters:
      status - status to set

    • context

      SpanContext context()
      Span context can be used to configure a span parent, as is used when a span reference is needed, without the possibility to end such a span.
      Returns:
      context of this span

    • addEvent

      void addEvent(String name, Map<String,?> attributes)
      Add an event to this span.
      Parameters:
      name - name of the event
      attributes - event attributes to be recorded

    • end

      void end()
      End this tag (finish processing) using current timestamp.

    • end

      void end(Throwable t)
      End with error status and an exception. Configures status to Span.Status.ERROR, and adds appropriate tags and events to report this exception.
      Parameters:
      t - throwable that caused the error status

    • activate

      Scope activate()
      Make this span the current active span. This is expected to use thread locals and as such is not suitable for reactive environment.
      Returns:
      current scope

    • addEvent

      default void addEvent(String logMessage)
      Add a new event to this span.
      Parameters:
      logMessage - message to log

    • unwrap

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