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 span (finish processing) using current timestamp.

    • end

      default void end(Instant timestamp)
      End this span using the provided timestamp.
      Parameters:
      timestamp - end time for the span

    • end

      default void end(Instant timestamp, Throwable t)
      End this span with an error status using the provided ending time and throwable. Sets the span status to Span.Status.ERROR and adds appropriate tags and events to report the error.
      Parameters:
      timestamp - end time for the span
      t - throwable causing the span to end

    • 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