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(Event event) Adds an event to the Span.
void	addEvent(Event event, long timestamp) Adds an event to the Span.
void	addEvent(String name) Adds an event to the Span.
void	addEvent(String name, Attributes attributes) Adds an event to the Span.
void	addEvent(String name, Attributes attributes, long timestamp) Adds an event to the Span.
void	addEvent(String name, long timestamp) Adds an event to the Span.
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	setAttribute(String key, AttributeValue 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(Status status) Sets the Status to the Span.
void	updateName(String name) Updates the Span name.

Method Detail

setAttribute

void setAttribute(String key,
                  @Nullable
                  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 attribute will be silently dropped. Note: this behavior could change in the future.

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.

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.

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.

Parameters:

key - the key for this attribute.

value - the value for this attribute.

Since:

0.1.0

setAttribute

void setAttribute(String key,
                  AttributeValue 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.

Parameters:

name - the name of the event.

Since:

0.1.0

addEvent

void addEvent(String name,
              long timestamp)

Adds an event to the Span.

Use this method to specify an explicit event timestamp. If not called, the implementation will use the current timestamp value, which should be the default case.

Important: this is NOT equivalent with System.nanoTime().

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.

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.

Use this method to specify an explicit event timestamp. If not called, the implementation will use the current timestamp value, which should be the default case.

Important: this is NOT equivalent with System.nanoTime().

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

addEvent

void addEvent(Event event)

Adds an event to the Span.

Parameters:

event - the event to add.

Since:

0.1.0

addEvent

void addEvent(Event event,
              long timestamp)

Adds an event to the Span.

Use this method to specify an explicit event timestamp. If not called, the implementation will use the current timestamp value, which should be the default case.

Important: this is NOT equivalent with System.nanoTime().

Parameters:

event - the event to add.

timestamp - the explicit event timestamp in nanos since epoch.

Since:

0.1.0

setStatus

void setStatus(Status status)

Sets the Status to the Span.

If used, this will override the default Span status. Default is Status.OK.

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

Parameters:

status - the Status to set.

Since:

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