Oh My Learning

Observability for Agents: Tracing, Logging, and Debugging Non-Determinism

agent-security-and-operations/06 staff drafted · 14 min read

OpenTelemetry Blog, AI Agent Observability - Evolving Standards and Best Practices (2025); MLflow, What Is Agent Observability? A 2026 Developer Guide (2026); Uptrace, OpenTelemetry for AI Systems: LLM and Agent Observability (2026); Braintrust, Agent observability: The complete guide for 2026 (2026); Zylos Research, OpenTelemetry for AI Agents: Observability, Tracing, and the GenAI Semantic Conventions (Feb 2026)

Prerequisites multi-agent-orchestration/04

Observability for Agents: Tracing, Logging, and Debugging Non-Determinism#

TL;DR#

Traditional application observability answers "did the request succeed, and how fast" from metrics, logs, and traces built around a mostly deterministic call graph. Agent observability has to answer a harder question - "why did the agent decide to do what it did" - because the same input can produce a different sequence of tool calls on different runs, the trace's shape (not just its duration) varies run to run, and each step carries its own token cost. The infrastructure (spans, trace propagation, structured logging) carries over directly from devops-reliability/sre; what's new is capturing the reasoning and decision content inside each span, not just its timing and status.

The idea#

multi-agent-orchestration/04 established that once agents coordinate - through an orchestrator, shared state, message passing, a task list, or a generator-verifier loop - the coordination mechanism itself determines what's easy versus hard to trace after the fact: an orchestrator-subagent trace reads like a call stack, a message-bus trace has to be reconstructed from scattered publish/subscribe events. Observability is the discipline of actually building that reconstruction - capturing what happened, in what order, why, and at what cost, well enough that a person can debug a specific bad run without having been watching it live.

The reason this is a distinct discipline from conventional application performance monitoring (APM), not just APM applied to a new kind of service, comes down to three properties traditional request/response services don't have. First, non-determinism: the same prompt and the same tools can produce a different tool-call sequence on different runs, because model sampling, retrieved context, or accumulated conversation state differ - so "did this succeed" is not enough, you need "what path did it take to get there," and that path is not reproducible just by replaying the same request the way a deterministic service's request can be replayed. Second, variable-length, variable-shape traces: a conventional service's request handling has a roughly fixed call graph (auth, then business logic, then a database call); an agent's trace can be three steps or thirty depending on what the model decided along the way, so the trace shape itself is a signal, not incidental. Third, cost per trace: every span in an agent trace - every model call, every tool call - carries a real dollar cost (agent-security-and-operations/05), so a useful agent trace has to carry cost alongside latency, something a traditional APM trace generally does not need to track per-span.

How it works#

What traditional APM gets right, and what agents inherit unchanged#

The underlying telemetry infrastructure - distributed tracing with parent/child spans, structured logging correlated by trace ID, metrics aggregation, and the operational disciplines devops-reliability/sre covers (SLIs and SLOs in sre/02-sre/03, monitoring and alerting design in sre/07, incident response in sre/09) - is not reinvented for agents. A trace is still a tree of spans with start/end timestamps and a status; you still want p50/p95/p99 latency (per ddia/01's percentile discipline), still want actionable alerts rather than noisy ones (sre/07's core lesson), still want a blameless postmortem process when an agent-driven incident happens (sre/10). None of that goes away, and building agent observability from scratch instead of on top of this existing infrastructure is a common, avoidable mistake - the transport and storage layer for agent telemetry in 2026 is standardizing on the same OpenTelemetry protocol traditional services already use.

What OpenTelemetry adds for agents specifically. OpenTelemetry's GenAI semantic conventions (an active, evolving specification as of 2026) extend the standard span/trace model with a shared vocabulary for LLM- and agent-specific attributes: LLM client spans (which model, how many input/output tokens, what temperature), agent spans (what the agent's role or task was, what tools were available to it), events for capturing prompt and completion content, and metrics for token usage and cost. The payoff of a shared, vendor-neutral schema is that traces from different agent frameworks can flow into the same observability backend without custom per-framework parsing - the same interoperability benefit standard HTTP or database instrumentation already provides for conventional services.

What's genuinely new: capturing why, not just that#

A conventional trace answers "did the database call succeed, how long did it take." An agent trace, to be useful for debugging, additionally has to answer "why did the agent choose to call this tool with these arguments, instead of a different tool or different arguments" - because the failure being debugged is often not "the tool call errored" (a traditional APM failure) but "the tool call succeeded, and the agent still produced the wrong final answer, because it chose the wrong tool, the wrong arguments, or stopped one step too early." Capturing this means each span needs to carry the model's stated reasoning (or reasoning trace, where the model exposes one) and the actual prompt/completion content leading to that step's decision, not just its timing and outcome status. This is the concrete difference practitioner sources point to for 2026: "logs capture discrete events, not causal chains" - a log line saying "tool X called, returned success" tells you nothing about whether X was the right tool to call, whereas the reasoning content attached to that span tells you what the agent believed when it made that choice.

