Package io.opentelemetry.sdk.trace

Class SdkSpan

java.lang.Object

io.opentelemetry.sdk.trace.SdkSpan

All Implemented Interfaces:

Span, ImplicitContextKeyed, ReadableSpan, ReadWriteSpan

@ThreadSafe
final class SdkSpan
extends java.lang.Object
implements ReadWriteSpan

Implementation for the Span class that records trace events.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static class	SdkSpan.EndState

Field Summary

Fields

Modifier and Type	Field	Description
private AttributesMap	attributes
private AnchoredClock	clock
private SpanContext	context
private long	endEpochNanos
private java.util.List<EventData>	events
private static AttributeKey<java.lang.String>	EXCEPTION_MESSAGE
private static AttributeKey<java.lang.String>	EXCEPTION_STACKTRACE
private static AttributeKey<java.lang.String>	EXCEPTION_TYPE
private SdkSpan.EndState	hasEnded
private InstrumentationScopeInfo	instrumentationScopeInfo
private SpanKind	kind
(package private) java.util.List<LinkData>	links
private java.lang.Object	lock
private static java.util.logging.Logger	logger
private java.lang.String	name
private SpanContext	parentSpanContext
private Resource	resource
private java.lang.Thread	spanEndingThread	The thread on which end() is called and which will be invoking the SpanProcessors.
private SpanLimits	spanLimits
private SpanProcessor	spanProcessor
private long	startEpochNanos
private StatusData	status
private int	totalRecordedEvents
private int	totalRecordedLinks

Constructor Summary

Constructors

Modifier	Constructor	Description
private	SdkSpan(SpanContext context, java.lang.String name, InstrumentationScopeInfo instrumentationScopeInfo, SpanKind kind, SpanContext parentSpanContext, SpanLimits spanLimits, SpanProcessor spanProcessor, AnchoredClock clock, Resource resource, AttributesMap attributes, java.util.List<LinkData> links, int totalRecordedLinks, long startEpochNanos)

Method Summary

