Package io.opentelemetry.api.trace

Interface Span

  • All Superinterfaces:
    io.opentelemetry.context.ImplicitContextKeyed
    @ThreadSafe
public interface Span
extends io.opentelemetry.context.ImplicitContextKeyed
    An interface that represents a span. It has an associated SpanContext.

    Spans are created by the SpanBuilder.startSpan() method.

    Span must be ended by calling end().

    • Method Detail

      • current

        static Span current()
        Returns the Span from the current Context, falling back to a default, no-op Span if there is no span in the current context.

      • fromContext

        static Span fromContext​(io.opentelemetry.context.Context context)
        Returns the Span from the specified Context, falling back to a default, no-op Span if there is no span in the context.

      • fromContextOrNull

        @Nullable
static Span fromContextOrNull​(io.opentelemetry.context.Context context)
        Returns the Span from the specified Context, or null if there is no span in the context.

      • getInvalid

        static Span getInvalid()
        Returns an invalid Span. An invalid Span is used when tracing is disabled, usually because there is no OpenTelemetry SDK installed.

      • wrap

        static Span wrap​(SpanContext spanContext)
        Returns a non-recording Span that holds the provided SpanContext but has no functionality. It will not be exported and all tracing operations are no-op, but it can be used to propagate a valid SpanContext downstream.

      • setAttribute

        default Span setAttribute​(String key,
                          @Nonnull
                          String value)
        Sets an attribute to the Span. If the Span previously contained a mapping for the key, the old value is replaced by the specified value.

        If a null or empty String value is passed in, the behavior is undefined, and hence strongly discouraged.

        Note: It is strongly recommended to use setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

        Parameters:
        key - the key for this attribute.
        value - the value for this attribute.
        Returns:
        this.

      • setAttribute

        default Span setAttribute​(String key,
                          long value)
        Sets an attribute to the Span. If the Span previously contained a mapping for the key, the old value is replaced by the specified value.

        Note: It is strongly recommended to use setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

        Parameters:
        key - the key for this attribute.
        value - the value for this attribute.
        Returns:
        this.

      • setAttribute

        default Span setAttribute​(String key,
                          double value)
        Sets an attribute to the Span. If the Span previously contained a mapping for the key, the old value is replaced by the specified value.

        Note: It is strongly recommended to use setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

        Parameters:
        key - the key for this attribute.
        value - the value for this attribute.
        Returns:
        this.

      • setAttribute

        default Span setAttribute​(String key,
                          boolean value)
        Sets an attribute to the Span. If the Span previously contained a mapping for the key, the old value is replaced by the specified value.

        Note: It is strongly recommended to use setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

        Parameters:
        key - the key for this attribute.
        value - the value for this attribute.
        Returns:
        this.

      • setAttribute

        <T> Span setAttribute​(AttributeKey<T> key,
                      @Nonnull
                      T value)
        Sets an attribute to the Span. If the Span previously contained a mapping for the key, the old value is replaced by the specified value.

        Note: the behavior of null values is undefined, and hence strongly discouraged.

        Parameters:
        key - the key for this attribute.
        value - the value for this attribute.
        Returns:
        this.

      • setAttribute

        default Span setAttribute​(AttributeKey<Long> key,
                          int value)
        Sets an attribute to the Span. If the Span previously contained a mapping for the key, the old value is replaced by the specified value.
        Parameters:
        key - the key for this attribute.
        value - the value for this attribute.
        Returns:
        this.

      • addEvent

        default Span addEvent​(String name)
        Adds an event to the Span. The timestamp of the event will be the current time.
        Parameters:
        name - the name of the event.
        Returns:
        this.

      • addEvent

        default Span addEvent​(String name,
                      long timestamp,
                      TimeUnit unit)
        Adds an event to the Span with the given timestamp, as nanos since epoch. Note, this timestamp is not the same as System.nanoTime() but may be computed using it, for example, by taking a difference of readings from System.nanoTime() and adding to the span start time.

        When possible, it is preferred to use addEvent(String) at the time the event occurred.

        Parameters:
        name - the name of the event.
        timestamp - the explicit event timestamp since epoch.
        unit - the unit of the timestamp
        Returns:
        this.

      • addEvent

        default Span addEvent​(String name,
                      Instant timestamp)
        Adds an event to the Span with the given timestamp, as nanos since epoch. Note, this timestamp is not the same as System.nanoTime() but may be computed using it, for example, by taking a difference of readings from System.nanoTime() and adding to the span start time.

        When possible, it is preferred to use addEvent(String) at the time the event occurred.

        Parameters:
        name - the name of the event.
        timestamp - the explicit event timestamp since epoch.
        Returns:
        this.

      • addEvent

        Span addEvent​(String name,
              Attributes attributes)
        Adds an event to the Span with the given Attributes. The timestamp of the event will be the current time.
        Parameters:
        name - the name of the event.
        attributes - the attributes that will be added; these are associated with this event, not the Span as for setAttribute().
        Returns:
        this.

      • addEvent

        Span addEvent​(String name,
              Attributes attributes,
              long timestamp,
              TimeUnit unit)
        Adds an event to the Span with the given Attributes and timestamp. Note, this timestamp is not the same as System.nanoTime() but may be computed using it, for example, by taking a difference of readings from System.nanoTime() and adding to the span start time.

        When possible, it is preferred to use addEvent(String) at the time the event occurred.

        Parameters:
        name - the name of the event.
        attributes - the attributes that will be added; these are associated with this event, not the Span as for setAttribute().
        timestamp - the explicit event timestamp since epoch.
        unit - the unit of the timestamp
        Returns:
        this.

      • addEvent

        default Span addEvent​(String name,
                      Attributes attributes,
                      Instant timestamp)
        Adds an event to the Span with the given Attributes and timestamp. Note, this timestamp is not the same as System.nanoTime() but may be computed using it, for example, by taking a difference of readings from System.nanoTime() and adding to the span start time.

        When possible, it is preferred to use addEvent(String) at the time the event occurred.

        Parameters:
        name - the name of the event.
        attributes - the attributes that will be added; these are associated with this event, not the Span as for setAttribute().
        timestamp - the explicit event timestamp since epoch.
        Returns:
        this.

      • setStatus

        default Span setStatus​(StatusCode statusCode)
        Sets the status to the Span.

        If used, this will override the default Span status. Default status code is StatusCode.UNSET.

        Only the value of the last call will be recorded, and implementations are free to ignore previous calls.

        Parameters:
        statusCode - the StatusCode to set.
        Returns:
        this.

      • setStatus

        Span setStatus​(StatusCode statusCode,
               String description)
        Sets the status to the Span.

        If used, this will override the default Span status. Default status code is StatusCode.UNSET.

        Only the value of the last call will be recorded, and implementations are free to ignore previous calls.

        Parameters:
        statusCode - the StatusCode to set.
        description - the description of the Status.
        Returns:
        this.

      • recordException

        default Span recordException​(Throwable exception)
        Records information about the Throwable to the Span.

        Note that the EXCEPTION_ESCAPED value from the Semantic Conventions cannot be determined by this function. You should record this attribute manually using recordException(Throwable, Attributes) if you know that an exception is escaping.

        Parameters:
        exception - the Throwable to record.
        Returns:
        this.

      • recordException

        Span recordException​(Throwable exception,
                     Attributes additionalAttributes)
        Records information about the Throwable to the Span.
        Parameters:
        exception - the Throwable to record.
        additionalAttributes - the additional Attributes to record.
        Returns:
        this.

      • updateName

        Span updateName​(String name)
        Updates the Span name.

        If used, this will override the name provided via Span.Builder.

        Upon this update, any sampling behavior based on Span name will depend on the implementation.

        Parameters:
        name - the Span name.
        Returns:
        this.

      • end

        void end()
        Marks the end of Span execution.

        Only the timing of the first end call for a given Span will be recorded, and implementations are free to ignore all further calls.

      • end

        void end​(long timestamp,
         TimeUnit unit)
        Marks the end of Span execution with the specified timestamp.

        Only the timing of the first end call for a given Span will be recorded, and implementations are free to ignore all further calls.

        Use this method for specifying explicit end options, such as end Timestamp. When no explicit values are required, use end().

        Parameters:
        timestamp - the explicit timestamp from the epoch, for this Span. 0 indicates current time should be used.
        unit - the unit of the timestamp

      • end

        default void end​(Instant timestamp)
        Marks the end of Span execution with the specified timestamp.

        Only the timing of the first end call for a given Span will be recorded, and implementations are free to ignore all further calls.

        Use this method for specifying explicit end options, such as end Timestamp. When no explicit values are required, use end().

        Parameters:
        timestamp - the explicit timestamp from the epoch, for this Span. 0 indicates current time should be used.

      • getSpanContext

        SpanContext getSpanContext()
        Returns the SpanContext associated with this Span.
        Returns:
        the SpanContext associated with this Span.

      • storeInContext

        default io.opentelemetry.context.Context storeInContext​(io.opentelemetry.context.Context context)
        Specified by:
        storeInContext in interface io.opentelemetry.context.ImplicitContextKeyed