Agent Observability: Seeing What Your Agent Actually Does

Logs, cost tracking, and OpenTelemetry support turn a black-box session into traceable data – essential once agents run automated or in a team.

Why watching matters

As long as you work with an agent alone and interactively, you see directly what's happening. Once agents run automated, in a team, or in CI/CD, you need real data instead: what the agent did, what it cost, which tools it called.

Session logs as the base layer

Claude Code writes every session to disk as a JSONL file (under ~/.claude/projects/). The format is internal and changes between versions – don't parse these files directly; use /export or the documented interfaces instead. Even on subscription plans, /usage shows a cost and usage breakdown right in the terminal.

Cost tracking in the terminal

The /usage command shows estimated cost and token usage for the current session right in the terminal, broken down by skills, subagents, plugins, and individual MCP servers. The figure is a local estimate computed from token counts, not an authoritative bill.

OpenTelemetry for the bigger picture

At team or organization scale, Claude Code offers native OpenTelemetry support: setting CLAUDE_CODE_ENABLE_TELEMETRY=1 exports metrics, events, and optionally traces to your own observability backend (Prometheus, Grafana, Datadog, and so on). That gives you cost, tool usage, and security events centrally across every user – instead of collecting logs from each machine by hand.

EXAMPLE

`export CLAUDE_CODE_ENABLE_TELEMETRY=1`, `export OTEL_METRICS_EXPORTER=otlp`, and `export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317` before starting `claude` are enough to send metrics to a local OpenTelemetry collector setup.

🛠️ EXERCISE — TRY IT YOURSELF

Turn on local cost and session transparency in Claude Code without setting up an external observability stack.

Run /usage in an active Claude Code session and read the breakdown by skills, subagents, and MCP servers.
Open /usage and look at the cost/usage breakdown.
Set CLAUDE_CODE_ENABLE_TELEMETRY=1 and OTEL_METRICS_EXPORTER=console as a test, restart claude, and watch which metrics show up in the console.

✅ SELF-CHECK

☐ Could /usage tell you which part of the session (e.g. a specific MCP server) consumed the most context?
☐ What was in the JSONL line – was it enough for you to reconstruct the cost?
☐ Which of the OTEL_LOG_* variables would you NOT enable in a real team setup because it exports data that's too sensitive?

QUICK QUIZ

What's the simplest way to enable OpenTelemetry export in Claude Code?