Package io.opentelemetry.api.trace

Interface Span

All Superinterfaces:

io.opentelemetry.context.ImplicitContextKeyed

@ThreadSafe
public interface Span
extends io.opentelemetry.context.ImplicitContextKeyed

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().

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Span.Kind	Type of span.

Method Summary

Modifier and Type	Method	Description
default Span	addEvent(String name)	Adds an event to the Span.
default Span	addEvent(String name, long timestamp, TimeUnit unit)	Adds an event to the Span with the given timestamp, as nanos since epoch.
Span	addEvent(String name, io.opentelemetry.api.common.Attributes attributes)	Adds an event to the Span with the given Attributes.
Span	addEvent(String name, io.opentelemetry.api.common.Attributes attributes, long timestamp, TimeUnit unit)	Adds an event to the Span with the given Attributes and timestamp.
default Span	addEvent(String name, io.opentelemetry.api.common.Attributes attributes, Instant timestamp)	Adds an event to the Span with the given Attributes and timestamp.
default Span	addEvent(String name, Instant timestamp)	Adds an event to the Span with the given timestamp, as nanos since epoch.
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.
void	end()	Marks the end of Span execution.
void	end(long timestamp, TimeUnit unit)	Marks the end of Span execution with the specified timestamp.
default void	end(Instant timestamp)	Marks the end of Span execution with the specified timestamp.
static Span	fromContext(io.opentelemetry.context.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.
static Span	fromContextOrNull(io.opentelemetry.context.Context context)	Returns the Span from the specified Context, or null if there is no span in the context.
static Span	getInvalid()	Returns an invalid Span.
SpanContext	getSpanContext()	Returns the SpanContext associated with this Span.
boolean	isRecording()	Returns true if this Span records tracing events (e.g.
default Span	recordException(Throwable exception)	Records information about the Throwable to the Span.
Span	recordException(Throwable exception, io.opentelemetry.api.common.Attributes additionalAttributes)	Records information about the Throwable to the Span.
default Span	setAttribute(io.opentelemetry.api.common.AttributeKey<Long> key, int value)	Sets an attribute to the Span.
<T> Span	setAttribute(io.opentelemetry.api.common.AttributeKey<T> key, T value)	Sets an attribute to the Span.
default Span	setAttribute(String key, boolean value)	Sets an attribute to the Span.
default Span	setAttribute(String key, double value)	Sets an attribute to the Span.
default Span	setAttribute(String key, long value)	Sets an attribute to the Span.
default Span	setAttribute(String key, String value)	Sets an attribute to the Span.
default Span	setStatus(StatusCode statusCode)	Sets the status to the Span.
Span	setStatus(StatusCode statusCode, String description)	Sets the status to the Span.
default io.opentelemetry.context.Context	storeInContext(io.opentelemetry.context.Context context)
Span	updateName(String name)	Updates the Span name.
static Span	wrap(SpanContext spanContext)	Returns a non-recording Span that holds the provided SpanContext but has no functionality.

Methods inherited from interface io.opentelemetry.context.ImplicitContextKeyed

makeCurrent

Method Detail

current

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.

fromContext

static Span fromContext(io.opentelemetry.context.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.

fromContextOrNull

@Nullable
static Span fromContextOrNull(io.opentelemetry.context.Context context)

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

getInvalid

static Span getInvalid()

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

wrap

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 valid SpanContext downstream.

setAttribute

default Span setAttribute(String key,
                          @Nonnull
                          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.

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

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 - the key for this attribute.

value - the value for this attribute.

Returns:

this.

setAttribute

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 - the key for this attribute.

value - the value for this attribute.

Returns:

this.

setAttribute

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 - the key for this attribute.

value - the value for this attribute.

Returns:

this.

setAttribute

<T> Span setAttribute(io.opentelemetry.api.common.AttributeKey<T> key,
                      @Nonnull
                      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 - the key for this attribute.

value - the value for this attribute.

Returns:

this.

setAttribute

default Span setAttribute(io.opentelemetry.api.common.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 - the key for this attribute.

value - the value for this attribute.

Returns:

this.

addEvent

default Span addEvent(String name)

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

Parameters:

name - the name of the event.

Returns:

this.

addEvent

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 - the name of the event.

timestamp - the explicit event timestamp since epoch.

unit - the unit of the timestamp

Returns:

this.

addEvent

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 - the name of the event.

timestamp - the explicit event timestamp since epoch.

Returns:

this.

addEvent

Span addEvent(String name,
              io.opentelemetry.api.common.Attributes attributes)

Adds an event to the Span with the given Attributes. 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 the Span as for setAttribute().

Returns:

this.

addEvent

Span addEvent(String name,
              io.opentelemetry.api.common.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 - 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.

addEvent

default Span addEvent(String name,
                      io.opentelemetry.api.common.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 - 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.

Returns:

this.

setStatus

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 - the StatusCode to set.

Returns:

this.

setStatus

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 - the StatusCode to set.

description - the description of the Status.

Returns:

this.

recordException

default Span recordException(Throwable exception)

Records information about the Throwable to the Span.

Note that SemanticAttributes.EXCEPTION_ESCAPED 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 - the Throwable to record.

Returns:

this.

recordException

Span recordException(Throwable exception,
                     io.opentelemetry.api.common.Attributes additionalAttributes)

Records information about the Throwable to the Span.

Parameters:

exception - the Throwable to record.

additionalAttributes - the additional Attributes to record.

Returns:

this.

updateName

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 - the Span name.

Returns:

this.

end

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.

end

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 - the explicit timestamp from the epoch, for this Span. 0 indicates current time should be used.

unit - the unit of the timestamp

end

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 - the explicit timestamp from the epoch, for this Span. 0 indicates current time should be used.

getSpanContext

SpanContext getSpanContext()

Returns the SpanContext associated with this Span.

Returns:

the SpanContext associated with this Span.

isRecording

boolean isRecording()

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

Returns:

true if this Span records tracing events.

storeInContext

default io.opentelemetry.context.Context storeInContext(io.opentelemetry.context.Context context)

Specified by:

storeInContext in interface io.opentelemetry.context.ImplicitContextKeyed