diff --git a/README.md b/README.md index 04ad324..9c6190d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,14 @@ # cotel — Claude Code Telemetry -One Docker container. OTLP ingest on `:4318`, interactive analytics dashboard on `:8080`. No cloud dependencies, no sign-up. +Self-hosted telemetry for Claude Code: sessions, tokens and spend for every sender — people, AI agents and hosts. One Docker container, OTLP ingest on `:4318`, dashboard on `:8080`. No cloud dependencies, no sign-up. + +- **Usage by actor** — every sender that identifies itself (actor token or Paperclip agent id) is an actor with its own page and spend; only senders that don't land together on Anonymous. +- **Cost by model** — per-span cost from a built-in Claude price table (Claude 5.5 and 5.2 included), repriceable after the fact with `--backfill-cost-apply` (`--backfill-cost` previews). +- **Ingest keys for agent fleets** — one shared `cotel_ik_…` key authorizes ingest for many senders that share one set of OTLP headers. +- **Paperclip agents, natively** — attributed by `paperclip.agent.id`; one Agent observability setting with an ingest key, no per-agent env. See [Paperclip agents](docs/operations/actors-and-auth.md#paperclip-agents). + +Docs: **https://flopsstuff.github.io/cotel/** ![cotel Overview](docs/assets/dashboard-overview.png) @@ -71,13 +78,16 @@ Add to your `~/.claude/settings.json`: "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_TRACES_ENDPOINT": "http://localhost:4318/v1/traces", + "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer cotel_" } } ``` Restart Claude Code. Telemetry starts flowing immediately. +The token comes from **Actors** → **Add actor** 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. + ## Actors and authentication cotel ships with token-based authentication for OTLP ingest. Tokens are tied to named **actors**: whoever sends telemetry, whether a person, an AI agent or a host. @@ -160,13 +170,13 @@ Add to your `~/.claude/settings.json`: Replace `cotel-ingest.yourdomain.com` with your actual OTLP hostname, and `cotel_` with the token you copied above. Restart Claude Code to apply the changes. -> **Token enforcement:** cotel accepts anonymous spans until the first actor with a token is created. Once any token exists, every OTLP request must carry a valid `Authorization: Bearer cotel_...` header — unless you explicitly re-enable Allow anonymous OTLP in Setup → Settings. +> **Token enforcement:** a public ingest endpoint should not accept anonymous writes. Once every sender has its actor token or an ingest key, disable **Allow anonymous OTLP** in Setup → Settings; requests without a valid `Authorization: Bearer cotel_…` header then get `401`. ## Ports | Port | Purpose | |------|---------| -| 4318 | OTLP/HTTP trace ingest (`POST /v1/traces`) | +| 4318 | OTLP/HTTP ingest (`POST /v1/traces`; `POST /v1/logs` is accepted and discarded) | | 8080 | Analytics dashboard | > **HTTP-only:** cotel speaks OTLP/HTTP (`application/x-protobuf` and `application/json`). There is no gRPC listener on port 4317. If spans are silently dropped, ensure `OTEL_EXPORTER_OTLP_PROTOCOL=http/json` (or `http/protobuf`) is set — the OTel SDK default is `grpc`, which will fail against cotel. diff --git a/docs/assets/dashboard-actors.png b/docs/assets/dashboard-actors.png index fb6f691..10dd403 100644 --- a/docs/assets/dashboard-actors.png +++ b/docs/assets/dashboard-actors.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:dd9dae97d37d2a0e650584922849509adcf4ff1b05af8e1f919fbeb53cf440a5 -size 162194 +oid sha256:e8bbe1da84ea0a06dc17f6d2d58e85581d899e245a8f4cac0d0017bc45a69525 +size 155017 diff --git a/docs/assets/dashboard-costs.png b/docs/assets/dashboard-costs.png index 872503c..42d28a4 100644 --- a/docs/assets/dashboard-costs.png +++ b/docs/assets/dashboard-costs.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:f39a8c0af75fb3a30af41989f9cc2364a9b524fc6c974f45fd35f61f59846c47 -size 144381 +oid sha256:0a9eaad9ca065117ec5d77bd294c66098afb1f3d21dfb0ac9e0f80ed66d2b627 +size 142003 diff --git a/docs/assets/dashboard-overview.png b/docs/assets/dashboard-overview.png index 9237c89..6640869 100644 --- a/docs/assets/dashboard-overview.png +++ b/docs/assets/dashboard-overview.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:a748712cb804b7d3489743c5c09eaee83785e097f9a48fc53f28eb322f468ad8 -size 313903 +oid sha256:360eea713da323fb6936828a2b25343e7569cdc44b0ae58fd841852343d725de +size 312150 diff --git a/docs/assets/dashboard-sessions.png b/docs/assets/dashboard-sessions.png index 7b1d295..447b787 100644 --- a/docs/assets/dashboard-sessions.png +++ b/docs/assets/dashboard-sessions.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:d054178cc51787106610a66791ac3a529c4388235545b7b20b8a063be5168107 -size 356245 +oid sha256:4b8b453862ea43c1aca7d2a9410dc5f54417192552bee3840b3f67363f554ebe +size 314340 diff --git a/docs/assets/dashboard-tools.png b/docs/assets/dashboard-tools.png index 6095ac5..df00e6a 100644 --- a/docs/assets/dashboard-tools.png +++ b/docs/assets/dashboard-tools.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:2cf41a8b6553a71e2f5e090f07dad841b05b147c693ae3080c2de0509cfa49e7 -size 146992 +oid sha256:e62c8782d503daade4e5ddf2c7b2e372e9513d7a9357c0b065b29e16e954b0df +size 144663 diff --git a/docs/index.md b/docs/index.md index 997695f..8533052 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,22 +4,31 @@ layout: home hero: name: cotel text: Claude Code Telemetry - tagline: One container. OTLP ingest + interactive analytics dashboard for Claude Code. + tagline: Self-hosted OTLP ingest and a cost dashboard for every Claude Code sender — people, AI agents and hosts. One container. actions: - theme: brand text: Quick start link: '#quick-start' + - theme: alt + text: Paperclip agents + link: '#paperclip-agents' - theme: alt text: GitHub link: https://github.com/Flopsstuff/cotel features: + - title: Usage by actor + details: 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. + - title: Cost by model + details: Spend computed per span from a built-in Claude price table, broken down by model, session and day. Repricing an old range is one backfill command. + - title: Ingest keys for agent fleets + details: One shared cotel_ik_ key authorizes a whole fleet's OTLP headers; actor tokens still say who each sender is. + - title: Native Paperclip integration + details: Paperclip agents are attributed by paperclip.agent.id. One Agent observability setting with an ingest key, no per-agent env. - title: Single-container deploy details: One docker run with a named volume. No sidecars, no orchestration. Runs on a Raspberry Pi. - title: OTLP-native ingest - details: Standard OpenTelemetry Protocol on port 4318. Point Claude Code at it and telemetry starts flowing. - - title: Analytics dashboard - details: Session, cost, model, and tool breakdowns with time-range filtering — all queried from embedded DuckDB. + details: Standard OpenTelemetry Protocol on port 4318, JSON or protobuf. Point Claude Code at it and telemetry starts flowing. --- ## Quick start @@ -30,10 +39,10 @@ docker run -d \ -p 4318:4318 \ -p 8080:8080 \ -v cotel-data:/data \ - ghcr.io/flopsstuff/cotel:main + ghcr.io/flopsstuff/cotel:latest ``` -Open **http://localhost:8080** for the dashboard. +Open **http://localhost:8080** → **Setup** for the guided onboarding. ## Point Claude Code at cotel @@ -45,18 +54,32 @@ Add to your `~/.claude/settings.json`: "CLAUDE_CODE_ENABLE_TELEMETRY": "1", "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1", "OTEL_TRACES_EXPORTER": "otlp", - "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT": "http://localhost:4318/v1/traces" + "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json", + "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT": "http://localhost:4318/v1/traces", + "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer cotel_" } } ``` 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_`. See [Actors and Authentication](./operations/actors-and-auth). + +## 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_`, 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](./operations/actors-and-auth#paperclip-agents). + ## Ports | Port | Purpose | |------|---------| -| 4318 | OTLP/HTTP trace ingest (`POST /v1/traces`) | +| 4318 | OTLP/HTTP ingest (`POST /v1/traces`; `POST /v1/logs` is accepted and discarded) | | 8080 | Analytics dashboard | ## Environment variables @@ -105,6 +128,7 @@ Single Go binary. Single DuckDB file. Single named volume. No sidecars. ## Documentation +- [Actors and Authentication](/operations/actors-and-auth) — actor tokens, ingest keys, Paperclip agents, allow-anonymous mode - [Architecture Decisions](/decisions/) — ADRs explaining key technical choices - [Design Docs](/design/) — UI information architecture, page specs, components, tokens - [Production health probes](/operations/health-probe) — the best-effort watcher of the public ingest, what it cannot see, and who is woken when it is red