io.opentelemetry.trace

Interface Span

All Known Implementing Classes:

DefaultSpan

@ThreadSafe
public interface Span

An interface that represents a span. It has an associated SpanContext.

Spans are created by the Span.Builder.startSpan() method.

Span must be ended by calling end().

Since:

0.1.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Span.Builder Span.Builder is used to construct Span instances which define arbitrary scopes of code that are sampled for distributed tracing as a single atomic unit.
static class	Span.Kind Type of span.

Method Summary

Modifier and Type	Method and Description
void	addEvent(String name) Adds an event to the Span.
void	addEvent(String name, Attributes attributes) Adds an event to the Span with the given Attributes.
void	addEvent(String name, Attributes attributes, long timestamp) Adds an event to the Span with the given Attributes and timestamp.
void	addEvent(String name, long timestamp) Adds an event to the Span with the given timestamp, as nanos since epoch.
void	end() Marks the end of Span execution.
void	end(EndSpanOptions endOptions) Marks the end of Span execution with the specified EndSpanOptions.
SpanContext	getContext() Returns the SpanContext associated with this Span.
boolean	isRecording() Returns true if this Span records tracing events (e.g.
void	recordException(Throwable exception) Records information about the Throwable to the Span.
void	recordException(Throwable exception, Attributes additionalAttributes) Records information about the Throwable to the Span.
default void	setAttribute(AttributeKey<Long> key, int value) Sets an attribute to the Span.
<T> void	setAttribute(AttributeKey<T> key, T value) Sets an attribute to the Span.
void	setAttribute(String key, boolean value) Sets an attribute to the Span.
void	setAttribute(String key, double value) Sets an attribute to the Span.
void	setAttribute(String key, long value) Sets an attribute to the Span.
void	setAttribute(String key, String value) Sets an attribute to the Span.
void	setStatus(StatusCanonicalCode canonicalCode) Sets the status to the Span.
void	setStatus(StatusCanonicalCode canonicalCode, String description) Sets the status to the Span.
void	updateName(String name) Updates the Span name.

Method Detail

setAttribute

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

Since:

0.1.0

setAttribute

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

Since:

0.1.0

setAttribute

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

Since:

0.1.0

setAttribute

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

Since:

0.1.0

setAttribute

<T> void setAttribute(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.

Since:

0.1.0

setAttribute

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

value - the value for this attribute.

Since:

0.1.0

addEvent

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

Since:

0.1.0

addEvent

void addEvent(String name,
              long 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 in nanos since epoch.

Since:

0.1.0

addEvent

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

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

Since:

0.1.0

addEvent

void addEvent(String name,
              Attributes attributes,
              long 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 in nanos since epoch.

Since:

0.1.0

setStatus

void setStatus(StatusCanonicalCode canonicalCode)

Sets the status to the Span.

If used, this will override the default Span status. Default status code is StatusCanonicalCode.UNSET.

Only the value of the last call will be recorded, and implementations are free to ignore previous calls.

Parameters:

canonicalCode - the StatusCanonicalCode to set.

Since:

0.9.0

setStatus

void setStatus(StatusCanonicalCode canonicalCode,
               String description)

Sets the status to the Span.

If used, this will override the default Span status. Default status code is StatusCanonicalCode.UNSET.

Only the value of the last call will be recorded, and implementations are free to ignore previous calls.

Parameters:

canonicalCode - the StatusCanonicalCode to set.

description - the description of the Status.

Since:

0.9.0

recordException

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

Since:

0.7.0

recordException

void recordException(Throwable exception,
                     Attributes additionalAttributes)

Records information about the Throwable to the Span.

Parameters:

exception - the Throwable to record.

additionalAttributes - the additional Attributes to record.

Since:

0.8.0

updateName

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

Since:

0.1

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.

Since:

0.1.0

end

void end(EndSpanOptions endOptions)

Marks the end of Span execution with the specified EndSpanOptions.

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:

endOptions - the explicit EndSpanOptions for this Span.

Since:

0.1.0

getContext

SpanContext getContext()

Returns the SpanContext associated with this Span.

Returns:

the SpanContext associated with this Span.

Since:

0.1.0

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.

Since:

0.1.0