Interface IOTelSpanContext

A SpanContext represents the portion of a IOTelSpan which must be serialized and propagated along side of a IOTelBaggage.

interface IOTelSpanContext {
    isRemote?: boolean;
    spanId: string;
    traceFlags: number;
    traceId: string;
    traceState?: IOTelTraceState | IW3cTraceState;
}

Hierarchy (view full)

Properties

isRemote? spanId traceFlags traceId traceState?

Properties

OptionalisRemote

isRemote?: boolean

Indicates whether this span context was propagated from a remote parent span.

This flag distinguishes between spans created locally within the same process and spans that represent operations in remote services. Remote spans are typically created when trace context is received via HTTP headers, message queues, or other inter-process communication mechanisms.

Default Value

false - spans are considered local unless explicitly marked as remote

Remarks

  • True only when span context was received from another process/service
  • Helps distinguish local vs. distributed trace segments
  • Used by tracing systems for visualization and analysis
  • Local child spans of remote parents are NOT considered remote themselves

Example

// HTTP service receiving trace context
const incomingSpanContext = extractSpanContextFromHeaders(request.headers);
console.log(incomingSpanContext.isRemote); // true

// Child span created locally
const localChild = tracer.startSpan('local-operation', {
  parent: incomingSpanContext
});
console.log(localChild.spanContext().isRemote); // false

spanId

spanId: string

The unique identifier for this specific span within the trace.

The span ID uniquely identifies this span within the trace and is used to establish parent-child relationships between spans. It consists of 8 randomly generated bytes encoded as 16 lowercase hexadecimal characters, providing 64 bits of entropy to ensure global uniqueness with practically sufficient probability.

Remarks

  • Must be exactly 16 lowercase hexadecimal characters
  • Represents 64 bits (8 bytes) of random data
  • Unique within the trace (different spans have different span IDs)
  • Used as parent ID when creating child spans
  • Should never be all zeros (invalid span ID)

Example

// Example span ID format
const spanId = "00f067aa0ba902b7";

// Each span has a unique ID within the trace
const parentId = parentSpan.spanContext().spanId; // "00f067aa0ba902b7"
const childId = childSpan.spanContext().spanId;   // "b9c7c989f97918e1"

// Child span uses parent's span ID as its parent ID
console.log(childSpan.parentSpanId === parentId); // true

traceFlags

traceFlags: number

Trace flags to propagate.

It is represented as 1 byte (bitmap). Bit to represent whether trace is sampled or not. When set, the least significant bit documents that the caller may have recorded trace data. A caller who does not record trace data out-of-band leaves this flag unset.

see eW3CTraceFlags for valid flag values.

traceId

traceId: string

The unique identifier for the trace that this span belongs to.

The trace ID is a globally unique identifier that connects all spans within a single distributed trace. It consists of 16 randomly generated bytes encoded as 32 lowercase hexadecimal characters, providing 128 bits of entropy to ensure worldwide uniqueness with practically sufficient probability.

Remarks

  • Must be exactly 32 lowercase hexadecimal characters
  • Represents 128 bits (16 bytes) of random data
  • Shared by all spans within the same trace
  • Used for trace correlation across distributed systems
  • Should never be all zeros (invalid trace ID)

Example

// Example trace ID format
const traceId = "4bf92f3577b34da6a3ce929d0e0e4736";

// All spans in the same trace share this ID
console.log(parentSpan.spanContext().traceId === childSpan.spanContext().traceId); // true

OptionaltraceState

traceState?: IOTelTraceState | IW3cTraceState

Vendor-specific trace state information for cross-system trace correlation.

The trace state carries tracing-system-specific context in a standardized format defined by the W3C Trace Context specification. It allows multiple tracing systems to participate in the same trace by providing a mechanism for each system to add its own metadata without interfering with others.

The trace state is formatted as a comma-separated list of key-value pairs, where each pair represents one tracing system's contribution. Keys should be unique within the trace state and follow specific naming conventions.

Remarks

  • Maximum of 32 list members allowed
  • Each member format: key=value separated by commas
  • Keys should be namespaced to avoid conflicts (e.g., vendor@system=value)
  • Total size should not exceed 512 characters for practical header limits
  • Spaces around list members are ignored
  • Preserves vendor-specific information during trace propagation

See

W3C Trace Context Specification

Example

// Single tracing system
const singleVendor = {
  get: (key: string) => key === 'rojo' ? '00f067aa0ba902b7' : undefined,
  set: (key: string, value: string) => { ... },
  unset: (key: string) => { ... },
  serialize: () => 'rojo=00f067aa0ba902b7'
};

// Multiple tracing systems
const multiVendor = {
  serialize: () => 'rojo=00f067aa0ba902b7,congo=t61rcWkgMzE,vendor@system=custom-value'
};

// Accessing trace state
const rojoValue = spanContext.traceState?.get('rojo');
const serialized = spanContext.traceState?.serialize();

// HTTP header format (When the traceState is an IOTelTraceState)
headers['tracestate'] = spanContext.traceState?.serialize() || '';

// HTTP header format (When the traceState is an IW3cTraceState)
headers['tracestate'] = spanContext.traceState?.hdrs()[0] || '';

Settings

Member Visibility

On This Page

Properties