Class SdkSpan
- All Implemented Interfaces:
Span
,ImplicitContextKeyed
,ReadableSpan
,ReadWriteSpan
Span
class that records trace events.-
Nested Class Summary
Nested Classes -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate AttributesMap
private final AnchoredClock
private final SpanContext
private long
private static final AttributeKey
<String> private static final AttributeKey
<String> private static final AttributeKey
<String> private SdkSpan.EndState
private final InstrumentationScopeInfo
private final SpanKind
private final Object
private static final Logger
private String
private final SpanContext
private final Resource
private Thread
The thread on whichend()
is called and which will be invoking theSpanProcessor
s.private final SpanLimits
private final SpanProcessor
private final long
private StatusData
private int
private int
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
SdkSpan
(SpanContext context, String name, InstrumentationScopeInfo instrumentationScopeInfo, SpanKind kind, SpanContext parentSpanContext, SpanLimits spanLimits, SpanProcessor spanProcessor, AnchoredClock clock, Resource resource, AttributesMap attributes, List<LinkData> links, int totalRecordedLinks, long startEpochNanos) -
Method Summary
Modifier and TypeMethodDescriptionAdds an event to theSpan
.Adds an event to theSpan
with the giventimestamp
, as nanos since epoch.addEvent
(String name, Attributes attributes) Adds an event to theSpan
with the givenAttributes
.addEvent
(String name, Attributes attributes, long timestamp, TimeUnit unit) addLink
(SpanContext spanContext, Attributes attributes) Adds a link to thisSpan
.private void
addTimedEvent
(EventData timedEvent) void
end()
Marks the end ofSpan
execution.void
Marks the end ofSpan
execution with the specified timestamp.private void
endInternal
(long endEpochNanos) <T> T
getAttribute
(AttributeKey<T> key) Returns the value for the givenAttributeKey
, ornull
if not found.Returns the Span attributes.(package private) AnchoredClock
getClock()
Returns theAnchoredClock
used by thisSpan
.private Attributes
Deprecated.Returns the instrumentation scope specified when creating the tracer which produced this span.getKind()
Returns the kind of the span.long
Returns the latency of theSpan
in nanos.getName()
Returns the name of theSpan
.(package private) Resource
Returns theSpanContext
associated with thisSpan
.(package private) long
boolean
hasEnded()
Returns whether this Span has already been ended.private boolean
boolean
Returnstrue
if thisSpan
records tracing events (e.g.recordException
(Throwable exception) recordException
(Throwable exception, Attributes additionalAttributes) <T> ReadWriteSpan
setAttribute
(AttributeKey<T> key, T value) Sets an attribute to theSpan
.setStatus
(StatusCode statusCode, String description) Sets the status to theSpan
.(package private) static SdkSpan
startSpan
(SpanContext context, String name, InstrumentationScopeInfo instrumentationScopeInfo, SpanKind kind, Span parentSpan, Context parentContext, SpanLimits spanLimits, SpanProcessor spanProcessor, Clock tracerClock, Resource resource, AttributesMap attributes, List<LinkData> links, int totalRecordedLinks, long userStartEpochNanos) Creates and starts a span with the given configuration.This converts this instance into an immutable SpanData instance, for use in export.toString()
updateName
(String name) Updates theSpan
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 Details
-
logger
-
spanLimits
-
context
-
parentSpanContext
-
spanProcessor
-
kind
-
clock
-
resource
-
instrumentationScopeInfo
-
startEpochNanos
private final long startEpochNanos -
lock
-
name
-
attributes
-
events
-
totalRecordedEvents
private int totalRecordedEvents -
links
-
totalRecordedLinks
private int totalRecordedLinks -
status
-
endEpochNanos
private long endEpochNanos -
hasEnded
-
spanEndingThread
The thread on whichend()
is called and which will be invoking theSpanProcessor
s. This field is used to ensure that only this thread may modify the span while it is in stateSdkSpan.EndState.ENDING
to prevent concurrent updates outside ofExtendedSpanProcessor.onEnding(ReadWriteSpan)
. -
EXCEPTION_TYPE
-
EXCEPTION_MESSAGE
-
EXCEPTION_STACKTRACE
-
-
Constructor Details
-
SdkSpan
private SdkSpan(SpanContext context, String name, InstrumentationScopeInfo instrumentationScopeInfo, SpanKind kind, SpanContext parentSpanContext, SpanLimits spanLimits, SpanProcessor spanProcessor, AnchoredClock clock, Resource resource, @Nullable AttributesMap attributes, @Nullable List<LinkData> links, int totalRecordedLinks, long startEpochNanos)
-
-
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, orSpan.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 clockresource
- 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
Description copied from interface:ReadableSpan
This converts this instance into an immutable SpanData instance, for use in export.- Specified by:
toSpanData
in interfaceReadableSpan
- Returns:
- an immutable
SpanData
instance.
-
getAttribute
Description copied from interface:ReadableSpan
Returns the value for the givenAttributeKey
, ornull
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 interfaceReadableSpan
- Returns:
- the value for the given
AttributeKey
, ornull
if not found.
-
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 interfaceReadableSpan
- 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 interfaceReadableSpan
- Returns:
true
if the span has already been ended,false
if not.
-
getSpanContext
Description copied from interface:Span
Returns theSpanContext
associated with thisSpan
.- Specified by:
getSpanContext
in interfaceReadableSpan
- Specified by:
getSpanContext
in interfaceSpan
- Returns:
- the
SpanContext
associated with thisSpan
.
-
getParentSpanContext
Description copied from interface:ReadableSpan
- Specified by:
getParentSpanContext
in interfaceReadableSpan
- Returns:
- the parent
SpanContext
of theSpan
-
getName
Returns the name of theSpan
.- Specified by:
getName
in interfaceReadableSpan
- Returns:
- the name of the
Span
.
-
getInstrumentationLibraryInfo
Deprecated.Description copied from interface:ReadableSpan
Returns the instrumentation library specified when creating the tracer which produced this span.- Specified by:
getInstrumentationLibraryInfo
in interfaceReadableSpan
- Returns:
- an instance of
InstrumentationLibraryInfo
describing the instrumentation library
-
getInstrumentationScopeInfo
Description copied from interface:ReadableSpan
Returns the instrumentation scope specified when creating the tracer which produced this span.- Specified by:
getInstrumentationScopeInfo
in interfaceReadableSpan
- Returns:
- an instance of
InstrumentationScopeInfo
describing the instrumentation scope
-
getLatencyNanos
public long getLatencyNanos()Returns the latency of theSpan
in nanos. If still active then returns now() - start time.- Specified by:
getLatencyNanos
in interfaceReadableSpan
- Returns:
- the latency of the
Span
in nanos.
-
getClock
AnchoredClock getClock()Returns theAnchoredClock
used by thisSpan
. -
setAttribute
Description copied from interface:Span
Sets an attribute to theSpan
. If theSpan
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 interfaceSpan
- Parameters:
key
- the key for this attribute.value
- the value for this attribute.- Returns:
- this.
-
isModifiableByCurrentThread
private boolean isModifiableByCurrentThread() -
addEvent
Description copied from interface:Span
Adds an event to theSpan
. The timestamp of the event will be the current time. -
addEvent
Description copied from interface:Span
Adds an event to theSpan
with the giventimestamp
, as nanos since epoch. Note, thistimestamp
is not the same asSystem.nanoTime()
but may be computed using it, for example, by taking a difference of readings fromSystem.nanoTime()
and adding to the span start time.When possible, it is preferred to use
Span.addEvent(String)
at the time the event occurred. -
addEvent
Description copied from interface:Span
Adds an event to theSpan
with the givenAttributes
. The timestamp of the event will be the current time. -
addEvent
Description copied from interface:Span
Adds an event to theSpan
with the givenAttributes
andtimestamp
. Note, thistimestamp
is not the same asSystem.nanoTime()
but may be computed using it, for example, by taking a difference of readings fromSystem.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 interfaceSpan
- Parameters:
name
- the name of the event.attributes
- the attributes that will be added; these are associated with this event, not theSpan
as forsetAttribute()
.timestamp
- the explicit event timestamp since epoch.unit
- the unit of the timestamp- Returns:
- this.
-
addTimedEvent
-
setStatus
Description copied from interface:Span
Sets the status to theSpan
.If used, this will override the default
Span
status. Default status code isStatusCode.UNSET
.Only the value of the last call will be recorded, and implementations are free to ignore previous calls.
- Specified by:
setStatus
in interfaceSpan
- Parameters:
statusCode
- theStatusCode
to set.description
- the description of theStatus
.- Returns:
- this.
-
recordException
Description copied from interface:Span
Records information about theThrowable
to theSpan
.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 interfaceSpan
- Parameters:
exception
- theThrowable
to record.- Returns:
- this.
-
recordException
Description copied from interface:Span
- Specified by:
recordException
in interfaceSpan
- Parameters:
exception
- theThrowable
to record.additionalAttributes
- the additionalAttributes
to record.- Returns:
- this.
-
updateName
Description copied from interface:Span
Updates theSpan
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 interfaceSpan
- Parameters:
name
- theSpan
name.- Returns:
- this.
-
addLink
Description copied from interface:Span
Adds a link to thisSpan
.Links are used to link
Span
s 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. -
end
public void end()Description copied from interface:Span
Marks the end ofSpan
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
Description copied from interface:Span
Marks the end ofSpan
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, useSpan.end()
. -
endInternal
private void endInternal(long endEpochNanos) -
isRecording
public boolean isRecording()Description copied from interface:Span
Returnstrue
if thisSpan
records tracing events (e.g.Span.addEvent(String)
,Span.setAttribute(String, long)
).- Specified by:
isRecording
in interfaceSpan
- Returns:
true
if thisSpan
records tracing events.
-
getResource
Resource getResource() -
getKind
Description copied from interface:ReadableSpan
Returns the kind of the span.- Specified by:
getKind
in interfaceReadableSpan
- Returns:
- the kind of the span.
-
getStartEpochNanos
long getStartEpochNanos() -
getImmutableTimedEvents
-
getImmutableAttributes
-
getImmutableLinks
-
toString
-