---
title: Tracing
description: Tracing protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

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

<Callout type="info">
**Source:** `packages/spec/src/system/tracing.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { OpenTelemetryCompatibility, OtelExporterType, SamplingDecision, SamplingStrategyType, Span, SpanAttributeValue, SpanAttributes, SpanEvent, SpanKind, SpanLink, SpanStatus, TraceContext, TraceContextPropagation, TraceFlags, TracePropagationFormat, TraceState } from '@objectstack/spec/system';
import type { OpenTelemetryCompatibility, OtelExporterType, SamplingDecision, SamplingStrategyType, Span, SpanAttributeValue, SpanAttributes, SpanEvent, SpanKind, SpanLink, SpanStatus, TraceContext, TraceContextPropagation, TraceFlags, TracePropagationFormat, TraceState } 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 | Description |
| :--- | :--- | :--- | :--- |
| **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`


---

## TraceState

Trace state

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **entries** | `Record<string, string>` | ✅ | Trace state entries |


---

