Claude Agent SDK Observability With OpenTelemetry (2026)

[Alex]: Welcome back to the Nerd Level Tech AI Cast! I’m Alex, your resident code wrangler and OpenTelemetry evangelist.

[Jamie]: And I’m Jamie, your curious co-host who still thinks “telemetry” sounds like something NASA uses to track lost satellites. [laughs] But hey, today we’re geeking out over something even cooler—Claude Agent SDK Observability with OpenTelemetry!

[Alex]: That’s right! If you’ve ever wondered how to actually see what your Claude agents are doing under the hood—or if you just want better dashboards to show your boss—you’re in the right place.

[Jamie]: Okay, Alex, set the scene for us: What is observability in the world of AI agents, and why should anyone care?

[Alex]: Great question, Jamie. Observability is basically the art of “seeing inside” your code—knowing what your agents are up to, how much they cost you, and where your latency is hiding. Think of it like having X-ray goggles for your AI pipelines.

[Jamie]: Oh, like when I try to debug my smart fridge and wish it could just tell me what’s wrong instead of blinking random lights at me?

[Alex]: Exactly! Except here, instead of blinking lights, you get traces, logs, and metrics—all thanks to the magic of OpenTelemetry. And today, we’re focusing on tracing: following every single step your Claude agent takes, from model requests to tool calls, all the way down to hooks.

[Jamie]: So, tracing is kinda like a play-by-play for my agent’s life story?

[Alex]: Nailed it! And with the Claude Agent SDK, you can now export all of that as OpenTelemetry traces. But—here’s the kicker—tracing is off by default and needs a few secret handshakes to turn on.

[Jamie]: Ooooh, secret handshakes! Lay it on me, what do I need?

[Alex]: You need to set two environment variables: `CLAUDE_CODE_ENABLE_TELEMETRY=1` to flip the master switch, and `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` because traces are still in beta. Then, point `OTEL_TRACES_EXPORTER` at your collector endpoint. That’s where your traces are shipped for viewing.

[Jamie]: And all this is in TypeScript, right? Because we’re living in the future?

[Alex]: You bet! The SDK is built for Node.js 18 and above, but was tested all the way up to Node 22.22.3. It’s basically the Tesla of agent SDKs—fancy, fast, but you better have the right cables.

[Jamie]: [laughs] So if I want to see what my agent is doing, what does that actually look like? Are we talking a wall of JSON? A beautiful dashboard? Or… more blinking lights?

[Alex]: [chuckles] Ideally, a beautiful dashboard! But you can start simple: just spin up a local HTTP server that prints out those traces in readable JSON. It’s like peeking at the agent’s diary—no commercial backend needed.

[Jamie]: Wait, can I really do this without shelling out for Jaeger or some enterprise tool?

[Alex]: Absolutely! For devs on a budget, a TypeScript script with Node’s built-in HTTP module will do the trick. Just remember to use the `httpjson` protocol—otherwise you’ll be staring at binary blobs, and nobody wants that.

[Jamie]: Alright, walk me through what actually gets traced. What’s in this "span tree" you keep mentioning?

[Alex]: Good catch! So, when you run a Claude agent with tracing enabled, each agent turn becomes a root span called `claude_code.interaction`. Under that, you get child spans for every model request (`claude_code.llm_request`), for every tool call (`claude_code.tool`), and—if you’re feeling adventurous—hook executions (`claude_code.hook`).

[Jamie]: Wait, so if my agent’s making a weather request and calling a tool, I’ll see all of that as separate spans?

[Alex]: Exactly. Picture it like a family tree, but instead of “grandpa Bob,” you’ve got “tool.execution.” And each span comes loaded with attributes: model used, duration, token counts, cost, and more.

[Jamie]: And this is useful because…?

[Alex]: Because the SDK’s summary stats only tell you the total cost or duration. But what if you want to know which tool call took the longest, or if the model had to retry before succeeding? Spans give you that granularity.

[Jamie]: Got it—so it’s not just “my agent cost 3 cents,” but “the weather tool call cost 1 cent and took 2 seconds because Berlin is cloudy and slow.”

[Alex]: [laughs] Precisely! And if your dashboards are set up right, you can track down performance bottlenecks or cost spikes in no time.

[Jamie]: I heard something about OpenTelemetry GenAI semantic conventions. Do the Claude SDK traces follow those rules?

[Alex]: Ah, the million-dollar question. The answer is: sort of. The span names—like `claude_code.interaction`—are Anthropic’s own, not the GenAI standard ones. But, a handful of attributes on those spans—like `gen_ai.system`, `gen_ai.request.model`, and `gen_ai.response.id`—are compliant with the GenAI spec.

[Jamie]: So, if my backend is looking for those GenAI spans by name, it might get confused?

[Alex]: Exactly. If you’re dashboarding based on span names alone, you’ll miss them. But if you dashboard by those GenAI attributes, you’ll find what you need. It’s like looking for apples by color, not by the sticker on the peel.

[Jamie]: [laughs] And I bet the stickers are always out of date anyway.

[Alex]: Always. In fact, one attribute—`gen_ai.system`—was renamed in the latest GenAI spec to `gen_ai.provider.name`, but Anthropic’s docs haven’t caught up yet. Always double-check what your backend expects!

[Jamie]: Okay, last burning question: If I want to trace my own app logic and see the Claude agent as part of my overall trace, is that possible?

[Alex]: Yes! If you’re already using OpenTelemetry in your app, you can wrap the agent’s `query()` call inside your own span. The SDK will propagate trace context, so your agent’s spans show up as children of your main app trace. It’s like adding your agent’s adventures to your app’s family scrapbook.

[Jamie]: Love it! So, in summary: flip the right switches, wire up your environment, and you can see inside your Claude agents like never before. No more flying blind!

[Alex]: Exactly. And if you ever get stuck, just remember: always spread `...process.env` when setting up your environment. Otherwise, your agent might lose its keys, wallet, and API access all at once.

[Jamie]: Never a good day when you lose your API key. [laughs] Alright, that’s a wrap for today’s episode of Nerd Level Tech AI Cast! If you liked this deep dive, subscribe and drop us a review—and let us know what you want us to nerd out over next.

[Alex]: Thanks for listening! Go forth and instrument all the things—your agents will thank you. [Outro music fades out]