Working premise
A trace is more than a chronological log. It must preserve the causal path from user request to agent outcome while keeping stable identifiers for sessions, releases, prompts, models, tools, and evaluations.
Operational context
Agent traces must explain causality, not merely chronology. An operator needs to see which instruction, retrieved item, model call, tool result, retry, and policy decision contributed to the final outcome. That requires stable boundaries for sessions, traces, spans, and events before individual framework hooks are added.
The schema should separate searchable metadata from sensitive payloads. Low-cardinality attributes such as environment, release, feature, model, prompt version, and outcome support filtering and aggregation. Full prompts, documents, tool arguments, and model responses need stricter collection, redaction, access, and retention rules.
Semantic conventions will evolve, especially for generative AI. A production design should record its convention version and keep an internal translation layer so instrumentation can migrate without breaking historical analysis or forcing every application team to update at once.
Questions to resolve first
Where does one user task begin and end when work continues asynchronously?
Which operations require spans, and which point-in-time facts belong as events?
Which attributes must be present at span start for sampling or routing decisions?
Which payload fields may never leave the application boundary?
Recommended method
- P1
Define session, trace, and span boundaries before instrumenting individual libraries.
- P2
Use stable attributes for application, environment, release, feature, model, and prompt version.
- P3
Represent retrieval and tool activity as first-class spans with inputs, outputs, status, and duration.
- P4
Attach evaluation scores and user feedback without rewriting the original execution record.
Common failure modes
Logs show what happened but cannot reconstruct parent-child relationships, retries, or parallel tool execution.
Teams export complete prompts and documents before defining purpose, access, or redaction.
Attributes mirror one SDK so model or framework changes destroy longitudinal comparability.
Control points
- Apply allowlists and redaction before telemetry leaves the application boundary.
- Keep correlation identifiers stable across asynchronous jobs and external tool calls.
- Record retry relationships so cost and latency are not misattributed.
- Version semantic conventions and validate instrumentation in CI.
Implementation sequence
- S1
Draw representative synchronous, asynchronous, retrieval, and tool-use trajectories and mark the required correlation boundaries.
- S2
Publish a minimal required attribute contract plus optional payload fields and explicit stability levels.
- S3
Add schema validation and trace-completeness tests to CI using known agent trajectories.
- S4
Measure collector loss, orphan spans, cardinality, and payload access after rollout, then tune sampling separately from schema quality.
Measures worth reviewing
Trace completeness should be evaluated against expected operations for a known trajectory. Orphan spans, missing versions, and unattributed token or tool cost indicate a broken evidence chain even when traces are technically ingesting.
Primary references
This note is an editorial synthesis of public standards, primary institutional guidance, and common engineering control patterns. It is intended to support engineering design and review. It is not a substitute for legal, security, safety, audit, or other professional advice for a specific system.