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.

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