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

  • 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 Span tag(Tag<?> tag)
      Add a tag to this span.
      Parameters:
      tag - tag to add
      Returns:
      current span

    • tag

      Span tag(String key, String value)
      Add a string tag.
      Parameters:
      key - tag key
      value - tag value
      Returns:
      current span

    • tag

      Span tag(String key, Boolean value)
      Add a boolean tag.
      Parameters:
      key - tag key
      value - tag value
      Returns:
      current span

    • tag

      Span tag(String key, Number value)
      Add a numeric tag.
      Parameters:
      key - tag key
      value - tag value
      Returns:
      current span

    • 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

    • baggage

      @Deprecated(since="4.0.5", forRemoval=true) Span baggage(String key, String value)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use baggage() and then WritableBaggage.set(String, String)}.
      Sets a baggage item in the Span (and its SpanContext) as a key/value pair.
      Parameters:
      key - String Key
      value - String Value
      Returns:
      current Span instance

    • baggage

      @Deprecated(since="4.0.5", forRemoval=true) Optional<String> baggage(String key)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use baggage() and then Baggage.get(String).
      Get Baggage Item by key.
      Parameters:
      key - String key
      Returns:
      Optional of the value of the baggage item

    • baggage

      WritableBaggage baggage()
      Returns writable baggage associated with this span.
      Returns:
      the mutable baggage instance for the span

    • 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