When a coding agent goes wrong, the final answer is rarely where the problem lives. The failure sits somewhere in the middle: a tool call with the wrong arguments, a test run that errored and was ignored, a retry loop, a step that quietly returned nothing. Five logging habits make those middle steps visible: structured fields, trace and span correlation, tool-step recording, timing and outcome capture, and deliberate control over what content you store.
These five are an editorial synthesis built on OpenTelemetry’s logging and tracing guidance and on the tracing documentation for the OpenAI Agents SDK and VS Code. They are not a published standard, and no source tests them together. Treat them as a practical checklist, not a benchmark-proven recipe.
As an Amazon Associate I earn from qualifying purchases.
Why plain logs fall short for agents
A log is a timestamped message. OpenTelemetry’s Observability primer makes the limit plain: logs aren’t enough for tracking code execution, because they usually lack contextual information, such as where they were called from. That limit bites hard with agents. One run can involve many model generations, tool calls and handoffs, and several runs may write to the same file at once. A line reading “command failed” tells you nothing about which run, which step or which decision led to it.
Free tools Windows power users keep installed
One-click scans. No signup required.
Two terms from the same primer matter throughout. A span represents one unit of work. A trace groups related spans into an end-to-end path. Each habit below either adds context to log lines or connects them to that path.
#1 Best Overall
Habit 1: Write events as structured fields, not sentences
OpenTelemetry’s logging documentation describes structured log records and a uniform data model that backends can consume. The point is that you can filter and query fields instead of grepping prose. No source mandates one schema, so pick a small, consistent set and stick to it. Useful fields for an agent:
- Run or session ID, so every line from one task can be pulled together.
- Event type, such as model_call, tool_call, file_edit or test_run.
- Component or tool name, such as the shell, the editor or a search tool.
- Status and error class, kept separate from the free-text message.
- Duration in a fixed unit.
An illustrative record (the field names are an example, not a standard):
{"ts":"2026-10-07T09:14:03Z","run_id":"r-4821","event":"tool_call","tool":"run_tests","status":"error","error_class":"NonZeroExit","duration_ms":8412}With records like this, “show every failed tool call in run r-4821” becomes a query rather than a reading exercise. You can emit such records directly through the OpenTelemetry API/SDK, or bridge an existing logging library into it, which avoids rewriting every log call.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesHabit 2: Tie every log line to a trace and span
OpenTelemetry says logs become more useful when they are associated with a span or correlated with a trace and span. In practice, stamp each record with the current trace ID and span ID. Then a log line saying “patch failed to apply” points to the exact span in which it happened, and you can see what ran before and after it.
The practical benefit for debugging is navigation. You can start from a suspicious log line and jump to its surrounding span, or start from a slow or failed span and list every log emitted inside it. Without the IDs you are matching timestamps by eye, which fails as soon as the agent runs steps in parallel.
Habit 3: Record tool steps, not just the final answer
The OpenAI Agents SDK documentation describes built-in tracing that collects a comprehensive record of events during an agent run: LLM generations, tool calls, handoffs, guardrails and custom events. OpenAI’s API tracing documentation likewise covers session and turn traces with recorded model and tool steps. The details exposed include tool arguments and, when available, results, along with outcome status and errors.
Rank #3
This changes what you can diagnose:
- Wrong argument: the model picked the right tool but passed a bad path or flag. Visible only if arguments are recorded.
- Ignored error: a tool returned a failure and the agent carried on as if it had succeeded. Visible only if results and status are recorded.
- Wrong handoff or skipped guardrail: the run took an unexpected route. Visible only if the sequence is recorded.
If your agent has domain-specific steps, such as “apply patch” or “re-read file”, add them as custom events so they sit in the same sequence. Otherwise the most important actions are the ones missing from the trace.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Habit 4: Keep timing and outcome next to every event
Start time, end time, duration and status turn a list of events into something you can scan for anomalies. Microsoft’s guide, Monitor agent usage with OpenTelemetry for VS Code, describes agent, LLM and tool telemetry that includes duration and error fields, which is the same shape you want in your own records.
What this surfaces: a test command that takes ten times longer than the others, a model call that repeats five times in a row, a step that ends with an error status yet is followed by a “success” summary. Be realistic about the limit, though. Timing and status help you find the slow or failed step; they do not fix latency or correctness by themselves.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Habit 5: Decide deliberately what content you capture
Prompts, model outputs and tool inputs and outputs can contain source code, credentials, personal data or customer information. The Agents SDK tracing documentation states that sensitive-data capture is enabled by default and provides a setting to disable it. Defaults and option names can change between SDK versions, so check the documentation for the version you run.
A sensible approach:
- Decide per field whether content is needed or whether metadata (tool name, argument keys, sizes, status) is enough.
- Redact secrets and personal data before records leave the process, not afterwards.
- Set a retention period and restrict who can read traces, since they may hold more than your normal application logs.
- Turn on full content capture for targeted debugging sessions rather than permanently, where your tooling allows it.
The trade-off is real: full content makes a failure easier to reproduce, while metadata-only logging limits exposure but can leave you guessing about what the model actually saw.
Recommended Free Tools
Choosing where the logs go
| Choice | Easier when | Cost |
|---|---|---|
| Local text or JSON files | One developer inspecting one run | Hard to query across runs or correlate with other services |
| Centralized collection | A team needs shared querying and correlation | More setup, and sensitive content now lives in another system |
| Bridging an existing logger to OpenTelemetry | You already have logging calls everywhere | Fields are only as structured as your current calls |
| Emitting records directly via the OpenTelemetry API/SDK | You are building new instrumentation | More code up front |
| Built-in SDK or IDE trace views | Quick local inspection | Export to another backend depends on configuration and product capabilities |
OpenTelemetry’s article AI Agent Observability — Evolving Standards and Best Practices frames telemetry as useful for troubleshooting and feedback, and notes that agent observability conventions are still evolving. Expect attribute names and defaults to shift, and avoid hard-coding assumptions you cannot easily change.
A quick debugging pass using all five
- Filter by run ID and error status to find the first failed event, not the last.
- Open that event’s span and read the tool arguments and result.
- Check the logs correlated to that span for the context around it.
- Compare durations with neighboring steps to spot loops or stalls.
- Confirm that whatever you are about to copy into a bug report has been redacted.
This is the same problem developers describe publicly in a Reddit thread titled “How do you actually debug your agents when they fail silently?” Silent failures are exactly the cases where a final answer looks plausible and only the intermediate record shows what went wrong.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
