Package io.opentelemetry.api.trace

Interface SpanContext

@Immutable
public interface SpanContext

A class that represents a span context. A span context contains the state that must propagate to child Spans and across process boundaries. It contains the identifiers (a trace_id and span_id) associated with the Span and a set of options (currently only whether the context is sampled or not), as well as the traceState and the remote flag.

Implementations of this interface *must* be immutable and have well-defined value-based equals/hashCode implementations. If an implementation does not strictly conform to these requirements, behavior of the OpenTelemetry APIs and default SDK cannot be guaranteed. It is strongly suggested that you use the implementation that is provided here via create(String, String, TraceFlags, TraceState) or createFromRemoteParent(String, String, TraceFlags, TraceState).

Method Summary

Modifier and Type	Method	Description
static SpanContext	create(String traceIdHex, String spanIdHex, TraceFlags traceFlags, TraceState traceState)	Creates a new SpanContext with the given identifiers and options.
static SpanContext	createFromRemoteParent(String traceIdHex, String spanIdHex, TraceFlags traceFlags, TraceState traceState)	Creates a new SpanContext that was propagated from a remote parent, with the given identifiers and options.
static SpanContext	getInvalid()	Returns the invalid SpanContext that can be used for no-op operations.
String	getSpanId()	Returns the span identifier associated with this SpanContext as 16 character lowercase hex String.
default byte[]	getSpanIdBytes()	Returns the span identifier associated with this SpanContext as 8-byte array.
TraceFlags	getTraceFlags()	Returns the trace flags associated with this SpanContext.
String	getTraceId()	Returns the trace identifier associated with this SpanContext as 32 character lowercase hex String.
default byte[]	getTraceIdBytes()	Returns the trace identifier associated with this SpanContext as 16-byte array.
TraceState	getTraceState()	Returns the TraceState associated with this SpanContext.
boolean	isRemote()	Returns true if the SpanContext was propagated from a remote parent.
default boolean	isSampled()	Whether the span in this context is sampled.
default boolean	isValid()	Returns true if this SpanContext is valid.

Method Detail

getInvalid

static SpanContext getInvalid()

Returns the invalid SpanContext that can be used for no-op operations.

Returns:

the invalid SpanContext.

create

static SpanContext create(String traceIdHex,
                          String spanIdHex,
                          TraceFlags traceFlags,
                          TraceState traceState)

Creates a new SpanContext with the given identifiers and options.

If the traceId or the spanId are invalid (ie. do not conform to the requirements for hexadecimal ids of the appropriate lengths), both will be replaced with the standard "invalid" versions (i.e. all '0's). See SpanId.isValid(CharSequence) and TraceId.isValid(CharSequence) for details.

Parameters:

traceIdHex - the trace identifier of the SpanContext.

spanIdHex - the span identifier of the SpanContext.

traceFlags - the trace flags of the SpanContext.

traceState - the trace state for the SpanContext.

Returns:

a new SpanContext with the given identifiers and options.

createFromRemoteParent

static SpanContext createFromRemoteParent(String traceIdHex,
                                          String spanIdHex,
                                          TraceFlags traceFlags,
                                          TraceState traceState)

Creates a new SpanContext that was propagated from a remote parent, with the given identifiers and options.

If the traceId or the spanId are invalid (ie. do not conform to the requirements for hexadecimal ids of the appropriate lengths), both will be replaced with the standard "invalid" versions (i.e. all '0's). See SpanId.isValid(CharSequence) and TraceId.isValid(CharSequence) for details.

Parameters:

traceIdHex - the trace identifier of the SpanContext.

spanIdHex - the span identifier of the SpanContext.

traceFlags - the trace flags of the SpanContext.

traceState - the trace state for the SpanContext.

Returns:

a new SpanContext with the given identifiers and options.

getTraceId

String getTraceId()

Returns the trace identifier associated with this SpanContext as 32 character lowercase hex String.

Returns:

the trace identifier associated with this SpanContext as lowercase hex.

getTraceIdBytes

default byte[] getTraceIdBytes()

Returns the trace identifier associated with this SpanContext as 16-byte array.

Returns:

the trace identifier associated with this SpanContext as 16-byte array.

getSpanId

String getSpanId()

Returns the span identifier associated with this SpanContext as 16 character lowercase hex String.

Returns:

the span identifier associated with this SpanContext as 16 character lowercase hex (base16) String.

getSpanIdBytes

default byte[] getSpanIdBytes()

Returns the span identifier associated with this SpanContext as 8-byte array.

Returns:

the span identifier associated with this SpanContext as 8-byte array.

isSampled

default boolean isSampled()

Whether the span in this context is sampled.

getTraceFlags

TraceFlags getTraceFlags()

Returns the trace flags associated with this SpanContext.

Returns:

the trace flags associated with this SpanContext.

getTraceState

TraceState getTraceState()

Returns the TraceState associated with this SpanContext.

Returns:

the TraceState associated with this SpanContext.

isValid

default boolean isValid()

Returns true if this SpanContext is valid.

Returns:

true if this SpanContext is valid.

isRemote

boolean isRemote()

Returns true if the SpanContext was propagated from a remote parent.

Returns:

true if the SpanContext was propagated from a remote parent.