Trace envelope
The canonical contract for a trace and its flat collection of spans.
The SDK encodes this contract automatically. Other producers send schemaVersion: 1,
producer, and a finalized trace. The trace owns its name/version; each span owns
its agent name/version. There is no separate trace definition or duplicate span name.
Completed example
Save this as trace.json for the upload example.
The model values illustrate a custom provider; preserve your own native data shapes.
{
"producer": {
"serviceName": "my-app",
"sdkVersion": "1.0.0",
"appVersion": "1.0",
"appBuild": "42",
"os": {
"name": "iOS",
"version": "27.0.0",
"build": "24A435"
}
},
"schemaVersion": 1,
"trace": {
"durationMilliseconds": 250,
"endedAt": "2026-08-31T18:00:00.000Z",
"id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"name": "summarize-text",
"startedAt": "2026-08-31T17:59:59.750Z",
"status": "success",
"spans": [
{
"durationMilliseconds": 250,
"endedAt": "2026-08-31T18:00:00.000Z",
"id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
"startedAt": "2026-08-31T17:59:59.750Z",
"status": "success",
"agent": {
"name": "summarizer",
"version": 1
},
"promptTemplate": {
"prompt": "Summarize: {{text}}"
},
"modelInput": {
"prompt": "Summarize: The launch is scheduled for Friday."
},
"modelOutput": {
"text": "Launch is Friday."
},
"input": {
"text": "The launch is scheduled for Friday."
}
}
],
"version": 1,
"input": {
"text": "The launch is scheduled for Friday."
}
}
}Validation
The idempotency key must match the trace ID. Span IDs are unique within a trace. Names contain non-whitespace text and fit within 256 characters; versions are positive 32-bit integers. A finalized trace contains at least one span.
Neither trace nor span may be running at ingestion. End times cannot precede starts.
An interrupted span can omit unknown endedAt and durationMilliseconds; omit both
when there was no observed completion. Trace end can be absent when a span end is unknown.
input is application input. modelInput, modelOutput, and providerCapture retain
native data. These fields, model, and promptTemplate accept JSON values. Omission,
explicit JSON null, and empty values remain distinct. outputReferences maps identifiers
to strings or arbitrary JSON objects, preserving native output unchanged.
The complete schema is TraceEnvelope in OpenAPI.