ObjectStackObjectStack

Tracing

Tracing protocol schemas

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

PropertyTypeRequiredDescription
sdkVersionstringoptionalOTel SDK version
exporter{ type: Enum<'otlp_http' | 'otlp_grpc' | 'jaeger' | 'zipkin' | 'console' | 'datadog' | …>; 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
semanticConventionsVersionstringoptionalSemantic conventions version

Nested Shape: OpenTelemetryCompatibility.exporter

PropertyTypeRequiredDescription
typeEnum<'otlp_http' | 'otlp_grpc' | 'jaeger' | 'zipkin' | 'console' | 'datadog' | …>✅Exporter type
endpointstringoptionalExporter endpoint
protocolstringoptionalProtocol version
headersRecord<string, string>optionalHTTP headers
timeoutintegeroptional (default: 10000)
compressionEnum<'none' | 'gzip'>optional (default: "none")
batch{ maxBatchSize: integer; maxQueueSize: integer; exportTimeout: integer; scheduledDelay: integer }optional

Nested Shape: OpenTelemetryCompatibility.resource

PropertyTypeRequiredDescription
serviceNamestring✅Service name
serviceVersionstringoptionalService version
serviceInstanceIdstringoptionalService instance ID
serviceNamespacestringoptionalService namespace
deploymentEnvironmentstringoptionalDeployment environment
attributesRecord<string, string | number | boolean | string[] | number[] | boolean[]>optionalAdditional resource attributes

Nested Shape: OpenTelemetryCompatibility.instrumentation

PropertyTypeRequiredDescription
autoInstrumentationbooleanoptional (default: true)
librariesstring[]optionalEnabled libraries
disabledLibrariesstring[]optionalDisabled libraries

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

PropertyTypeRequiredDescription
context{ traceId: string; spanId: string; traceFlags: integer; traceState?: object; … }✅Trace context
namestring✅Span name
kindEnum<'internal' | 'server' | 'client' | 'producer' | 'consumer'>optional (default: "internal")Span kind
startTimestring✅Span start time
endTimestringoptionalSpan end time
durationnumberoptionalDuration in milliseconds
status{ code: Enum<'unset' | 'ok' | 'error'>; message?: string }optional
attributesRecord<string, string | number | boolean | string[] | number[] | boolean[]>optional (default: {})Span attributes
events{ name: string; timestamp: string; attributes?: Record<string, string | number | boolean | string[] | number[] | boolean[]> }[]optional (default: [])
links{ context: object; attributes?: Record<string, string | number | boolean | string[] | number[] | boolean[]> }[]optional (default: [])
resourceRecord<string, string | number | boolean | string[] | number[] | boolean[]>optionalResource attributes
instrumentationLibrary{ name: string; version?: string }optional

Nested Shape: Span.context

PropertyTypeRequiredDescription
traceIdstring✅Trace ID (32 hex chars)
spanIdstring✅Span ID (16 hex chars)
traceFlagsintegeroptional (default: 1)Trace flags bitmap
traceState{ entries: Record<string, string> }optionalTrace state
parentSpanIdstringoptionalParent span ID (16 hex chars)
sampledbooleanoptional (default: true)
remotebooleanoptional (default: false)

Nested Shape: Span.status

PropertyTypeRequiredDescription
codeEnum<'unset' | 'ok' | 'error'>✅Status code
messagestringoptionalStatus message

Nested Shape: Span.events[number]

Span event

PropertyTypeRequiredDescription
namestring✅Event name
timestampstring✅Event timestamp
attributesRecord<string, string | number | boolean | string[] | number[] | boolean[]>optionalEvent attributes

Nested Shape: Span.links[number]

Span link

PropertyTypeRequiredDescription
context{ traceId: string; spanId: string; traceFlags: integer; traceState?: object; … }✅Linked trace context
attributesRecord<string, string | number | boolean | string[] | number[] | boolean[]>optionalLink attributes

Nested Shape: Span.instrumentationLibrary

PropertyTypeRequiredDescription
namestring✅Library name
versionstringoptionalLibrary version

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

Type: Record<string, string | number | boolean | string[] | number[] | boolean[]>

SpanEvent

Span event

Properties

PropertyTypeRequiredDescription
namestring✅Event name
timestampstring✅Event timestamp
attributesRecord<string, string | number | boolean | string[] | number[] | boolean[]>optionalEvent attributes

SpanKind

Span kind

Allowed Values

  • internal
  • server
  • client
  • producer
  • consumer

Span link

Properties

PropertyTypeRequiredDescription
context{ traceId: string; spanId: string; traceFlags: integer; traceState?: object; … }✅Linked trace context
attributesRecord<string, string | number | boolean | string[] | number[] | boolean[]>optionalLink attributes

Nested Shape: SpanLink.context

PropertyTypeRequiredDescription
traceIdstring✅Trace ID (32 hex chars)
spanIdstring✅Span ID (16 hex chars)
traceFlagsintegeroptional (default: 1)Trace flags bitmap
traceState{ entries: Record<string, string> }optionalTrace state
parentSpanIdstringoptionalParent span ID (16 hex chars)
sampledbooleanoptional (default: true)
remotebooleanoptional (default: false)

SpanStatus

Span status

Allowed Values

  • unset
  • ok
  • error

TraceContext

Trace context (W3C Trace Context)

Properties

PropertyTypeRequiredDescription
traceIdstring✅Trace ID (32 hex chars)
spanIdstring✅Span ID (16 hex chars)
traceFlagsintegeroptional (default: 1)Trace flags bitmap
traceState{ entries: Record<string, string> }optionalTrace state
parentSpanIdstringoptionalParent span ID (16 hex chars)
sampledbooleanoptional (default: true)
remotebooleanoptional (default: false)

Nested Shape: TraceContext.traceState

PropertyTypeRequiredDescription
entriesRecord<string, string>✅Trace state entries

TraceContextPropagation

Trace context propagation

Properties

PropertyTypeRequiredDescription
formatsEnum<'w3c' | 'b3' | 'b3_multi' | 'jaeger' | 'xray' | 'ottrace' | 'custom'>[]optional (default: ["w3c"])
extractbooleanoptional (default: true)
injectbooleanoptional (default: true)
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

PropertyTypeRequiredDescription
typeEnum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | 'probability' | 'composite' | 'custom'>✅Sampling strategy
rationumberoptionalSample ratio (0-1)
rateLimitnumberoptionalTraces per second
parentBased{ whenParentSampled?: Enum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>; whenParentNotSampled?: Enum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>; root?: Enum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>; rootRatio?: number }optional
composite{ strategy: Enum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>; 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 (default: [])
customSamplerIdstringoptionalCustom sampler identifier

Nested Shape: TraceSamplingConfig.parentBased

PropertyTypeRequiredDescription
whenParentSampledEnum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>optional (default: "always_on")Sampling strategy type
whenParentNotSampledEnum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>optional (default: "always_off")Sampling strategy type
rootEnum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>optional (default: "trace_id_ratio")Sampling strategy type
rootRationumberoptional (default: 0.1)

Nested Shape: TraceSamplingConfig.composite[number]

PropertyTypeRequiredDescription
strategyEnum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>✅Strategy type
rationumberoptional
conditionRecord<string, any> | string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object }optionalCondition for this strategy — structured filter or CEL predicate

Nested Shape: TraceSamplingConfig.rules[number]

PropertyTypeRequiredDescription
namestring✅Rule name
match{ service?: string; spanName?: string; attributes?: Record<string, any> }optional
decisionEnum<'drop' | 'record_only' | 'record_and_sample'>✅Sampling decision
ratenumberoptional

TraceState

Trace state

Properties

PropertyTypeRequiredDescription
entriesRecord<string, string>✅Trace state entries

TracingConfig

Tracing configuration

Properties

PropertyTypeRequiredDescription
namestring✅Configuration name (snake_case, max 64 chars)
labelstring✅Display label
enabledbooleanoptional (default: true)
sampling{ type: Enum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>; ratio?: number; rateLimit?: number; parentBased?: object; … }optionalTrace sampling configuration
propagation{ formats?: Enum<'w3c' | 'b3' | 'b3_multi' | 'jaeger' | 'xray' | 'ottrace' | 'custom'>[]; extract?: boolean; inject?: boolean; headers?: object; … }optional (default: {"formats":["w3c"],"extract":true,"inject":true})Trace context propagation
openTelemetry{ sdkVersion?: string; exporter: object; resource: object; instrumentation?: object; … }optionalOpenTelemetry compatibility configuration
spanLimits{ maxAttributes?: integer; maxEvents?: integer; maxLinks?: integer; maxAttributeValueLength?: integer }optional
traceIdGeneratorEnum<'random' | 'uuid' | 'custom'>optional (default: "random")
customTraceIdGeneratorIdstringoptionalCustom generator identifier
performance{ asyncExport?: boolean; exportInterval?: integer }optional

Nested Shape: TracingConfig.sampling

PropertyTypeRequiredDescription
typeEnum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>✅Sampling strategy
rationumberoptionalSample ratio (0-1)
rateLimitnumberoptionalTraces per second
parentBased{ whenParentSampled?: Enum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>; whenParentNotSampled?: Enum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>; root?: Enum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>; rootRatio?: number }optional
composite{ strategy: Enum<'always_on' | 'always_off' | 'trace_id_ratio' | 'rate_limiting' | 'parent_based' | …>; 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 (default: [])
customSamplerIdstringoptionalCustom sampler identifier

Nested Shape: TracingConfig.openTelemetry

PropertyTypeRequiredDescription
sdkVersionstringoptionalOTel SDK version
exporter{ type: Enum<'otlp_http' | 'otlp_grpc' | 'jaeger' | 'zipkin' | 'console' | 'datadog' | …>; 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
semanticConventionsVersionstringoptionalSemantic conventions version

On this page

TypeScript UsageOpenTelemetryCompatibilityPropertiesNested Shape: OpenTelemetryCompatibility.exporterNested Shape: OpenTelemetryCompatibility.resourceNested Shape: OpenTelemetryCompatibility.instrumentationOtelExporterTypeAllowed ValuesSamplingDecisionAllowed ValuesSamplingStrategyTypeAllowed ValuesSpanPropertiesNested Shape: Span.contextNested Shape: Span.statusNested Shape: Span.events[number]Nested Shape: Span.links[number]Nested Shape: Span.instrumentationLibrarySpanAttributeValueUnion OptionsOption 1Option 2Option 3Option 4Option 5Option 6SpanAttributesSpanEventPropertiesSpanKindAllowed ValuesSpanLinkPropertiesNested Shape: SpanLink.contextSpanStatusAllowed ValuesTraceContextPropertiesNested Shape: TraceContext.traceStateTraceContextPropagationPropertiesTraceFlagsTracePropagationFormatAllowed ValuesTraceSamplingConfigPropertiesNested Shape: TraceSamplingConfig.parentBasedNested Shape: TraceSamplingConfig.composite[number]Nested Shape: TraceSamplingConfig.rules[number]TraceStatePropertiesTracingConfigPropertiesNested Shape: TracingConfig.samplingNested Shape: TracingConfig.openTelemetry