Top Description Methods
io.opentelemetry.api.trace

public Interface Span

extends ImplicitContextKeyed
Known Direct Implementers
io.opentelemetry.api.trace.PropagatedSpan
Annotations
@ThreadSafe
Static Imports
java.util.concurrent.TimeUnit.NANOSECONDS, .TimeUnit.SECONDS

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 Summary

Modifier and TypeMethod and Description
public default Span

Returns:

this.
addEvent
(String
the name of the event.
name
)

Adds an event to the Span.

public default Span

Returns:

this.
addEvent
(String
the name of the event.
name
,
long
the explicit event timestamp since epoch.
timestamp
,
TimeUnit
the unit of the timestamp
unit
)

Adds an event to the Span with the given timestamp, as nanos since epoch.

public default Span

Returns:

this.
addEvent
(String
the name of the event.
name
,
Instant
the explicit event timestamp since epoch.
timestamp
)

Adds an event to the Span with the given timestamp, as nanos since epoch.

public Span

Returns:

this.
addEvent
(String
the name of the event.
name
,
Attributes
the attributes that will be added; these are associated with this event, not the Span as for setAttribute().
attributes
)

Adds an event to the Span with the given Attributes.

public Span

Returns:

this.
addEvent
(String
the name of the event.
name
,
Attributes
the attributes that will be added; these are associated with this event, not the Span as for setAttribute().
attributes
,
long
the explicit event timestamp since epoch.
timestamp
,
TimeUnit
the unit of the timestamp
unit
)

Adds an event to the Span with the given Attributes and timestamp.

public default Span

Returns:

this.
addEvent
(String
the name of the event.
name
,
Attributes
the attributes that will be added; these are associated with this event, not the Span as for setAttribute().
attributes
,
Instant
the explicit event timestamp since epoch.
timestamp
)

Adds an event to the Span with the given Attributes and timestamp.

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

public void
end()

Marks the end of Span execution.

public void
end(long
the explicit timestamp from the epoch, for this Span. 0 indicates current time should be used.
timestamp
,
TimeUnit
the unit of the timestamp
unit
)

Marks the end of Span execution with the specified timestamp.

public default void
end(Instant
the explicit timestamp from the epoch, for this Span. 0 indicates current time should be used.
timestamp
)

Marks the end of Span execution with the specified timestamp.

