Claude Code OpenTelemetry: Metrics, Logs and Traces

Enable Claude Code telemetry

Native telemetry includes metrics and log events. Distributed traces are opt-in and currently documented as beta. Set the protocol explicitly and match it to your receiver. This example targets a local OTLP/HTTP collector:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# Optional beta span tracing
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp
claude

Check your installed Claude Code version against the official monitoring reference. Content logging has separate controls; do not enable prompt or tool-content collection just to obtain numeric usage metrics. Managed settings may constrain exporter destinations.

A common monitoring setup

Claude Code → OTLP receiver → Collector pipelines
                              ├─ metrics → metrics backend
                              ├─ logs    → logs backend
                              └─ traces  → tracing backend

The Collector separates receiving, processing and exporting. A receiver declared in YAML only becomes active when referenced by a service pipeline. Start with the debug exporter to verify receipt, then configure production exporters for your chosen backends.

receivers:
  otlp:
    protocols:
      http:
        endpoint: 127.0.0.1:4318
processors:
  batch: {}
exporters:
  debug:
    verbosity: basic
service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

This is a local diagnostic configuration, not durable storage. In a container, the receiver must also be reachable through the container network; bind and publish ports deliberately. Remote collectors need appropriate transport security and authentication. See the Collector configuration reference.

Exporters and backends

An exporter sends a signal; a backend stores and queries it. A metrics dashboard cannot recover tool-output text from a numeric counter. A trace backend needs spans, not just a logs pipeline.

• Metrics: use a metrics backend for aggregate usage trends and alerts. When using a Prometheus-compatible system, check the receiver/exporter path and the backend’s temporality requirements.
• Logs: use a logs backend to query events and their attributes.
• Traces: use a tracing backend for parent-child spans and request timing. A Collector can forward OTLP to hosted or self-operated systems.

A concrete Grafana stack pairs a Prometheus-compatible metrics backend with Loki for OTLP logs and Tempo for traces. Grafana is the query and visualization interface; it is not a substitute for each signal’s storage. Grafana Alloy is another Collector distribution with these pipelines.

For Claude Code metrics, the documented default temporality is delta; session identifiers can increase cardinality. Export intervals also mean a dashboard may lag behind the terminal. Check collector receipt before troubleshooting dashboard queries. For a missing signal, verify its exporter, protocol, endpoint and enabled pipeline independently.

OpenTelemetry vs tracehouse

tracehouse is not advertised here as a general OTLP receiver. Do not point Claude Code’s OTLP endpoint at tracehouse’s transcript ingestion API. Native tracing can also represent subagent relationships; the distinction is the collection path and review workflow, not a claim that OTel cannot show agent traces.

When to use both

Use OTel when your operations team needs telemetry in its existing storage and alerting system. Add tracehouse monitoring when reviewers need to read the saved conversation and compare attempts. These can run independently; this guide does not promise an automatic cross-backend join.

Record a session identifier and time window in your investigation. Do not add OTel totals and transcript-derived totals together: they may describe the same usage. Check missing records, cache-token treatment and retention before comparing numbers with the cost tracker. For one saved run, the local session viewer may be sufficient.