Interface Span
- All Superinterfaces:
io.opentelemetry.context.ImplicitContextKeyed
SpanContext
.
Spans are created by the SpanBuilder.startSpan()
method.
Span
must be ended by calling end()
.
-
Method Summary
Modifier and TypeMethodDescriptiondefault Span
Adds an event to theSpan
.default Span
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) default Span
addEvent
(String name, Attributes attributes, Instant timestamp) default Span
Adds an event to theSpan
with the giventimestamp
, as nanos since epoch.static Span
current()
void
end()
Marks the end ofSpan
execution.void
Marks the end ofSpan
execution with the specified timestamp.default void
Marks the end ofSpan
execution with the specified timestamp.static Span
fromContext
(io.opentelemetry.context.Context context) static Span
fromContextOrNull
(io.opentelemetry.context.Context context) static Span
Returns an invalidSpan
.Returns theSpanContext
associated with thisSpan
.boolean
Returnstrue
if thisSpan
records tracing events (e.g.default Span
recordException
(Throwable exception) recordException
(Throwable exception, Attributes additionalAttributes) default Span
setAllAttributes
(Attributes attributes) Sets attributes to theSpan
.default Span
setAttribute
(AttributeKey<Long> key, int value) Sets an attribute to theSpan
.<T> Span
setAttribute
(AttributeKey<T> key, T value) Sets an attribute to theSpan
.default Span
setAttribute
(String key, boolean value) Sets an attribute to theSpan
.default Span
setAttribute
(String key, double value) Sets an attribute to theSpan
.default Span
setAttribute
(String key, long value) Sets an attribute to theSpan
.default Span
setAttribute
(String key, String value) Sets an attribute to theSpan
.default Span
setStatus
(StatusCode statusCode) Sets the status to theSpan
.setStatus
(StatusCode statusCode, String description) Sets the status to theSpan
.default io.opentelemetry.context.Context
storeInContext
(io.opentelemetry.context.Context context) updateName
(String name) Updates theSpan
name.static Span
wrap
(SpanContext spanContext) Returns a non-recordingSpan
that holds the providedSpanContext
but has no functionality.Methods inherited from interface io.opentelemetry.context.ImplicitContextKeyed
makeCurrent
-
Method Details
-
current
-
fromContext
-
fromContextOrNull
-
getInvalid
-
wrap
Returns a non-recordingSpan
that holds the providedSpanContext
but has no functionality. It will not be exported and all tracing operations are no-op, but it can be used to propagate a validSpanContext
downstream. -
setAttribute
Sets an attribute to theSpan
. If theSpan
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
Sets an attribute to theSpan
. If theSpan
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
Sets an attribute to theSpan
. If theSpan
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
Sets an attribute to theSpan
. If theSpan
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
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.
- Parameters:
key
- the key for this attribute.value
- the value for this attribute.- Returns:
- this.
-
setAttribute
Sets an attribute to theSpan
. If theSpan
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
Sets attributes to theSpan
. If theSpan
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
Adds an event to theSpan
. The timestamp of the event will be the current time.- Parameters:
name
- the name of the event.- Returns:
- this.
-
addEvent
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
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
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
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
Adds an event to theSpan
with the givenAttributes
. 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 theSpan
as forsetAttribute()
.- Returns:
- this.
-
addEvent
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
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 theSpan
as forsetAttribute()
.timestamp
- the explicit event timestamp since epoch.unit
- the unit of the timestamp- Returns:
- this.
-
addEvent
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
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 theSpan
as forsetAttribute()
.timestamp
- the explicit event timestamp since epoch.- Returns:
- this.
-
setStatus
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.
- Parameters:
statusCode
- theStatusCode
to set.- Returns:
- this.
-
setStatus
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.
- Parameters:
statusCode
- theStatusCode
to set.description
- the description of theStatus
.- Returns:
- this.
-
recordException
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
recordException(Throwable, Attributes)
if you know that an exception is escaping.- Parameters:
exception
- theThrowable
to record.- Returns:
- this.
-
recordException
- Parameters:
exception
- theThrowable
to record.additionalAttributes
- the additionalAttributes
to record.- Returns:
- this.
-
updateName
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.- Parameters:
name
- theSpan
name.- Returns:
- this.
-
end
void end()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
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, useend()
.- Parameters:
timestamp
- the explicit timestamp from the epoch, for thisSpan
.0
indicates current time should be used.unit
- the unit of the timestamp
-
end
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, useend()
.- Parameters:
timestamp
- the explicit timestamp from the epoch, for thisSpan
.0
indicates current time should be used.
-
getSpanContext
SpanContext getSpanContext()Returns theSpanContext
associated with thisSpan
.- Returns:
- the
SpanContext
associated with thisSpan
.
-
isRecording
boolean isRecording()Returnstrue
if thisSpan
records tracing events (e.g.addEvent(String)
,setAttribute(String, long)
).- Returns:
true
if thisSpan
records tracing events.
-
storeInContext
default io.opentelemetry.context.Context storeInContext(io.opentelemetry.context.Context context) - Specified by:
storeInContext
in interfaceio.opentelemetry.context.ImplicitContextKeyed
-