The article explains how traditional logging falls short when debugging failures in AI agents, especially in high-stakes scenarios where an agent may execute unintended actions such as deleting or modifying critical data.Simple logs that only record that an agent ran or a tool was called provide little insight into why a decision was made.

Instead, the author argues for decision tracing using OpenTelemetry, where every model invocation, tool execution, and retrieval step is represented as a structured span within a trace.

The core idea is to move beyond “heartbeat logging” and instead capture full decision context, including reasoning, tool selection, and the source of context that influenced the decision.By using OpenTelemetry’s GenAI semantic conventions, developers can standardize observability across different systems and avoid vendor lock-in.

Spans such as agent invocation, tool execution, and retrieval are enriched with attributes like model name, token usage, risk level, and especially a context_source field that helps explain where the agent’s decision originated.The article also emphasizes best practices for security and privacy.

It warns against storing full prompt or message content in span attributes due to size limits and privacy risks, recommending span events instead for large or sensitive data.

Additionally, it highlights the importance of propagating trace context across multi-agent systems so that parent-child relationships remain intact when agents delegate tasks.

A key pattern introduced is a decision-logging contract, where the agent must explicitly output structured JSON describing intent, reasoning, risk level, and reversibility before executing sensitive operations like writes or deletions.This enables human approval gates and improves traceability.

Finally, the article discusses operational pitfalls such as incorrect span classification, insufficient retention policies, and insecure recovery systems.

It concludes that proper instrumentation transforms debugging from manual log investigation into structured trace analysis, making it possible to quickly answer what an agent did, why it did it, and what systems it affected.