Class SdkSpan

java.lang.Object
io.opentelemetry.sdk.trace.SdkSpan
All Implemented Interfaces:
Span, ImplicitContextKeyed, ReadableSpan, ReadWriteSpan
@ThreadSafe final class SdkSpan extends Object implements ReadWriteSpan
Implementation for the Span class that records trace events.

  • Field Details

  • Constructor Details

  • Method Details

    • startSpan

      static SdkSpan startSpan(SpanContext context, String name, InstrumentationScopeInfo instrumentationScopeInfo, SpanKind kind, Span parentSpan, Context parentContext, SpanLimits spanLimits, SpanProcessor spanProcessor, Clock tracerClock, Resource resource, @Nullable AttributesMap attributes, @Nullable List<LinkData> links, int totalRecordedLinks, long userStartEpochNanos)
      Creates and starts a span with the given configuration.
      Parameters:
      context - supplies the trace_id and span_id for the newly started span.
      name - the displayed name for the new span.
      kind - the span kind.
      parentSpan - the parent span, or Span.getInvalid() if this span is a root span.
      spanLimits - limits applied to this span.
      spanProcessor - handler called when the span starts and ends.
      tracerClock - the tracer's clock
      resource - the resource associated with this span.
      attributes - the attributes set during span creation.
      links - the links set during span creation, may be truncated. The list MUST be immutable.
      Returns:
      a new and started span.

    • toSpanData

      public SpanData toSpanData()
      Description copied from interface: ReadableSpan
      This converts this instance into an immutable SpanData instance, for use in export.
      Specified by:
      toSpanData in interface ReadableSpan
      Returns:
      an immutable SpanData instance.

    • getAttribute

      @Nullable public <T> T getAttribute(AttributeKey<T> key)
      Description copied from interface: ReadableSpan
      Returns the value for the given AttributeKey, or null if not found.

      The attribute values can be changed during the lifetime of the Span by using Span.setAttribute(String, String)} so this value cannot be cached.

      Note: the implementation of this method performs locking to ensure thread-safe behavior.

      Specified by:
      getAttribute in interface ReadableSpan
      Returns:
      the value for the given AttributeKey, or null if not found.

    • getAttributes

      public Attributes getAttributes()
      Description copied from interface: ReadableSpan
      Returns the Span attributes.

      Attributes can be changed during the lifetime of the Span by using Span.setAttribute(String, String)} so this value cannot be cached.

      Note: the implementation of this method performs locking and returns an immutable copy to ensure thread-safe behavior. If you only need a single attribute it is better to call ReadableSpan.getAttribute(AttributeKey).

      Specified by:
      getAttributes in interface ReadableSpan
      Returns:
      the Span attributes, or Attributes.empty() if the span has no attributes.

    • hasEnded

      public boolean hasEnded()
      Description copied from interface: ReadableSpan
      Returns whether this Span has already been ended.

      Note: the implementation of this method performs locking to ensure thread-safe behavior.

      Specified by:
      hasEnded in interface ReadableSpan
      Returns:
      true if the span has already been ended, false if not.

    • getSpanContext

      public SpanContext getSpanContext()
      Description copied from interface: Span
      Returns the SpanContext associated with this Span.
      Specified by:
      getSpanContext in interface ReadableSpan
      Specified by:
      getSpanContext in interface Span
      Returns:
      the SpanContext associated with this Span.

    • getParentSpanContext

      public SpanContext getParentSpanContext()
      Description copied from interface: ReadableSpan
      Returns the parent SpanContext of the Span, or SpanContext.getInvalid() if this is a root span.
      Specified by:
      getParentSpanContext in interface ReadableSpan
      Returns:
      the parent SpanContext of the Span

    • getName

      public String getName()
      Returns the name of the Span.
      Specified by:
      getName in interface ReadableSpan
      Returns:
      the name of the Span.

    • getInstrumentationLibraryInfo

      @Deprecated public InstrumentationLibraryInfo getInstrumentationLibraryInfo()
      Deprecated.
      Description copied from interface: ReadableSpan
      Returns the instrumentation library specified when creating the tracer which produced this span.
      Specified by:
      getInstrumentationLibraryInfo in interface ReadableSpan
      Returns:
      an instance of InstrumentationLibraryInfo describing the instrumentation library

    • getInstrumentationScopeInfo

      public InstrumentationScopeInfo getInstrumentationScopeInfo()
      Description copied from interface: ReadableSpan
      Returns the instrumentation scope specified when creating the tracer which produced this span.
      Specified by:
      getInstrumentationScopeInfo in interface ReadableSpan
      Returns:
      an instance of InstrumentationScopeInfo describing the instrumentation scope

    • getLatencyNanos

      public long getLatencyNanos()
      Returns the latency of the Span in nanos. If still active then returns now() - start time.
      Specified by:
      getLatencyNanos in interface ReadableSpan
      Returns:
      the latency of the Span in nanos.

    • getClock

      AnchoredClock getClock()
      Returns the AnchoredClock used by this Span.

    • setAttribute

      public <T> ReadWriteSpan setAttribute(AttributeKey<T> key, T value)
      Description copied from interface: Span
      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.

      Specified by:
      setAttribute in interface Span
      Parameters:
      key - the key for this attribute.
      value - the value for this attribute.
      Returns:
      this.

    • isModifiableByCurrentThread

      private boolean isModifiableByCurrentThread()

    • addEvent

      public ReadWriteSpan addEvent(String name)
      Description copied from interface: Span
      Adds an event to the Span. The timestamp of the event will be the current time.
      Specified by:
      addEvent in interface Span
      Parameters:
      name - the name of the event.
      Returns:
      this.

    • addEvent

      public ReadWriteSpan addEvent(String name, long timestamp, TimeUnit unit)
      Description copied from interface: Span
      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 Span.addEvent(String) at the time the event occurred.

      Specified by:
      addEvent in interface Span
      Parameters:
      name - the name of the event.
      timestamp - the explicit event timestamp since epoch.
      unit - the unit of the timestamp
      Returns:
      this.

    • addEvent

      public ReadWriteSpan addEvent(String name, Attributes attributes)
      Description copied from interface: Span
      Adds an event to the Span with the given Attributes. The timestamp of the event will be the current time.
      Specified by:
      addEvent in interface Span
      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

      public ReadWriteSpan addEvent(String name, Attributes attributes, long timestamp, TimeUnit unit)
      Description copied from interface: Span
      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 Span.addEvent(String) at the time the event occurred.

      Specified by:
      addEvent in interface Span
      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.

    • addTimedEvent

      private void addTimedEvent(EventData timedEvent)

    • setStatus

      public ReadWriteSpan setStatus(StatusCode statusCode, @Nullable String description)
      Description copied from interface: Span
      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.

      Specified by:
      setStatus in interface Span
      Parameters:
      statusCode - the StatusCode to set.
      description - the description of the Status.
      Returns:
      this.

    • recordException

      public ReadWriteSpan recordException(Throwable exception)
      Description copied from interface: Span
      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 Span.recordException(Throwable, Attributes) if you know that an exception is escaping.

      Specified by:
      recordException in interface Span
      Parameters:
      exception - the Throwable to record.
      Returns:
      this.

    • recordException

      public ReadWriteSpan recordException(Throwable exception, Attributes additionalAttributes)
      Description copied from interface: Span
      Records information about the Throwable to the Span.
      Specified by:
      recordException in interface Span
      Parameters:
      exception - the Throwable to record.
      additionalAttributes - the additional Attributes to record.
      Returns:
      this.

    • updateName

      public ReadWriteSpan updateName(String name)
      Description copied from interface: Span
      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.

      Specified by:
      updateName in interface Span
      Parameters:
      name - the Span name.
      Returns:
      this.

    • addLink

      public Span addLink(SpanContext spanContext, Attributes attributes)
      Description copied from interface: Span
      Adds a link to this Span.

      Links are used to link Spans in different traces. Used (for example) in batching operations, where a single batch handler processes multiple requests from different traces or the same trace.

      Implementations may ignore calls with an invalid span context.

      Callers should prefer to add links before starting the span via SpanBuilder.addLink(SpanContext, Attributes) if possible.

      Specified by:
      addLink in interface Span
      Parameters:
      spanContext - the context of the linked Span.
      attributes - the attributes of the Link.
      Returns:
      this.

    • end

      public void end()
      Description copied from interface: Span
      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.

      Specified by:
      end in interface Span

    • end

      public void end(long timestamp, TimeUnit unit)
      Description copied from interface: Span
      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 Span.end().

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

    • endInternal

      private void endInternal(long endEpochNanos)

    • isRecording

      public boolean isRecording()
      Description copied from interface: Span
      Returns true if this Span records tracing events (e.g. Span.addEvent(String), Span.setAttribute(String, long)).
      Specified by:
      isRecording in interface Span
      Returns:
      true if this Span records tracing events.

    • getResource

      Resource getResource()

    • getKind

      public SpanKind getKind()
      Description copied from interface: ReadableSpan
      Returns the kind of the span.
      Specified by:
      getKind in interface ReadableSpan
      Returns:
      the kind of the span.

    • getStartEpochNanos

      long getStartEpochNanos()

    • getImmutableTimedEvents

      private List<EventData> getImmutableTimedEvents()

    • getImmutableAttributes

      private Attributes getImmutableAttributes()

    • getImmutableLinks

      private List<LinkData> getImmutableLinks()

    • toString

      public String toString()
      Overrides:
      toString in class Object