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 Details

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