Worked example. A research agent's final answer cites a stale statistic. Traditional APM-style tracing shows every span green: the search tool executed successfully, the summarization step executed successfully, no error anywhere in the trace - a traditional on-call engineer would see nothing wrong. Reasoning-aware tracing shows the actual sequence: the agent's search-tool span recorded a query for "2023 figures" (not 2026), because an earlier planning span's reasoning content shows it working from a document snippet that itself referenced 2023 data without a date qualifier. The bug is not in any single span's success/failure status - it's a decision made two steps upstream, visible only if the trace captured the reasoning content at each step, not just each step's pass/fail outcome.

Debugging non-determinism: the same input, different runs#

Because two runs of the same agent on the same input can take different paths, a single trace is evidence about one run, not a general guarantee about the agent's behavior on that input class. This changes what "reproducing a bug" means: instead of replaying the exact same request and expecting the exact same trace (the traditional APM debugging move), agent debugging typically means running the same or similar inputs multiple times, and looking at the distribution of trace shapes and outcomes - does the agent take the buggy path 1 time in 20, or 15 times in 20? A trace that only ever gets looked at one run at a time can miss a systematic failure that only shows up statistically.

Worked example, with numbers. A coding agent is reported to occasionally skip running tests before declaring a task complete. Looking at one failing trace shows the skip happening after a step where the agent's reasoning content says "tests likely still pass given the scope of this change" - plausible-sounding, but wrong this time. Running the same task 20 times and aggregating trace outcomes shows the skip happens in 3 of 20 runs (15%), concentrated specifically on tasks where the agent's context includes a prior successful run's test output from several steps earlier - the agent is pattern-matching on stale test results still sitting in its context window rather than genuinely deciding tests are unnecessary. This diagnosis - a systematic bias correlated with a specific context condition - is only visible in the aggregate across many traces, not in any single trace considered in isolation, which is the central reason agent observability needs a mechanism for sampling and clustering many runs, not just deep-diving into one.

Cost as a first-class observability signal#

Because every span in an agent trace can carry a real token cost (agent-security-and-operations/05), cost anomalies are often the earliest visible signal of a functional bug, before the bug manifests as a wrong answer a human notices. A step that suddenly takes 3x its usual token count is frequently also the step where something is going wrong - a retry loop consuming tokens on each failed attempt, or a context-growth bug re-sending more history than intended. Instrumenting cost per span alongside latency per span means an alert on "this task's cost exceeded its usual p95 by 3x" (mirroring sre/07's actionable-alerting discipline, now applied to a cost metric instead of a latency metric) can catch a class of bugs before the budget cap (agent-security-and-operations/05) even has to fire.

High-cardinality filtering: the practical infrastructure need#

2026 practitioner guidance stresses that debugging agent behavior at scale requires filtering traces across high-cardinality dimensions - by tool version, by model version, by which prompt template was in effect, by user segment - because "the agent got confused" is rarely a single universal bug; it's usually correlated with one specific combination of these dimensions (a particular tool version's output format changed, and only agents using that version misbehave). This is the same high-cardinality observability need conventional distributed systems have (filtering by service version, region, or customer tier), applied to the additional dimensions specific to agent stacks - model version and prompt/tool version being the two agents add that a traditional service trace wouldn't need.

