Tracing

Tracing Protocol - Distributed Tracing & Observability

Comprehensive distributed tracing based on OpenTelemetry standards:

Trace context propagation
Span creation and management
Sampling strategies
Integration with tracing backends (Jaeger, Zipkin, etc.)
W3C Trace Context standard compliance

Source: packages/spec/src/system/tracing.zod.ts

TypeScript Usage

import { OpenTelemetryCompatibility, OtelExporterType, SamplingDecision, SamplingStrategyType, Span, SpanAttributeValue, SpanAttributes, SpanEvent, SpanKind, SpanLink, SpanStatus, TraceContext, TraceContextPropagation, TraceFlags, TracePropagationFormat, TraceSamplingConfig, TraceState, TracingConfig } from '@objectstack/spec/system';
import type { OpenTelemetryCompatibility, OtelExporterType, SamplingDecision, SamplingStrategyType, Span, SpanAttributeValue, SpanAttributes, SpanEvent, SpanKind, SpanLink, SpanStatus, TraceContext, TraceContextPropagation, TraceFlags, TracePropagationFormat, TraceSamplingConfig, TraceState, TracingConfig } from '@objectstack/spec/system';

// Validate data
const result = OpenTelemetryCompatibility.parse(data);

OpenTelemetryCompatibility

OpenTelemetry compatibility configuration

Properties

Property	Type	Required	Description
sdkVersion	`string`	optional	OTel SDK version
exporter	`Object`	✅	Exporter configuration
resource	`Object`	✅	Resource attributes
instrumentation	`Object`	optional
semanticConventionsVersion	`string`	optional	Semantic conventions version

OtelExporterType

OpenTelemetry exporter type

Allowed Values

otlp_http
otlp_grpc
jaeger
zipkin
console
datadog
honeycomb
lightstep
newrelic
custom

SamplingDecision

Sampling decision

Allowed Values

drop
record_only
record_and_sample

SamplingStrategyType

Sampling strategy type

Allowed Values

always_on
always_off
trace_id_ratio
rate_limiting
parent_based
probability
composite
custom

Span

OpenTelemetry span

Properties

Property	Type	Required	Description
context	`Object`	✅	Trace context
name	`string`	✅	Span name
kind	`Enum<'internal' \| 'server' \| 'client' \| 'producer' \| 'consumer'>`	✅	Span kind
startTime	`string`	✅	Span start time
endTime	`string`	optional	Span end time
duration	`number`	optional	Duration in milliseconds
status	`Object`	optional
attributes	`Record<string, string \| number \| boolean \| string[] \| number[] \| boolean[]>`	✅	Span attributes
events	`Object[]`	✅
links	`Object[]`	✅
resource	`Record<string, string \| number \| boolean \| string[] \| number[] \| boolean[]>`	optional	Resource attributes
instrumentationLibrary	`Object`	optional

SpanAttributeValue

Span attribute value

Union Options

This schema accepts one of the following structures:

Option 1

Type: string

Option 2

Type: number

Option 3

Type: boolean

Option 4

Type: string[]

Option 5

Type: number[]

Option 6

Type: boolean[]

SpanEvent

Span event

Properties

Property	Type	Required	Description
name	`string`	✅	Event name
timestamp	`string`	✅	Event timestamp
attributes	`Record<string, string \| number \| boolean \| string[] \| number[] \| boolean[]>`	optional	Event attributes

SpanKind

Span kind

Allowed Values

internal
server
client
producer
consumer

SpanLink

Span link

Properties

Property	Type	Required	Description
context	`Object`	✅	Linked trace context
attributes	`Record<string, string \| number \| boolean \| string[] \| number[] \| boolean[]>`	optional	Link attributes

SpanStatus

Span status

Allowed Values

unset
ok
error

TraceContext

Trace context (W3C Trace Context)

Properties

Property	Type	Required	Description
traceId	`string`	✅	Trace ID (32 hex chars)
spanId	`string`	✅	Span ID (16 hex chars)
traceFlags	`integer`	✅	Trace flags bitmap
traceState	`Object`	optional	Trace state
parentSpanId	`string`	optional	Parent span ID (16 hex chars)
sampled	`boolean`	✅
remote	`boolean`	✅

TraceContextPropagation

Trace context propagation

Properties

Property	Type	Required
formats	`Enum<'w3c' \| 'b3' \| 'b3_multi' \| 'jaeger' \| 'xray' \| 'ottrace' \| 'custom'>[]`	✅
extract	`boolean`	✅
inject	`boolean`	✅
headers	`Object`	optional
baggage	`Object`	optional

TracePropagationFormat

Trace propagation format

Allowed Values

w3c
b3
b3_multi
jaeger
xray
ottrace
custom

TraceSamplingConfig

Trace sampling configuration

Properties

Property	Type	Required	Description
type	`Enum<'always_on' \| 'always_off' \| 'trace_id_ratio' \| 'rate_limiting' \| 'parent_based' \| 'probability' \| 'composite' \| 'custom'>`	✅	Sampling strategy
ratio	`number`	optional	Sample ratio (0-1)
rateLimit	`number`	optional	Traces per second
parentBased	`Object`	optional
composite	`Object[]`	optional
rules	`Object[]`	✅
customSamplerId	`string`	optional	Custom sampler identifier

TraceState

Trace state

Properties

Property	Type	Required	Description
entries	`Record<string, string>`	✅	Trace state entries

TracingConfig

Tracing configuration

Properties

Property	Type	Required	Description
name	`string`	✅	Configuration name (snake_case, max 64 chars)
label	`string`	✅	Display label
enabled	`boolean`	✅
sampling	`Object`	✅	Trace sampling configuration
propagation	`Object`	✅	Trace context propagation
openTelemetry	`Object`	optional	OpenTelemetry compatibility configuration
spanLimits	`Object`	optional
traceIdGenerator	`Enum<'random' \| 'uuid' \| 'custom'>`	✅
customTraceIdGeneratorId	`string`	optional	Custom generator identifier
performance	`Object`	optional

On this page