Stepan Samko | Consulting [email protected]

How to Give AI Agents Access to Runtime Traces

December 2025

A practical guide to debugging locally with execution-aware AI

AI coding agents are very good at reading code. Point one at a repository and it can explain control flow, trace dependencies, spot patterns, and suggest changes almost instantly.

Then you try to debug something locally and everything slows down:

These aren’t problems of understanding code. They’re problems of how the code actually executes.

Right now, agents mostly operate on static inputs. They know what the code says, but they don’t directly see how it behaves when it runs. So you end up doing the unglamorous part: reproducing the issue, checking traces or logs, figuring out what’s slow or failing, and then translating that back into text.

That translation step is where most of the time goes.

This post shows how to remove that step for local debugging, using OpenTelemetry traces and a small tool I built called otel-mcp.

The current AI debugging workflow (and why it’s slow)

If you’ve used an AI agent to debug anything beyond syntax errors, this loop probably feels familiar.

Before:


You:    The /users endpoint is slow locally.
Agent: I see two DB queries and an external call. Which part is slow?
You:    (spends 10 minutes checking logs / traces / console output)
You:    The external API averages ~600ms.
Agent: Add caching. Here's how.

The agent’s suggestion might even be correct.

But notice where the time went:

You’re acting as a human adapter between the running system and the model.

The problem isn’t reasoning.
The problem is visibility.

Reading code doesn’t tell you how it behaves

Here’s a completely normal endpoint:

app.get('/api/users/:id', async (req, res) => {
  const user = await db.query('SELECT * FROM users WHERE id = ?', [req.params.id]);
  const posts = await db.query('SELECT * FROM posts WHERE user_id = ?', [user.id]);
  const enriched = await enrichUserData(user, posts);
  res.json(enriched);
});

From the source alone, an agent can say sensible things:

All of that is true. It’s also not enough to debug.

When you’re actually fixing a local issue, you care about things like:

You can’t read your way to answers like:

“This query takes ~430ms because it returns ~50 rows without an index.”

or

“The HTTP call is fine, but connection reuse stalls after restart.”

Those answers only show up when the code runs.

Traces: execution data an AI can actually use

Distributed tracing gives you a structured record of how a request executes.

A trace is a tree of spans. Each span represents a timed operation — a database query, an HTTP call, a cache access — with attributes like duration, status, and optional metadata.

With OpenTelemetry auto-instrumentation, you usually get spans for exactly the things that dominate local latency.

That same endpoint might produce a trace like this:

Trace: GET /api/users/123   (total: 892ms)

  db.query users_by_id                 6ms
  db.query posts_by_user_id          438ms   rows=52
  enrichUserData                     440ms
    http.client GET /user-metadata   411ms   status=200
    cache.set                          9ms

This is concrete, timed, hierarchical data. It tells you what ran, in what order, and how long each step took.

This is exactly the information you look for when debugging manually.

So the obvious next question is:

What if the agent could inspect this directly?

otel-mcp: traces for AI agents

otel-mcp is a small MCP server that makes runtime traces available to AI agents during local development.

It does three simple things:

  1. Runs a local OTLP HTTP collector (localhost only).
  2. Stores recent traces in memory (ephemeral, dev-focused).
  3. Exposes a small set of query tools that agents can call via MCP.

It’s not an APM. There’s no UI, no dashboards, no retention policies. It’s designed specifically for local debugging with AI agents.

Which agents does this work with?

otel-mcp works with any MCP-compatible AI coding assistant, including:

If your agent can call MCP tools, it can query traces through otel-mcp.

What changes when the agent can see traces

Let’s replay the same debugging scenario.

After (with otel-mcp):

You:    The /users endpoint is slow locally.
Agent: (lists slow traces from the last few minutes)
Agent: I found 23 slow requests. The posts query averages ~430ms and
       returns ~50 rows without an index. The external API averages ~70ms.
       Adding an index on posts(user_id) should fix this.

No “can you check the traces and tell me what you see?” No screenshots. No paraphrasing what you saw in another tool.

The agent is inspecting the same execution data you would — directly.

What tools the agent gets

otel-mcp exposes a deliberately small and predictable set of tools:

This mirrors how people actually debug: start broad, narrow down, inspect details.

What you need

Before setting this up, make sure you have:

You don’t need production observability or a hosted backend — this is all local.

Setting it up

If you already use OpenTelemetry, setup is usually trivial — just point your exporter at the local collector.

Here’s a typical Node.js configuration:

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

const sdk = new NodeSDK({
  serviceName: 'my-app',
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

Auto-instrumentation usually captures most of what matters locally:

When it doesn’t, adding a manual span around a critical section is usually enough.

Why this works well for local debugging

A few design choices make this effective in practice:

The goal isn’t to build a full observability platform. It’s to remove friction from debugging.

Common issues

Limitations (and why they’re fine here)

For local debugging, these trade-offs are usually acceptable.

Try it

If you’re debugging locally with an AI agent and find yourself constantly explaining what you saw in logs or traces, this is worth trying.

👉 https://github.com/moondef/otel-mcp

Once the agent can see how the code actually runs, the conversation changes — and debugging gets noticeably faster.