# Claude Code OpenTelemetry Setup

Canonical: https://hyperparam.app/docs/claude-code-otel

This guide explains how to set up Claude Code to export telemetry to the built-in OpenTelemetry daemon (hypaware) 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 (HypAware deployed via MDM, traces written as Iceberg in your bucket or in managed storage, analyzed in Hyperparam), see [HypAware Team and Fleet Setup](https://hypaware.ai/docs/team-setup/) and the architecture overview.

> **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, with no Docker and 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')/hypaware/`:
  - macOS: `~/Library/Application Support/Hyperparam/hypaware/`
  - Linux: `~/.config/Hyperparam/hypaware/`
  - Windows: `%APPDATA%\Hyperparam\hypaware\`
- **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`:

```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:

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

Or open the **Telemetry** source in Webapp, and 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.