Telemetry

Claude Code Observability With OpenTelemetry

A practical map of Claude Code and Agent SDK telemetry: traces, metrics, logs, identity attributes, and event analysis.

#

Telemetry model

Metrics, logs, traces

The Agent SDK passes OpenTelemetry configuration through to the Claude Code CLI, which exports the signals.

#

Cost caveat

SDK costs are estimates

The cost fields exposed by SDK result messages are useful for operations, but they are not authoritative billing records.

"traces, metrics, and log events"

How The Data Leaves The Agent

In Agent SDK applications, Anthropic documents that the SDK runs Claude Code as a child process and passes telemetry configuration to that process. The Claude Code CLI then exports directly to the configured OpenTelemetry collector. This is a useful architectural boundary: your app does not need to invent a parallel telemetry model just to observe agent work.

OpenTelemetry gives the data a vendor-neutral path into tools such as Honeycomb, Datadog, Grafana, Langfuse, or a self-hosted collector. Claude Logs does not recommend one backend. The important design choice is to export enough structure that you can answer who, what, when, cost, latency, and failure questions later.

Which Signal Answers Which Question

Metrics answer rate and volume questions: session count, token usage, cost estimates, lines modified, commits, pull requests, and tool decisions. Logs answer event questions: prompts, API requests and errors, tool results, permission decisions, and MCP activity when detailed logging is enabled. Traces answer sequence and latency questions across model requests, tools, and hooks.

For most teams, metrics and structured logs provide the first useful layer. Traces become important when agents run inside production services, queue systems, hosted workers, or multi-step automation where a stalled tool call can hide inside a larger job.

Identity Is Part Of The Signal

Anthropic documents standard event attributes that include user and organization identifiers when the session is signed in with a Claude account, plus per-session identifiers. That means an observability pipeline can attribute MCP calls, Bash commands, file edits, and permission decisions to the developer or identity that started the session.

If a deployment uses direct API keys or cloud providers where those Claude account fields are not populated, attach identity through governed resource attributes or a wrapper. Do not wait until an incident to discover that every agent event looks anonymous.

Cost Belongs In Observability, Not Invoices

The Agent SDK exposes per-step and per-session usage fields, but Anthropic explicitly cautions that client-side cost fields are estimates. Use them to spot runaway loops, compare workflow efficiency, and set operational alerts. Do not use them to invoice customers or trigger irreversible financial decisions.

A healthy dashboard shows cost beside tokens, cache behavior, model, query source, tool activity, and final outcome. A high-cost session that shipped a clean PR is different from a high-cost session that hit a retry loop and produced no durable output.

Primary sources

Sources behind this page

Anthropic

Claude Code monitoring

Reference for Claude Code metric names, event analysis, identity attributes, MCP audit detail, and retry analysis.

OpenTelemetry

OpenTelemetry documentation

Defines OpenTelemetry as a vendor-neutral observability framework for traces, metrics, and logs.

Anthropic

Track cost and usage

Explains per-step usage, model usage, session scoping, and the client-side nature of SDK cost estimates.

Cite this page

Claude Logs. "Claude Code Observability With OpenTelemetry." claudelogs.com, updated 2026-07-06. https://claudelogs.com/observability

FAQ

Do I need OpenTelemetry if I already keep transcripts?

Yes for team operations. Transcripts explain a session in depth. OpenTelemetry lets you aggregate sessions, alert on trends, and correlate agent activity with infrastructure and identity data.

Should prompts and responses be logged?

Only after a deliberate privacy decision. Structured event logging can expose user prompts, response text, file paths, tool inputs, and business data. Start with metadata, then add content logging only where governed.