OptionalisIndicates 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.
// 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
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.
// 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
OptionaltraceTrace flags that control trace behavior and indicate sampling decisions.
The trace flags are represented as a single byte (8-bit bitmap) that carries trace-level information. The least significant bit (0x01) indicates whether the trace is sampled. When this bit is set, it documents that the caller may have recorded trace data. Additional bits are reserved for future use and should be ignored when not understood.
// Check if trace is sampled
const isSampled = (spanContext.traceFlags & 0x01) === 1;
// Common flag values
const UNSAMPLED = 0x00; // 00000000 - not sampled
const SAMPLED = 0x01; // 00000001 - sampled
// Preserving unknown flags during propagation
const preservedFlags = spanContext.traceFlags | 0x01; // Set sampled bit while preserving others
// W3C traceparent header format includes these flags
const traceparent = `00-${traceId}-${spanId}-${traceFlags.toString(16).padStart(2, '0')}`;
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.
OptionaltraceVendor-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.
key=value separated by commasvendor@system=value)// 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] || '';
An object that can be used to populate a new IDistributedTraceContext instance, the included IW3cTraceState or IOTelTraceState is used as the parent of the created instances traceState