Modifier and Type	Method	Description
ReadWriteSpan	addEvent(java.lang.String name)	Adds an event to the Span.
ReadWriteSpan	addEvent(java.lang.String name, long timestamp, java.util.concurrent.TimeUnit unit)	Adds an event to the Span with the given timestamp, as nanos since epoch.
ReadWriteSpan	addEvent(java.lang.String name, Attributes attributes)	Adds an event to the Span with the given Attributes.
ReadWriteSpan	addEvent(java.lang.String name, Attributes attributes, long timestamp, java.util.concurrent.TimeUnit unit)	Adds an event to the Span with the given Attributes and timestamp.
Span	addLink(SpanContext spanContext, Attributes attributes)	Adds a link to this Span.
private void	addTimedEvent(EventData timedEvent)
void	end()	Marks the end of Span execution.
void	end(long timestamp, java.util.concurrent.TimeUnit unit)	Marks the end of Span execution with the specified timestamp.
private void	endInternal(long endEpochNanos)
<T> T	getAttribute(AttributeKey<T> key)	Returns the value for the given AttributeKey, or null if not found.
Attributes	getAttributes()	Returns the Span attributes.
(package private) AnchoredClock	getClock()	Returns the AnchoredClock used by this Span.
private Attributes	getImmutableAttributes()
private java.util.List<LinkData>	getImmutableLinks()
private java.util.List<EventData>	getImmutableTimedEvents()
InstrumentationLibraryInfo	getInstrumentationLibraryInfo()	Deprecated.
InstrumentationScopeInfo	getInstrumentationScopeInfo()	Returns the instrumentation scope specified when creating the tracer which produced this span.
SpanKind	getKind()	Returns the kind of the span.
long	getLatencyNanos()	Returns the latency of the Span in nanos.
java.lang.String	getName()	Returns the name of the Span.
SpanContext	getParentSpanContext()	Returns the parent SpanContext of the Span, or SpanContext.getInvalid() if this is a root span.
(package private) Resource	getResource()
SpanContext	getSpanContext()	Returns the SpanContext associated with this Span.
(package private) long	getStartEpochNanos()
boolean	hasEnded()	Returns whether this Span has already been ended.
private boolean	isModifiableByCurrentThread()
boolean	isRecording()	Returns true if this Span records tracing events (e.g.
ReadWriteSpan	recordException(java.lang.Throwable exception)	Records information about the Throwable to the Span.
ReadWriteSpan	recordException(java.lang.Throwable exception, Attributes additionalAttributes)	Records information about the Throwable to the Span.
<T> ReadWriteSpan	setAttribute(AttributeKey<T> key, T value)	Sets an attribute to the Span.
ReadWriteSpan	setStatus(StatusCode statusCode, java.lang.String description)	Sets the status to the Span.
(package private) static SdkSpan	startSpan(SpanContext context, java.lang.String name, InstrumentationScopeInfo instrumentationScopeInfo, SpanKind kind, Span parentSpan, Context parentContext, SpanLimits spanLimits, SpanProcessor spanProcessor, Clock tracerClock, Resource resource, AttributesMap attributes, java.util.List<LinkData> links, int totalRecordedLinks, long userStartEpochNanos)	Creates and starts a span with the given configuration.
SpanData	toSpanData()	This converts this instance into an immutable SpanData instance, for use in export.
java.lang.String	toString()
ReadWriteSpan	updateName(java.lang.String name)	Updates the Span name.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface io.opentelemetry.context.ImplicitContextKeyed

makeCurrent

Methods inherited from interface io.opentelemetry.api.trace.Span

addEvent, addEvent, addLink, end, setAllAttributes, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setStatus, storeInContext

Field Detail

logger

private static final java.util.logging.Logger logger

spanLimits

private final SpanLimits spanLimits

context

private final SpanContext context

parentSpanContext

private final SpanContext parentSpanContext

spanProcessor

private final SpanProcessor spanProcessor

kind

private final SpanKind kind

clock

private final AnchoredClock clock

resource

private final Resource resource

instrumentationScopeInfo

private final InstrumentationScopeInfo instrumentationScopeInfo

startEpochNanos

private final long startEpochNanos

lock

private final java.lang.Object lock

name

private java.lang.String name

attributes

@Nullable
private AttributesMap attributes

events

@Nullable
private java.util.List<EventData> events

totalRecordedEvents

private int totalRecordedEvents

links

@Nullable
java.util.List<LinkData> links

totalRecordedLinks

private int totalRecordedLinks

status

private StatusData status

endEpochNanos

private long endEpochNanos

hasEnded

private SdkSpan.EndState hasEnded

spanEndingThread

@Nullable
private java.lang.Thread spanEndingThread

The thread on which end() is called and which will be invoking the SpanProcessors. This field is used to ensure that only this thread may modify the span while it is in state SdkSpan.EndState.ENDING to prevent concurrent updates outside of ExtendedSpanProcessor.onEnding(ReadWriteSpan).

EXCEPTION_TYPE

private static final AttributeKey<java.lang.String> EXCEPTION_TYPE

EXCEPTION_MESSAGE

private static final AttributeKey<java.lang.String> EXCEPTION_MESSAGE

EXCEPTION_STACKTRACE

private static final AttributeKey<java.lang.String> EXCEPTION_STACKTRACE

Constructor Detail

SdkSpan

private SdkSpan(SpanContext context,
                java.lang.String name,
                InstrumentationScopeInfo instrumentationScopeInfo,
                SpanKind kind,
                SpanContext parentSpanContext,
                SpanLimits spanLimits,
                SpanProcessor spanProcessor,
                AnchoredClock clock,
                Resource resource,
                @Nullable
                AttributesMap attributes,
                @Nullable
                java.util.List<LinkData> links,
                int totalRecordedLinks,
                long startEpochNanos)

Method Detail

startSpan

static SdkSpan startSpan(SpanContext context,
                         java.lang.String name,
                         InstrumentationScopeInfo instrumentationScopeInfo,
                         SpanKind kind,
                         Span parentSpan,
                         Context parentContext,
                         SpanLimits spanLimits,
                         SpanProcessor spanProcessor,
                         Clock tracerClock,
                         Resource resource,
                         @Nullable
                         AttributesMap attributes,
                         @Nullable
                         java.util.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(java.lang.String, java.lang.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(java.lang.String, java.lang.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 java.lang.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(java.lang.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(java.lang.String name,
                              long timestamp,
                              java.util.concurrent.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(java.lang.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(java.lang.String name,
                              Attributes attributes,
                              long timestamp,
                              java.util.concurrent.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
                               java.lang.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(java.lang.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(java.lang.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(java.lang.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,
                java.util.concurrent.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 java.util.List<EventData> getImmutableTimedEvents()

getImmutableAttributes

private Attributes getImmutableAttributes()

getImmutableLinks

private java.util.List<LinkData> getImmutableLinks()

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object