Pros#

  • Builds on existing, mature tracing infrastructure (OpenTelemetry, the same backends devops-reliability/sre already uses) rather than requiring a parallel observability stack - the transport and storage layer is shared, only the semantic content of spans is new.
  • Reasoning-content-aware tracing catches an entire class of bugs (wrong decision, right execution) that success/failure-status-only tracing structurally cannot see.
  • Cost-per-span instrumentation doubles as an early warning signal for functional bugs (runaway retries, context growth) well before those bugs manifest as an incorrect final answer.
  • A shared semantic-convention schema (OpenTelemetry's GenAI conventions) means traces are portable across agent frameworks and observability backends, avoiding vendor lock-in on the telemetry layer itself.

Cons#

  • Capturing full reasoning and prompt/completion content in every span is far more data-heavy than status-and-timing telemetry, raising storage cost and, if the content includes sensitive user data, real privacy and data-handling obligations that traditional latency-only traces didn't carry.
  • Debugging non-determinism by aggregating across many runs requires the infrastructure and discipline to run and cluster many traces, not just deep-dive one - a capability most teams' existing APM tooling was never built for.
  • The GenAI semantic-convention standard was still actively evolving as of 2026, meaning schemas and instrumentation libraries can shift under a team that adopts early, unlike the long-stable conventions for HTTP or database spans.
  • A trace that captures everything (full reasoning, full prompt content, every retry) at every step, for every run, at production volume, can itself become expensive enough that teams reflexively sample it down - and naive sampling can discard exactly the rare, low-frequency failure paths that aggregate-across-runs debugging depends on catching.

Alternatives#

  • Evaluation-only telemetry (offline eval suites, no live tracing) - run the agent against a fixed test set and score outcomes, without instrumenting live production traces at all. Cheaper and simpler, but blind to failures that only appear on real, unanticipated production inputs - a complement to live tracing (see agent-evaluation/04), not a substitute for it.
  • Status-and-latency-only tracing (skip reasoning content) - instrument agent spans the same way a conventional service is instrumented, capturing timing and success/failure but not the reasoning or prompt content behind each decision. Cheaper to store and simpler to build, but reproduces exactly the blind spot this lesson describes: every span can be green while the agent is still wrong.
  • Human-reviewed transcripts instead of structured tracing - have a person read the raw conversation/tool-call transcript of flagged runs rather than building structured, queryable trace infrastructure. Viable at very low volume; does not scale to the aggregate-across-many-runs analysis that catching systematic, low-frequency non-determinism requires.

When to use it#

Instrument full reasoning-and-content-aware tracing for any agent making consequential decisions in production - anywhere a wrong tool choice or wrong reasoning step could produce an incorrect action a human would need to debug after the fact. Prioritize capturing reasoning content and cost per span from the start rather than retrofitting it later; retrofitting means every prior incident is undebuggable from its trace alone. Build the capability to run and aggregate multiple traces per input class specifically for agents suspected of, or at risk of, non-deterministic failure patterns - not just spot-checking single traces.

When NOT to use it#

Do not instrument full prompt/completion content capture for agents handling sensitive personal data without first working through the data-handling and retention obligations that content implies - a trace that faithfully captures everything the agent saw and said can itself become a compliance liability if it's storing content that shouldn't be retained at that granularity or for that long. Do not treat a single successful trace as proof an agent is reliable on that input class - given genuine non-determinism, one green trace is one data point, not a guarantee; reserve strong reliability claims for outcomes verified across many runs. Do not build a bespoke, from-scratch tracing stack when the underlying transport, storage, and alerting infrastructure your organization already runs (per devops-reliability/sre) can be extended with GenAI-specific span attributes instead. And do not over-instrument low-stakes, low-volume agent uses (an internal scratch tool a single engineer runs occasionally) with the full reasoning-capture-and-multi-run-aggregation apparatus described above - that machinery earns its cost at production scale, where systematic, low-frequency, hard-to-reproduce failures are the actual risk; for a low-stakes tool, ordinary status-and-latency tracing plus occasional manual transcript review is proportionate.

Key takeaways / mental model#

Agent observability keeps everything conventional distributed tracing already does well (spans, trace IDs, percentile latency, actionable alerting, blameless postmortems - all of devops-reliability/sre's toolkit) and adds three things traditional APM was never built for: capturing why a step happened (reasoning and prompt content, not just status), treating trace shape itself as a signal because it varies run to run under genuine non-determinism, and treating cost per span as a first-class metric because every step has a real dollar price. The central debugging shift: a single green trace proves one run succeeded, not that the agent is reliable on that input class - real confidence about non-deterministic behavior comes from the distribution across many runs, not any one of them.

Self-check questions#

  1. A trace shows every span succeeding (no errors, all tools returned valid results) but the agent's final answer was still wrong. Explain why this is possible for an agent in a way it typically isn't for a conventional deterministic service, and what kind of span content would have caught it.
  2. What does OpenTelemetry's GenAI semantic conventions effort add on top of standard distributed tracing, and why does a shared, vendor-neutral schema matter specifically for agent observability?
  3. Your team suspects an agent has a rare, non-deterministic failure mode but every trace you've individually reviewed looks fine. What's wrong with the debugging approach, and what would you do differently?
  4. Explain why cost-per-span can serve as an early warning signal for a functional bug, using a concrete example different from the ones in this lesson.
  5. A compliance team objects to capturing full prompt/completion content in every production trace for an agent handling customer PII. What's the actual tension here, and what would you propose that preserves most of the debugging value without ignoring the objection?
  6. Contrast what stays the same versus what's genuinely new when moving from devops-reliability/sre's monitoring-and-alerting discipline (sre/07) to agent observability. Which specific SRE practices carry over unchanged, and which need a new mechanism?

References#