Agentic coding tools like Claude Code, OpenAI Codex, Google Antigravity, and Cursor have become ubiquitous in everyday software development. As these systems mature, developers increasingly delegate work to subagents, and many teams are exploring shared, multi-tenant agentic infrastructure where costs aren't tied to a single owner. This is where observability becomes crucial for monitoring infrastructure spend.
In this guide, you'll learn how observability works, enable Claude Code's built-in telemetry, run a backend to collect it, and read the metrics, logs, and traces it emits. By the end, you'll be equipped to track your team's costs more effectively—and as telemetry matures, you'll gain even cleaner correlations with your sessions.
Note: As of 2026, Claude Code's emitted telemetry lacks attributes for reliable mapping to named sessions. You can track usage via session_id, but this remains clumsy for longer sessions mixing multiple prompts and skills.
This guide applies to Linux and macOS only, and focuses on Claude Code's telemetry for metrics, logs, and tracing.
Understanding Observability with OpenTelemetry
Observability is the ability to understand a system's internal state based on its external outputs. OpenTelemetry provides a standardized framework for collecting telemetry data—metrics, logs, and traces—from applications. In the context of agentic coding tools, telemetry helps you monitor performance, detect anomalies, and track resource usage, which is essential for cost management in shared infrastructure.
Telemetry Data Types
- Metrics: Numerical measurements (e.g., token counts, request durations) aggregated over time.
- Logs: Timestamped records of events, providing detailed context.
- Traces: End-to-end request flows, showing how subagents interact.
Instrumenting Claude Code
Claude Code includes built-in telemetry support via OpenTelemetry, allowing you to export data without modifying the tool itself. To understand how this works, it's important to know how telemetry leaves the application.
Pull vs. Push: How Telemetry Leaves an App
OpenTelemetry supports both pull-based (where the collector scrapes endpoints) and push-based (where the app sends data to a collector) models. Claude Code uses the push model, sending telemetry to an OpenTelemetry Collector or compatible backend.
When to Run a Collector
Running an OpenTelemetry Collector is recommended if you need to:
- Aggregate data from multiple sources.
- Apply transformations or filtering.
- Export to different backends (e.g., Jaeger, Prometheus, or cloud services).
For simple setups, you might export directly to a backend, but a collector offers flexibility.
Prerequisites
- Claude Code installed and configured on Linux or macOS.
- An OpenTelemetry backend (e.g., Jaeger for traces, Prometheus for metrics) or a collector setup.
- Basic familiarity with command-line tools and configuration files.
Setup
To enable Claude Code's telemetry:
- Set the environment variable
OTELEXPORTEROTLP_ENDPOINTto your collector or backend URL. - Optionally, configure service name and other attributes via environment variables or a config file.
- Run Claude Code normally; telemetry will be sent automatically.
You can then visualize metrics, logs, and traces in your chosen backend.
Conclusion
With OpenTelemetry, you can gain valuable insights into Claude Code's usage, helping you monitor costs and optimize workflows. While current telemetry has limitations in session correlation, future developments promise richer data. Start with the setup described, and adapt as the ecosystem evolves in 2026 and beyond.
via FreeCodeCamp