public static Span
fromContext(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.

public static Span
fromContextOrNull(Context context)

Returns the Span from the specified Context, or null if there is no span in the context.

public static Span
getInvalid()

Returns an invalid Span.

public SpanContext

Returns:

the SpanContext associated with this Span.
getSpanContext
()

Returns the SpanContext associated with this Span.

public boolean

Returns:

true if this Span records tracing events.
isRecording
()

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

public default Span

Returns:

this.
recordException
(Throwable
the Throwable to record.
exception
)

Records information about the Throwable to the Span.

public Span

Returns:

this.
recordException
(Throwable
the Throwable to record.
exception
,
Attributes
the additional Attributes to record.
additionalAttributes
)

Records information about the Throwable to the Span.

public default Span

Returns:

this.
setAllAttributes
(Attributes
the attributes
attributes
)

Sets attributes to the Span.

public default Span

Returns:

this.
setAttribute
(String
the key for this attribute.
key
,
String
the value for this attribute.
value
)

Sets an attribute to the Span.

public default Span

Returns:

this.
setAttribute
(String
the key for this attribute.
key
,
long
the value for this attribute.
value
)

Sets an attribute to the Span.

public default Span

Returns:

this.
setAttribute
(String
the key for this attribute.
key
,
double
the value for this attribute.
value
)

Sets an attribute to the Span.

public default Span

Returns:

this.
setAttribute
(String
the key for this attribute.
key
,
boolean
the value for this attribute.
value
)

Sets an attribute to the Span.

public <T> Span

Returns:

this.
setAttribute
(AttributeKey<T>
the key for this attribute.
key
,
T
the value for this attribute.
value
)

Sets an attribute to the Span.

public default Span

Returns:

this.
setAttribute
(AttributeKey<Long>
the key for this attribute.
key
,
int
the value for this attribute.
value
)

Sets an attribute to the Span.

public default Span

Returns:

this.
setStatus
(StatusCode
the StatusCode to set.
statusCode
)

Sets the status to the Span.

public Span

Returns:

this.
setStatus
(StatusCode
the StatusCode to set.
statusCode
,
String
the description of the Status.
description
)

Sets the status to the Span.

public default Context
storeInContext(Context context)

Implements io.opentelemetry.context.ImplicitContextKeyed.storeInContext.

Returns a new Context created by setting this into the provided Context.

public Span

Returns:

this.
updateName
(String
the Span name.
name
)

Updates the Span name.

public static Span
wrap(SpanContext spanContext)

Returns a non-recording Span that holds the provided SpanContext but has no functionality.

Inherited from io.opentelemetry.context.ImplicitContextKeyed:
makeCurrent

Method Detail

addEventback to summary
public default Span addEvent(String name)

Adds an event to the Span. The timestamp of the event will be the current time.

Parameters
name:String

the name of the event.

Returns:Span

this.

addEventback to summary
public 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:String

the name of the event.

timestamp:long

the explicit event timestamp since epoch.

unit:TimeUnit

the unit of the timestamp

Returns:Span

this.

addEventback to summary
public 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:String

the name of the event.

timestamp:Instant

the explicit event timestamp since epoch.

Returns:Span

this.

addEventback to summary
public 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:String

the name of the event.

attributes:Attributes

the attributes that will be added; these are associated with this event, not the Span as for setAttribute().

Returns:Span

this.

addEventback to summary
public 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:String

the name of the event.

attributes:Attributes

the attributes that will be added; these are associated with this event, not the Span as for setAttribute().

timestamp:long

the explicit event timestamp since epoch.

unit:TimeUnit

the unit of the timestamp

Returns:Span

this.

addEventback to summary
public 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:String

the name of the event.

attributes:Attributes

the attributes that will be added; these are associated with this event, not the Span as for setAttribute().

timestamp:Instant

the explicit event timestamp since epoch.

Returns:Span

this.

currentback to summary
public 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.

endback to summary
public 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.

endback to summary
public 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:long

the explicit timestamp from the epoch, for this Span. 0 indicates current time should be used.

unit:TimeUnit

the unit of the timestamp

endback to summary
public 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:Instant

the explicit timestamp from the epoch, for this Span. 0 indicates current time should be used.

fromContextback to summary
public static Span fromContext(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.

fromContextOrNullback to summary
public static Span fromContextOrNull(Context context)

Returns the Span from the specified Context, or null if there is no span in the context.

Annotations
@Nullable
getInvalidback to summary
public static Span getInvalid()

Returns an invalid Span. An invalid Span is used when tracing is disabled, usually because there is no OpenTelemetry SDK installed.

getSpanContextback to summary
public SpanContext getSpanContext()

Returns the SpanContext associated with this Span.

Returns:SpanContext

the SpanContext associated with this Span.

isRecordingback to summary
public boolean isRecording()

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

Returns:boolean

true if this Span records tracing events.

recordExceptionback to summary
public 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:Throwable

the Throwable to record.

Returns:Span

this.

recordExceptionback to summary
public Span recordException(Throwable exception, Attributes additionalAttributes)

Records information about the Throwable to the Span.

Parameters
exception:Throwable

the Throwable to record.

additionalAttributes:Attributes

the additional Attributes to record.

Returns:Span

this.

setAllAttributesback to summary
public 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:Attributes

the attributes

Returns:Span

this.

Annotations
@SuppressWarnings:unchecked
Since
1.2.0
setAttributeback to summary
public 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.

Empty String "" and null are valid attribute value, but not valid keys.

Note

It is strongly recommended to use setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

Parameters
key:String

the key for this attribute.

value:String

the value for this attribute.

Returns:Span

this.

setAttributeback to summary
public 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:String

the key for this attribute.

value:long

the value for this attribute.

Returns:Span

this.

setAttributeback to summary
public 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:String

the key for this attribute.

value:double

the value for this attribute.

Returns:Span

this.

setAttributeback to summary
public 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:String

the key for this attribute.

value:boolean

the value for this attribute.

Returns:Span

this.

setAttributeback to summary
public <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:AttributeKey<T>

the key for this attribute.

value:T

the value for this attribute.

Returns:Span

this.

setAttributeback to summary
public 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:AttributeKey<Long>

the key for this attribute.

value:int

the value for this attribute.

Returns:Span

this.

setStatusback to summary
public 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:StatusCode

the StatusCode to set.

Returns:Span

this.

setStatusback to summary
public 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:StatusCode

the StatusCode to set.

description:String

the description of the Status.

Returns:Span

this.

storeInContextback to summary
public default Context storeInContext(Context context)

Implements io.opentelemetry.context.ImplicitContextKeyed.storeInContext.

Doc from io.opentelemetry.context.ImplicitContextKeyed.storeInContext.

Returns a new Context created by setting this into the provided Context. It is generally recommended to call Context#with(ImplicitContextKeyed) instead of this method. The following are equivalent.

  • context.with(myContextValue)
  • myContextValue.storeInContext(context)
Annotations
@Override
updateNameback to summary
public 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:String

the Span name.

Returns:Span

this.

wrapback to summary
public 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 SpanContext downstream.