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 Details

    • 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, 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, 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.

    • setAllAttributes

      default Span setAllAttributes(Attributes attributes)
      Sets attributes to the Span. If the Span previously contained a mapping for any of the keys, the old values are replaced by the specified values.
      Parameters:
      attributes - the attributes
      Returns:
      this.
      Since:
      1.2.0

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

    • isRecording

      boolean isRecording()
      Returns true if this Span records tracing events (e.g. addEvent(String), setAttribute(String, long)).
      Returns:
      true if this Span records tracing events.

    • storeInContext

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