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 { OpenTelemetryCompatibilitySchema, OtelExporterType, SamplingDecision, SamplingStrategyType, SpanSchema, SpanAttributeValueSchema, SpanAttributesSchema, SpanEventSchema, SpanKind, SpanLinkSchema, SpanStatus, TraceContextSchema, TraceContextPropagationSchema, TraceFlagsSchema, TracePropagationFormat, TraceSamplingConfigSchema, TraceStateSchema, TracingConfigSchema } 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 = OpenTelemetryCompatibilitySchema.parse(data);

OpenTelemetryCompatibility

OpenTelemetry compatibility configuration

Properties

Property	Type	Required	Description
sdkVersion	`string`	optional	OTel SDK version
exporter	`{ type: Enum<'otlp_http' \| 'otlp_grpc' \| 'jaeger' \| 'zipkin' \| 'console' \| 'datadog' \| … +4 more>; endpoint?: string; protocol?: string; headers?: Record<string, string>; … }`	✅	Exporter configuration
resource	`{ serviceName: string; serviceVersion?: string; serviceInstanceId?: string; serviceNamespace?: string; … }`	✅	Resource attributes
instrumentation	`{ autoInstrumentation: boolean; libraries?: string[]; disabledLibraries?: string[] }`	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	`{ traceId: string; spanId: string; traceFlags: integer; traceState?: 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	`{ code: Enum<'unset' \| 'ok' \| 'error'>; message?: string }`	optional
attributes	`Record<string, string \| number \| boolean \| string[] \| number[] \| boolean[]>`	✅	Span attributes
events	`{ name: string; timestamp: string; attributes?: Record<string, string \| number \| boolean \| string[] \| number[] \| boolean[]> }[]`	✅
links	`{ context: object; attributes?: Record<string, string \| number \| boolean \| string[] \| number[] \| boolean[]> }[]`	✅
resource	`Record<string, string \| number \| boolean \| string[] \| number[] \| boolean[]>`	optional	Resource attributes
instrumentationLibrary	`{ name: string; version?: string }`	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[]

SpanAttributes

Span attributes

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	`{ traceId: string; spanId: string; traceFlags: integer; traceState?: 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	`{ entries: Record<string, string> }`	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	`{ traceId?: string; spanId?: string; traceFlags?: string; traceState?: string }`	optional
baggage	`{ enabled: boolean; maxSize: integer; allowedKeys?: string[] }`	optional

TraceFlags

Trace flags bitmap

Type: integer

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	`{ whenParentSampled?: Enum<'always_on' \| 'always_off' \| 'trace_id_ratio' \| 'rate_limiting' \| 'parent_based' \| … +3 more>; whenParentNotSampled?: Enum<'always_on' \| 'always_off' \| 'trace_id_ratio' \| 'rate_limiting' \| 'parent_based' \| … +3 more>; root?: Enum<'always_on' \| 'always_off' \| 'trace_id_ratio' \| 'rate_limiting' \| 'parent_based' \| … +3 more>; rootRatio?: number }`	optional
composite	`{ strategy: Enum<'always_on' \| 'always_off' \| 'trace_id_ratio' \| 'rate_limiting' \| 'parent_based' \| … +3 more>; ratio?: number; condition?: Record<string, any> \| string \| object }[]`	optional
rules	`{ name: string; match?: object; decision: Enum<'drop' \| 'record_only' \| 'record_and_sample'>; rate?: number }[]`	optional
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`	optional
sampling	`{ type: Enum<'always_on' \| 'always_off' \| 'trace_id_ratio' \| 'rate_limiting' \| 'parent_based' \| … +3 more>; ratio?: number; rateLimit?: number; parentBased?: object; … }`	optional	Trace sampling configuration
propagation	`{ formats?: Enum<'w3c' \| 'b3' \| 'b3_multi' \| 'jaeger' \| 'xray' \| 'ottrace' \| 'custom'>[]; extract?: boolean; inject?: boolean; headers?: object; … }`	optional	Trace context propagation
openTelemetry	`{ sdkVersion?: string; exporter: object; resource: object; instrumentation?: object; … }`	optional	OpenTelemetry compatibility configuration
spanLimits	`{ maxAttributes?: integer; maxEvents?: integer; maxLinks?: integer; maxAttributeValueLength?: integer }`	optional
traceIdGenerator	`Enum<'random' \| 'uuid' \| 'custom'>`	optional
customTraceIdGeneratorId	`string`	optional	Custom generator identifier
performance	`{ asyncExport?: boolean; exportInterval?: integer }`	optional

On this page