Package io.opentelemetry.api.trace

Class PropagatedSpan

java.lang.Object

io.opentelemetry.api.trace.PropagatedSpan

All Implemented Interfaces:

Span, ImplicitContextKeyed

@Immutable
final class PropagatedSpan
extends java.lang.Object
implements Span

The default Span that is used when no Span implementation is available. All operations are no-op except context propagation.

Field Summary

Fields

Modifier and Type	Field	Description
(package private) static PropagatedSpan	INVALID
private SpanContext	spanContext

Constructor Summary

Constructors

Modifier	Constructor	Description
private	PropagatedSpan(SpanContext spanContext)

Method Summary

Modifier and Type	Method	Description
Span	addEvent(java.lang.String name)	Adds an event to the Span.
Span	addEvent(java.lang.String name, long timestamp, java.util.concurrent.TimeUnit unit)	Adds an event to the Span with the given timestamp, as nanos since epoch.
Span	addEvent(java.lang.String name, Attributes attributes)	Adds an event to the Span with the given Attributes.
Span	addEvent(java.lang.String name, Attributes attributes, long timestamp, java.util.concurrent.TimeUnit unit)	Adds an event to the Span with the given Attributes and timestamp.
(package private) static Span	create(SpanContext spanContext)
void	end()	Marks the end of Span execution.
void	end(long timestamp, java.util.concurrent.TimeUnit unit)	Marks the end of Span execution with the specified timestamp.
SpanContext	getSpanContext()	Returns the SpanContext associated with this Span.
boolean	isRecording()	Returns true if this Span records tracing events (e.g.
Span	recordException(java.lang.Throwable exception)	Records information about the Throwable to the Span.
Span	recordException(java.lang.Throwable exception, Attributes additionalAttributes)	Records information about the Throwable to the Span.
Span	setAllAttributes(Attributes attributes)	Sets attributes to the Span.
<T> Span	setAttribute(AttributeKey<T> key, T value)	Sets an attribute to the Span.
Span	setAttribute(java.lang.String key, boolean value)	Sets an attribute to the Span.
Span	setAttribute(java.lang.String key, double value)	Sets an attribute to the Span.
Span	setAttribute(java.lang.String key, long value)	Sets an attribute to the Span.
Span	setAttribute(java.lang.String key, java.lang.String value)	Sets an attribute to the Span.
Span	setStatus(StatusCode statusCode)	Sets the status to the Span.
Span	setStatus(StatusCode statusCode, java.lang.String description)	Sets the status to the Span.
java.lang.String	toString()
Span	updateName(java.lang.String name)	Updates the Span name.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface io.opentelemetry.context.ImplicitContextKeyed

makeCurrent

Methods inherited from interface io.opentelemetry.api.trace.Span

addEvent, addEvent, addLink, addLink, end, setAttribute, storeInContext

Field Detail

INVALID

static final PropagatedSpan INVALID

spanContext

private final SpanContext spanContext

Constructor Detail

PropagatedSpan

private PropagatedSpan(SpanContext spanContext)

Method Detail

create

static Span create(SpanContext spanContext)

setAttribute

public Span setAttribute(java.lang.String key,
                         java.lang.String value)

Description copied from interface: Span

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 Span.setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

Specified by:

setAttribute in interface Span

Parameters:

key - the key for this attribute.

value - the value for this attribute.

Returns:

this.

setAttribute

public Span setAttribute(java.lang.String key,
                         long value)

Description copied from interface: Span

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 Span.setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

Specified by:

setAttribute in interface Span

Parameters:

key - the key for this attribute.

value - the value for this attribute.

Returns:

this.

setAttribute

public Span setAttribute(java.lang.String key,
                         double value)

Description copied from interface: Span

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 Span.setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

Specified by:

setAttribute in interface Span

Parameters:

key - the key for this attribute.

value - the value for this attribute.

Returns:

this.

setAttribute

public Span setAttribute(java.lang.String key,
                         boolean value)

Description copied from interface: Span

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 Span.setAttribute(AttributeKey, Object), and pre-allocate your keys, if possible.

Specified by:

setAttribute in interface Span

Parameters:

key - the key for this attribute.

value - the value for this attribute.

Returns:

this.

setAttribute

public <T> Span setAttribute(AttributeKey<T> key,
                             T value)

Description copied from interface: Span

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.

Specified by:

setAttribute in interface Span

Parameters:

key - the key for this attribute.

value - the value for this attribute.

Returns:

this.

setAllAttributes

public Span setAllAttributes(Attributes attributes)

Description copied from interface: Span

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.

Specified by:

setAllAttributes in interface Span

Parameters:

attributes - the attributes

Returns:

this.

addEvent

public Span addEvent(java.lang.String name)

Description copied from interface: Span

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

Specified by:

addEvent in interface Span

Parameters:

name - the name of the event.

Returns:

this.

addEvent

public Span addEvent(java.lang.String name,
                     long timestamp,
                     java.util.concurrent.TimeUnit unit)

Description copied from interface: Span

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 Span.addEvent(String) at the time the event occurred.

Specified by:

addEvent in interface Span

Parameters:

name - the name of the event.

timestamp - the explicit event timestamp since epoch.

unit - the unit of the timestamp

Returns:

this.

addEvent

public Span addEvent(java.lang.String name,
                     Attributes attributes)

Description copied from interface: Span

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

Specified by:

addEvent in interface 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().

Returns:

this.

addEvent

public Span addEvent(java.lang.String name,
                     Attributes attributes,
                     long timestamp,
                     java.util.concurrent.TimeUnit unit)

Description copied from interface: Span

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 Span.addEvent(String) at the time the event occurred.

Specified by:

addEvent in interface 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().

timestamp - the explicit event timestamp since epoch.

unit - the unit of the timestamp

Returns:

this.

setStatus

public Span setStatus(StatusCode statusCode)

Description copied from interface: Span

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.

Specified by:

setStatus in interface Span

Parameters:

statusCode - the StatusCode to set.

Returns:

this.

setStatus

public Span setStatus(StatusCode statusCode,
                      java.lang.String description)

Description copied from interface: Span

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.

Specified by:

setStatus in interface Span

Parameters:

statusCode - the StatusCode to set.

description - the description of the Status.

Returns:

this.

recordException

public Span recordException(java.lang.Throwable exception)

Description copied from interface: Span

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 Span.recordException(Throwable, Attributes) if you know that an exception is escaping.

Specified by:

recordException in interface Span

Parameters:

exception - the Throwable to record.

Returns:

this.

recordException

public Span recordException(java.lang.Throwable exception,
                            Attributes additionalAttributes)

Description copied from interface: Span

Records information about the Throwable to the Span.

Specified by:

recordException in interface Span

Parameters:

exception - the Throwable to record.

additionalAttributes - the additional Attributes to record.

Returns:

this.

updateName

public Span updateName(java.lang.String name)

Description copied from interface: Span

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.

Specified by:

updateName in interface Span

Parameters:

name - the Span name.

Returns:

this.

end

public void end()

Description copied from interface: Span

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.

Specified by:

end in interface Span

end

public void end(long timestamp,
                java.util.concurrent.TimeUnit unit)

Description copied from interface: Span

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

Specified by:

end in interface Span

Parameters:

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

unit - the unit of the timestamp

getSpanContext

public SpanContext getSpanContext()

Description copied from interface: Span

Returns the SpanContext associated with this Span.

Specified by:

getSpanContext in interface Span

Returns:

the SpanContext associated with this Span.

isRecording

public boolean isRecording()

Description copied from interface: Span

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

Specified by:

isRecording in interface Span

Returns:

true if this Span records tracing events.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object