What a Good Agent Trace Looks Like: A Reference Schema

A trace is a familiar concept: a tree of spans showing what a request did and how long each part took. This whitepaper keeps that basic model, but argues it isn't enough for AI agents, and lays out a concrete schema to close the gap.

The schema is built as a practical extension to the OpenTelemetry GenAI semantic conventions. It's written to be implemented directly: every field is intended to be emitted by a production agent runtime, and every design rule is tied to the operational question it's meant to answer.

Why Normal Tracing Falls Short

Conventional tracing was built for services whose behavior is fixed by their code — knowing the input and the version is usually enough to know what happened. So a normal trace only records what varies between requests: timings, IDs, status codes.

An AI agent breaks that assumption. Its code is small and stable, but its behavior is decided at runtime by a model reading its context - the prompt, the retrieved documents, the tool results, the earlier turns. That context effectively becomes the program, and a conventional trace has nowhere to record it. Five agent properties, in particular, leave normal tracing silent:

• The context is the program — if the prompt version, retrieved documents, and tool schemas aren't captured on the span, you're missing the equivalent of unreadable source code.
• Same input, different path — a run can't be reproduced from the request alone; you need everything the model actually saw.
• It considers options and drops most of them — the road not taken is usually the one under review, and normal tracing has nowhere to put it.
• Humans are part of the run — approvals, edits, and rejections happen inside the flow, and their reasons are often the most valuable signal available.
• Every step has a price and a privacy risk — cost and redaction need to work per span, not just per run.

What This Schema Adds

On top of a standard trace, the schema introduces four capabilities:

• Skipped options as spans. When an agent considers several options and acts on only one, the rejected paths still appear in the trace, each with a reason code explaining why it wasn't taken. "Why didn't it do X" becomes something you can filter for, rather than something you have to investigate.
• Human overrides as spans with a required reason. Every approval, edit, rejection, or escalation is logged with who acted, what changed, and a reason code drawn from a fixed list - enough to tell "the agent is drifting" apart from "the policy changed."
• Cost on every span. Not just the run total, but the cost of each individual step, making it possible to trace exactly which call - a retrieval, a tool, a model response - drove up spend.
• Redaction and retention set per span type. Prompt and output content is scrubbed of personal data and kept for 30 days; human decisions are kept for six months or more; timings and counts are kept for a year.

Everything else follows the OpenTelemetry GenAI conventions as-is. Where a standard field name already exists, the schema uses it; where the standard is silent, it adds a field under a dedicated agent.* namespace, so that any concept the standard later adopts can be migrated with a single rename.

What's Inside This Whitepaper

The document is organized into thirteen sections, building from problem to implementation:

• Sections 1–3 lay out the problem agent tracing faces and the six design rules the schema follows.
• Sections 4–5 define the shape of a trace - sessions, traces, spans, and events, and give the full field-by-field specification for each of the nine span kinds.
• Sections 6–10 cover the schema's four core additions in depth: skipped options, human overrides, per-span cost, and per-span redaction and retention.
• Sections 11–13 close with a fully worked example (spans and an equivalent log stream), a mapping table back to the OpenTelemetry GenAI conventions, and a staged, three-level adoption path with a day-by-day rollout plan and an implementation checklist.

About Blue Data Consulting

Blue Data Consulting is a B2B enterprise AI and IT consulting firm operating across India, Malaysia, and the UAE. The firm helps organizations in the telecom, semiconductor, and healthcare sectors build and deploy enterprise-grade AI systems, from infrastructure design and model integration to governance frameworks and workforce enablement. Its two practice areas are Enterprise IT Solutions (AI platform architecture, systems integration, production deployment) and Enterprise Upskilling and Corporate Training (helping technical and business teams operate AI systems responsibly and effectively). This whitepaper is part of Blue Data's ongoing technical publishing programme, focused on research and reference specifications that practitioners can implement directly.

Get in Touch

If your team is running AI agents in production and can't yet answer "what did it see, why did it do that, what did it cost, and who stepped in", this schema is built to close that gap. Reach out to Blue Data Consulting to discuss how to bring agent observability into your own stack, or to get support implementing this schema end to end.

Contact Us