Hisham Alhussain"Why did it do that?"
If you've built an agent, you've asked this question, probably more times than you'd like. A user reports something weird, and now you have to figure out what happened across a dozen model calls, a handful of tool calls, and some retrieval in the middle.
If all you have is scattered logs, that's an afternoon gone. With proper traces, it's usually a few minutes. That difference is why observability is one of the first things I set up now, not one of the last.
Traces, not logs
Logs tell you individual things happened. Traces tell you the story. For an agent, I want one trace per run that shows every step in order:
- The input, and who or what triggered the run
- Each model call: the full prompt, the response, which model, token counts, latency
- Each tool call: arguments, result, errors, how long it took
- Retrieval: what was searched, what came back, and the scores
- The final outcome, and whether it counted as a success
When you can click through a run step by step and see exactly what the model saw at each point, most bugs become obvious pretty quickly.
Use the standards
There's been good progress on OpenTelemetry conventions for generative AI, and most agent frameworks and observability tools support it now. I'd strongly recommend going that route instead of inventing your own format. It means your agent traces can sit alongside the rest of your system's traces, and you can switch tools later without re-instrumenting everything.
Track the numbers that matter
Beyond individual traces, I keep an eye on a few metrics over time:
- Success or resolution rate, ideally by task type
- Cost per run and per resolved task
- Latency, especially the slow tail, not just the average
- Tool error rates, which often spike before users notice anything
- Steps per run, because a sudden jump usually means the agent is looping or struggling
- Handoff rate to humans, if you have that
When a number moves suddenly, that's your cue to go read some traces.
Be careful with sensitive data
Traces capture everything, which is the point, but it also means they can capture personal or confidential information. Decide early what gets stored, mask or redact sensitive fields, set retention limits, and control who can access the traces. It's much easier to set this up from the start than to clean it up later.
Close the loop
The best part is connecting observability back to evals. When I find a bad run in production, I turn it into an eval case so it can't happen again. Over time, production traces become the best source of test cases you have, because they reflect what real users actually do.
Start today
If you have an agent in production without tracing, add it this week. Even basic tracing beats none. The next time someone asks "why did it do that?", you'll actually be able to answer.