Skip to content

cotelClaude Code Telemetry

Self-hosted OTLP ingest and a cost dashboard for every Claude Code sender — people, AI agents and hosts. One container.

Quick start ​

bash
docker run -d \
  --name cotel \
  -p 4318:4318 \
  -p 8080:8080 \
  -v cotel-data:/data \
  ghcr.io/flopsstuff/cotel:latest

Open http://localhost:8080 → Setup for the guided onboarding.

Point Claude Code at cotel ​

Add to your ~/.claude/settings.json:

json
{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
    "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT": "http://localhost:4318/v1/traces",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer cotel_<your-actor-token>"
  }
}

Restart Claude Code. Telemetry starts flowing immediately.

The token comes from Actors → Add actor in the dashboard and puts the spans under that actor. While Allow anonymous OTLP is on (the default) the header is optional and spans without it land on the Anonymous actor. For a fleet that shares one set of headers, send an ingest key instead: Authorization=Bearer cotel_ik_<key>. See Actors and Authentication.

Paperclip agents ​

Paperclip gives every agent the same OTLP headers, so its agents cannot each send their own token. cotel attributes their spans by the paperclip.agent.id attribute Paperclip already sets:

  1. In cotel, Setup → Settings → Ingest keys → create a key.
  2. In Paperclip, Company Settings → General → Agent observability: destination Custom OTLP, your ingest base URL (e.g. https://otlp.example.com), header Authorization = Bearer cotel_ik_<key>, export on.
  3. In cotel, open each agent's actor page and fill in Paperclip agent with its UUID.

No per-agent env, helper or managed settings on the Paperclip host. Details: Paperclip agents.

Ports ​

PortPurpose
4318OTLP/HTTP ingest (POST /v1/traces; POST /v1/logs is accepted and discarded)
8080Analytics dashboard

Environment variables ​

VariableDefaultDescription
COTEL_DB_PATH/data/cotel.duckdbDuckDB file path
COTEL_INGEST_ADDR:4318Ingest listener address
COTEL_DASH_ADDR:8080Dashboard listener address
COTEL_RETENTION_RAW_DAYS30Raw span retention in days (roll-up consumes whole days, so spans survive up to a day longer)
COTEL_RETENTION_AGGREGATE_DAYS90Daily aggregate retention in days
COTEL_RETENTION_INTERVAL6hRetention worker tick interval
COTEL_SNAPSHOT_DIR(unset - snapshots off)Where the snapshot worker exports the whole database (compose sets /snapshots); empty disables snapshots. See Database Snapshots and Restore
COTEL_SNAPSHOT_INTERVAL24hHow often a snapshot is taken (Go duration)
COTEL_SNAPSHOT_KEEP14How many complete snapshots to keep - 14 days at the default interval
COTEL_SNAPSHOT_VOLUMEcotel-snapshotsRead by docker-compose.yml, not the binary: the Docker volume mounted at /snapshots
SNAPSHOT_CHECKautoRead by scripts/probe-healthz.sh, not the binary: auto pages only on an affirmatively broken snapshot, require also when the instance claims none, off never asks. See Production health probes
SNAPSHOT_STALE_AFTER_SECONDS172800Read by scripts/probe-healthz.sh, not the binary: how old the newest snapshot may be - two COTEL_SNAPSHOT_INTERVAL periods at the shipped 24h
API_HEALTH_URL(derived from the /healthz URL)Read by scripts/probe-healthz.sh, not the binary: overrides the derived /api/v1/health address

Data & retention ​

Data lives in the named volume at /data/cotel.duckdb. You can query it directly:

bash
docker run --rm -v cotel-data:/data ubuntu \
  duckdb /data/cotel.duckdb "SELECT model, COUNT(*) FROM spans GROUP BY model"
TierPeriodTable
Raw spans30 daysspans
Daily aggregates90 daysdaily_usage

Architecture ​

Claude Code  →  OTLP/HTTP (port 4318)  →  ingest handler
                                           ↓
                                        DuckDB (named volume)
                                           ↓
dashboard (port 8080)  ←─────────────────┘

Single Go binary. Single DuckDB file. Single named volume. No sidecars.

Documentation ​

Released under the MIT License.