Usage by actor
Every sender is an actor — a person, an AI agent or a host. Sessions, tokens and spend per actor, each with its own token, page and activity.
Self-hosted OTLP ingest and a cost dashboard for every Claude Code sender — people, AI agents and hosts. One container.
docker run -d \
--name cotel \
-p 4318:4318 \
-p 8080:8080 \
-v cotel-data:/data \
ghcr.io/flopsstuff/cotel:latestOpen http://localhost:8080 → Setup for the guided onboarding.
Add to your ~/.claude/settings.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 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:
https://otlp.example.com), header Authorization = Bearer cotel_ik_<key>, export on.No per-agent env, helper or managed settings on the Paperclip host. Details: Paperclip agents.
| Port | Purpose |
|---|---|
| 4318 | OTLP/HTTP ingest (POST /v1/traces; POST /v1/logs is accepted and discarded) |
| 8080 | Analytics dashboard |
| Variable | Default | Description |
|---|---|---|
COTEL_DB_PATH | /data/cotel.duckdb | DuckDB file path |
COTEL_INGEST_ADDR | :4318 | Ingest listener address |
COTEL_DASH_ADDR | :8080 | Dashboard listener address |
COTEL_RETENTION_RAW_DAYS | 30 | Raw span retention in days (roll-up consumes whole days, so spans survive up to a day longer) |
COTEL_RETENTION_AGGREGATE_DAYS | 90 | Daily aggregate retention in days |
COTEL_RETENTION_INTERVAL | 6h | Retention 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_INTERVAL | 24h | How often a snapshot is taken (Go duration) |
COTEL_SNAPSHOT_KEEP | 14 | How many complete snapshots to keep - 14 days at the default interval |
COTEL_SNAPSHOT_VOLUME | cotel-snapshots | Read by docker-compose.yml, not the binary: the Docker volume mounted at /snapshots |
SNAPSHOT_CHECK | auto | Read 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_SECONDS | 172800 | Read 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 lives in the named volume at /data/cotel.duckdb. You can query it directly:
docker run --rm -v cotel-data:/data ubuntu \
duckdb /data/cotel.duckdb "SELECT model, COUNT(*) FROM spans GROUP BY model"| Tier | Period | Table |
|---|---|---|
| Raw spans | 30 days | spans |
| Daily aggregates | 90 days | daily_usage |
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.