Claude Code OpenTelemetry Setup

This guide explains how to set up Claude Code to export telemetry to the built-in OpenTelemetry daemon (collectivus) bundled with Hyperparam Desktop. Traces are written to JSONL files on disk and can be browsed from the Telemetry source in Hyperparam Webapp's source list.

This page covers the local single-machine flow, which is the easiest way to get traces flowing for one developer. For the fleet-wide pattern (Collectivus deployed via MDM, traces written as Iceberg in your bucket, analyzed in Hyperparam), see HypStack.

Note: Claude Code also writes conversation transcripts directly to ~/.claude/projects/<project-hash>/<session-id>.jsonl. These can be more convenient for local chat log analysis, while OpenTelemetry is useful for structured span, metric, and log collection.

Telemetry Types

OpenTelemetry exports three data types: traces (detailed operation spans with full context), logs (discrete events), and metrics (aggregated numbers). Traces contain the most raw data.

Quick Start

Hyperparam Desktop ships with a built-in OTLP/HTTP daemon — no Docker, no separate collector process. Setup is three steps:

  1. Start the daemon from the Desktop Telemetry menu.
  2. Configure Claude Code to export OTLP to http://localhost:4318.
  3. Browse traces via the Telemetry source in the Webapp source list.

1. Start the Built-in Daemon

Open Hyperparam Desktop and use the top-level Telemetry menu:

  • Start Daemon — binds an OTLP/HTTP receiver on :4318 (default port; change via Configure Port...).
  • Open Data Folder — reveals the output directory where JSONL files are written. Defaults to app.getPath('userData')/collectivus/:
    • macOS: ~/Library/Application Support/Hyperparam/collectivus/
    • Linux: ~/.config/Hyperparam/collectivus/
    • Windows: %APPDATA%\Hyperparam\collectivus\
  • Change Output Folder... — pick a different directory (persisted across restarts).
  • Retention... — auto-delete files older than N days (0 = off).
  • Reset Telemetry... — wipes everything under the output directory.
  • Status: Running on :4318 — a disabled info row at the bottom of the menu confirms the daemon state.

Files are date-partitioned by UTC day, with both signal-level raw output and service-partitioned views:

<out>/
  traces/2026-04-17.jsonl
  metrics/2026-04-17.jsonl
  logs/2026-04-17.jsonl
  services/
    <service.name>/
      traces-2026-04-17.jsonl
      metrics-2026-04-17.jsonl
      logs-2026-04-17.jsonl

Each line is one raw OTLP/HTTP JSON body. The daemon rotates files at midnight UTC.

2. Configure Claude Code

Add these environment variables to ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
  }
}

Alternatively, set these as shell environment variables. If you changed the daemon port via Configure Port..., update OTEL_EXPORTER_OTLP_ENDPOINT to match.

3. Browse Telemetry

In Hyperparam Desktop, open the Webapp source list. When running inside Hyperparam Desktop, the list includes a Telemetry source alongside Local Files and any configured S3 sources. Selecting Telemetry opens the services/ view, where each folder is a service.name. Opening a service shows the prefixed telemetry files for that service, such as traces-YYYY-MM-DD.jsonl, metrics-YYYY-MM-DD.jsonl, and logs-YYYY-MM-DD.jsonl. Click any file to open it in the existing JSONL viewer.

The Telemetry source is only visible inside Hyperparam Desktop; it does not appear when Webapp is loaded in a regular browser, because the underlying /api/otel/* endpoints are served by the Desktop shell.

Verification

After running Claude Code with telemetry enabled, confirm the daemon is receiving data by opening the data folder (Telemetry → Open Data Folder) and tailing today's file:

tail -f "traces/$(date -u +%Y-%m-%d).jsonl"

Or open the Telemetry source in Webapp — new service folders and prefixed files appear there within seconds.

Troubleshooting

  • Port already in use: The daemon fails loudly on bind conflict. Pick a different port via Telemetry → Configure Port... and update OTEL_EXPORTER_OTLP_ENDPOINT to match.
  • No traces appearing: Confirm the Status: Running on :PORT row in the Telemetry menu, then confirm CLAUDE_CODE_ENABLE_TELEMETRY=1 is set in the Claude Code environment.
  • Wrong output folder: Use Telemetry → Change Output Folder... to pick a writable location.
  • Telemetry source missing from Webapp: It only appears in Hyperparam Desktop. In a regular browser the daemon's files aren't reachable, so the source is hidden.
Claude Code OpenTelemetry Setup - Hyperparam