Observability & Evaluation · Data artifact

Trace Schema

Data artifactObservability & EvaluationObservability & Evaluationarc:TraceSchema

A structured contract defining hierarchical spans (start/end time, metadata, parent-child links, trace IDs) and the per-span fields agent traces must carry, aligned with OpenTelemetry semantic conventions.

Responsibility. Defines the span structure and attributes every agent trace event must conform to.

Also known as: Span model, Trace data model, OpenTelemetry semantic conventions, Span hierarchy, Run hierarchy

Direct neighbourhood (hover for relationship types)

Relationships

configures structural

Design guidance

SHOULD follow OpenTelemetry semantic conventions so agent traces integrate with existing enterprise observability backends.
MUST record temporal data, token consumption, tool name/parameters/raw outputs/errors, state before and after each operation, and concurrency overlap per span.
SHOULD record agent reasoning (thoughts) as trace events, not only external function calls.
SHOULD log raw tool outputs alongside the agent's subsequent reasoning to enable cross-reference validation.
SHOULD mirror the execution flow as a parent-child span hierarchy in which child spans inherit the parent context.
SHOULD nest runs as conversation > agent decision > LLM call / tool invocation > final response, recording inputs/outputs, duration, tokens, cost, errors and metadata (Ref8.01).
SHOULD record static properties as span attributes and dynamic occurrences (agent failures, version conflicts, slow dependencies) as timestamped span events.
SHOULD record the shared-state version read and written in state-access spans to expose race conditions.

Quantitative guidance

As stated by the sources; verify before use.

A single agent execution may generate 50+ spans across workflow, agent and tool layers; complex production workflows may generate hundreds (Ch3.6).

Classification

Patterns: Hierarchical span structureThought-Action-Observation trace eventsWorkflow/agent/tool instrumentation layers
Technologies: OpenTelemetry
Quality attributes: Compatibility (ISO/IEC 25010)Maintainability (ISO/IEC 25010)
Risks mitigated: Vendor lock-in to a dedicated observability stackInvisible decision points
Frameworks & regulations: OpenTelemetry semantic conventions

Sources

Ch3.6: T. Nguyen, "Trace Analysis and Execution Debugging," in Mastering Agentic AI Systems: Guide for the NVIDIA NCP-AAI Exam, 1st ed. 2026, ch. 3.6. ISBN: 9798244538229.
Ch8.1: T. Nguyen, "Latency Metrics," in Mastering Agentic AI Systems: Guide for the NVIDIA NCP-AAI Exam, 1st ed. 2026, ch. 8.1. ISBN: 9798244538229.
Ch8.2A: T. Nguyen, "Error Rates and Reliability," in Mastering Agentic AI Systems: Guide for the NVIDIA NCP-AAI Exam, 1st ed. 2026, ch. 8.2A. ISBN: 9798244538229.
Ref8.01: LangChain, "LangSmith observability: AI agent observability platform," LangChain. Accessed: Sep. 27, 2026. [Online]. Available: https://www.langchain.com/langsmith/observability