Trace Schema

A trace envelope that separates infrastructure, model, tool, policy, business-outcome, and evaluation telemetry.

Audience: Platform engineers; SRE; observability and evaluation teams Reading time: 3 minutes Status: Production guidance Last reviewed: 2026-06-23 UTC

Trace correlation should connect runtime layers without assuming every organization may retain raw prompts, retrieved documents, tool payloads, or personal data.

Status and scope

Status: Production guidance
Schema dialect: JSON Schema Draft 2020-12
Reviewed: 2026-06-23 UTC

Trace and correlation identifiers, UTC span timing, sampling, typed span groups, policy decisions, outcomes, evaluations, and redaction posture.

Download JSON Schema Open examples

Fields

Trace Envelope v1
Field	Type	Required	Contract meaning
`schemaVersion`	constant	Yes	See the schema constraints and examples for this versioned field. Required value: aruntime.trace-envelope.v1.
`traceId`	string	Yes	See the schema constraints and examples for this versioned field.
`correlationId`	string	Yes	See the schema constraints and examples for this versioned field.
`startedUtc`	string	Yes	UTC ISO 8601 timestamp ending in Z.
`endedUtc`	string	Yes	UTC ISO 8601 timestamp ending in Z.
`sampling`	enum	Yes	See the schema constraints and examples for this versioned field. Allowed values: record-only, sampled, dropped-details.
`infrastructureSpans`	array	Yes	See the schema constraints and examples for this versioned field.
`modelSpans`	array	Yes	See the schema constraints and examples for this versioned field.
`toolSpans`	array	Yes	See the schema constraints and examples for this versioned field.
`policyDecisions`	array	Yes	See the schema constraints and examples for this versioned field.
`businessOutcomes`	array	Yes	See the schema constraints and examples for this versioned field.
`evaluationResults`	array	Yes	See the schema constraints and examples for this versioned field.
`redaction`	object	Yes	See the schema constraints and examples for this versioned field.

Versioning and compatibility rules

Use W3C Trace Context or an equivalent organization-wide propagation mechanism at process boundaries.
Infrastructure, model, and tool spans remain distinct so access controls and retention can differ.
Business outcomes and offline evaluation can be attached after request completion using the correlation identifier.

Validation and error behavior

Validate the complete envelope before model execution or credential resolution. Return a stable machine code, a safe human explanation, the failing JSON Pointer, and the supported contract versions. Never “repair” missing authority or risk fields with model-generated values.

{
  "error": {
    "code": "contract-validation-failed",
    "contractVersion": "v1",
    "path": "/idempotencyKey",
    "message": "A stable idempotency key is required.",
    "retryable": false
  }
}

Security, redaction, and minimization

Do not use span attributes as an unrestricted payload store.
Raw prompts, retrieved records, tool payloads, and model outputs require explicit field-level approval and redaction.
Sampling decisions must not create blind spots for mandatory policy or side-effect evidence.

Validated examples

Correlated request and model spans

Download this example

{
    "schemaVersion": "aruntime.trace-envelope.v1",
    "traceId": "0123456789abcdef0123456789abcdef",
    "correlationId": "corr_20260623_001",
    "startedUtc": "2026-06-23T14:30:00Z",
    "endedUtc": "2026-06-23T14:30:08Z",
    "sampling": "sampled",
    "infrastructureSpans": [
        {
            "spanId": "0123456789abcdef",
            "parentSpanId": null,
            "name": "runtime.request",
            "startedUtc": "2026-06-23T14:30:00Z",
            "endedUtc": "2026-06-23T14:30:08Z",
            "status": "ok",
            "attributes": {
                "runtime.route": "hosted-general-v3"
            }
        }
    ],
    "modelSpans": [
        {
            "spanId": "1111111111111111",
            "parentSpanId": "0123456789abcdef",
            "name": "model.generate",
            "startedUtc": "2026-06-23T14:30:02Z",
            "endedUtc": "2026-06-23T14:30:07Z",
            "status": "ok",
            "attributes": {
                "model.deployment": "deploy:2026-06-20.1",
                "gen_ai.usage.output_tokens": 412
            }
        }
    ],
    "toolSpans": [],
    "policyDecisions": [
        {
            "decision": "allow"
        }
    ],
    "businessOutcomes": [],
    "evaluationResults": [
        {
            "evaluator": "citation-completeness.v2",
            "score": 1
        }
    ],
    "redaction": {
        "rawPromptsStored": false,
        "rules": [
            "omit-raw-input"
        ]
    }
}

Reference implementation

The bundled PHP 8.1 example validates admission fields, selects a constrained model route, checks tool permission and approval requirements, performs an idempotent synthetic operation, creates minimized evidence, handles errors, and prints expected JSON output.

Download the runnable PHP example

php examples/php/runtime_pipeline.php

Find runtime definitions and implementation guidance