Files
headroom/deploy/beacon/sample-event.json
67eb910e38 feat(beacon): schema v2 — routing/compression training signal, gzip transport (#3253)
## What

Nine new sections on the session heartbeat — `quality`, `hist`,
`shapes`, `cache`, `trajectory`, `clients`, `errors`, `strata`, `config`
— plus a gzip transport. Everything is a counter, a ratio, or a slug
from a fixed list in the source. No prompts, code, file paths, tool
names, project names, or error text can appear.

## No regression in v1

Every existing field keeps its name, type, and meaning.
`tests/test_beacon_schema_v2.py` locks the v1 surface with literal key
lists and a shape-stability invariant, so a v1 field that silently
changes type fails there rather than in the corpus six weeks later.

The v2 section is built in `_payload_v2()` behind `try/except`, and
`_fold_extra()` likewise. A bug in new code can cost the new fields and
nothing else. The first version built one dict literal — any raise
dropped `tokens.saved` along with it.

## The STRUCT/MAP flip

Four fields ship as lists of records rather than objects keyed by data
(`clients`, `config`, `strata`, `waste`). DuckDB infers a JSON object as
`STRUCT` when the keys are few and identifier-shaped, and as `MAP`
otherwise — so a key set that grows with the fleet flips type mid-corpus
and `BINDER ERROR`s the reader.

Caught against the real 369k-session corpus, not in theory: `clients`
inferred `STRUCT(claude_code, codex)` at two harnesses and `MAP(VARCHAR,
BIGINT)` at 22, and `clients.cursor` errors on one of them.

## Transport

Body is gzipped at level 6 (~6x). The receiver sniffs magic bytes rather
than trusting `Content-Encoding`, enforces a decompression-bomb limit
*during* the stream read, and leaves the plain path byte-identical for
the existing fleet.

A `400`/`415` disables gzip for the process and retries once. A `413`
does not — an uncompressed retry is 6x larger and guaranteed to fail
again.

At current rates (~235k heartbeats/day): v1 today 892 MB/day, v2
uncompressed 1,802 MB/day, **v2 gzipped 295 MB/day** — a net reduction
against what we send now.

## `headroom telemetry`

Prints the real payload, built by the same `_Session.payload()` the
beacon uses. \"Go read worker.js\" answers what happens to the data; it
does not answer what leaves your machine.

Uses `read_install_id()` and
`resource_attributes(create_install_id=False)` — the default mints and
persists the id, so building the report would itself be the act that
identifies the machine. Filtering the id out of the *output* is not
enough; by then the file exists.

## Receiver

Allowlist gains the nine keys. `MAX_BODY_BYTES` 64KB → 256KB — that
figure dated from \"a beacon event is ~2KB\", and worst-case v2 is
81,965 B uncompressed.

## Verification

Against the production corpus (369,015 sessions): **14/14** `beacon.sh`
reports pass, **18/18** dashboard queries pass, v1 totals byte-identical
at `273,495,971,478` tokens saved.

`sample-event.json` regenerated as a real v2 payload. The old v1-only
version would have passed the post-deploy smoke test whether or not the
new allowlist landed; the new one distinguishes the cases 9/9 vs 0/9.

Suite: 11,655 passed, 1 failed —
`test_mcp_reconcile.py::test_ordinary_install_does_not_adopt_serena`,
which reproduces identically on clean `main`.

## Not verified here

`node test-rollup.mjs` and `npx wrangler dev` have not been run — no
`node` in the authoring environment. `DecompressionStream` is the one
path with no fallback and has never been executed. **Both are required
before deploy.**

## Deploy order

**Worker first, client second.** The worker is backward-compatible with
the v1 fleet (allowlist additive, plain path byte-identical, cap only
raised). The reverse is not: the worker strips unknown keys at ingest,
so v2 data arriving before the allowlist lands is gone, not recoverable
by re-rolling. The corpus already carries 6 such rows from a dev proxy.

Merging this PR does not ship the client — releases are separate
commits.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Tejas Chopra <tejas@Tejass-MacBook-Pro.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-09-19 11:58:29 -07:00

1100 lines
43 KiB
JSON

{
"resourceLogs": [
{
"resource": {
"attributes": [
{
"key": "service.name",
"value": {
"stringValue": "headroom"
}
},
{
"key": "service.version",
"value": {
"stringValue": "0.37.0"
}
},
{
"key": "headroom.install_id",
"value": {
"stringValue": "00000000000000000000000000000000"
}
},
{
"key": "headroom.install_mode",
"value": {
"stringValue": "pip"
}
},
{
"key": "headroom.stack",
"value": {
"stringValue": "proxy"
}
},
{
"key": "os.type",
"value": {
"stringValue": "darwin"
}
},
{
"key": "host.arch",
"value": {
"stringValue": "arm64"
}
}
]
},
"scopeLogs": [
{
"scope": {
"name": "headroom.telemetry.session"
},
"logRecords": [
{
"timeUnixNano": "1787703693355874048",
"body": {
"kvlistValue": {
"values": [
{
"key": "schema_version",
"value": {
"intValue": "2"
}
},
{
"key": "session",
"value": {
"kvlistValue": {
"values": [
{
"key": "id",
"value": {
"stringValue": "4996e02d2b7cafe7"
}
},
{
"key": "seq",
"value": {
"intValue": "0"
}
},
{
"key": "duration_s",
"value": {
"intValue": "135"
}
},
{
"key": "turns",
"value": {
"intValue": "4"
}
},
{
"key": "ended",
"value": {
"stringValue": "shutdown"
}
},
{
"key": "final",
"value": {
"boolValue": true
}
}
]
}
}
},
{
"key": "tokens",
"value": {
"kvlistValue": {
"values": [
{
"key": "original",
"value": {
"intValue": "480000"
}
},
{
"key": "attempted",
"value": {
"intValue": "160000"
}
},
{
"key": "input",
"value": {
"intValue": "360000"
}
},
{
"key": "output",
"value": {
"intValue": "4800"
}
},
{
"key": "saved",
"value": {
"intValue": "120000"
}
},
{
"key": "tool_saved",
"value": {
"intValue": "0"
}
},
{
"key": "cache_read",
"value": {
"intValue": "240000"
}
},
{
"key": "cache_write",
"value": {
"intValue": "32000"
}
},
{
"key": "uncached",
"value": {
"intValue": "88000"
}
}
]
}
}
},
{
"key": "rates",
"value": {
"kvlistValue": {
"values": [
{
"key": "saved_pct",
"value": {
"doubleValue": 25.0
}
},
{
"key": "eligible_pct",
"value": {
"doubleValue": 33.33
}
},
{
"key": "yield_pct",
"value": {
"doubleValue": 75.0
}
},
{
"key": "all_layers_saved_pct",
"value": {
"doubleValue": 25.0
}
},
{
"key": "all_layers_yield_pct",
"value": {
"doubleValue": 75.0
}
},
{
"key": "cache_read_pct",
"value": {
"doubleValue": 50.0
}
},
{
"key": "overhead_pct",
"value": {
"doubleValue": 1.14
}
}
]
}
}
},
{
"key": "compression",
"value": {
"kvlistValue": {
"values": [
{
"key": "transforms",
"value": {
"kvlistValue": {
"values": [
{
"key": "crush",
"value": {
"intValue": "4"
}
}
]
}
}
},
{
"key": "by_strategy",
"value": {
"arrayValue": {
"values": []
}
}
},
{
"key": "overhead_ms_total",
"value": {
"doubleValue": 192.0
}
},
{
"key": "latency_ms_total",
"value": {
"doubleValue": 16800.0
}
},
{
"key": "overhead_ms_per_turn",
"value": {
"doubleValue": 48.0
}
},
{
"key": "latency_ms_per_turn",
"value": {
"doubleValue": 4200.0
}
},
{
"key": "passthrough_turns",
"value": {
"intValue": "0"
}
},
{
"key": "response_cache_hits",
"value": {
"intValue": "0"
}
}
]
}
}
},
{
"key": "skips",
"value": {
"kvlistValue": {
"values": []
}
}
},
{
"key": "sources",
"value": {
"kvlistValue": {
"values": [
{
"key": "proxy",
"value": {
"intValue": "4"
}
}
]
}
}
},
{
"key": "providers",
"value": {
"arrayValue": {
"values": [
{
"stringValue": "anthropic"
}
]
}
}
},
{
"key": "models",
"value": {
"arrayValue": {
"values": [
{
"stringValue": "claude-sonnet-5"
}
]
}
}
},
{
"key": "failures",
"value": {
"intValue": "0"
}
},
{
"key": "failure_statuses",
"value": {
"kvlistValue": {
"values": []
}
}
},
{
"key": "quality",
"value": {
"kvlistValue": {
"values": [
{
"key": "reread_tokens",
"value": {
"intValue": "3600"
}
},
{
"key": "reread_compressed_tokens",
"value": {
"intValue": "1600"
}
},
{
"key": "waste_turns",
"value": {
"intValue": "4"
}
},
{
"key": "waste",
"value": {
"arrayValue": {
"values": []
}
}
}
]
}
}
},
{
"key": "hist",
"value": {
"kvlistValue": {
"values": [
{
"key": "msgs",
"value": {
"kvlistValue": {
"values": [
{
"key": "edges",
"value": {
"arrayValue": {
"values": [
{
"intValue": "5"
},
{
"intValue": "20"
},
{
"intValue": "50"
},
{
"intValue": "100"
},
{
"intValue": "250"
},
{
"intValue": "500"
}
]
}
}
},
{
"key": "counts",
"value": {
"arrayValue": {
"values": [
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "4"
},
{
"intValue": "0"
},
{
"intValue": "0"
}
]
}
}
}
]
}
}
},
{
"key": "overhead_ms",
"value": {
"kvlistValue": {
"values": [
{
"key": "edges",
"value": {
"arrayValue": {
"values": [
{
"doubleValue": 1.0
},
{
"doubleValue": 5.0
},
{
"doubleValue": 25.0
},
{
"doubleValue": 100.0
},
{
"doubleValue": 500.0
},
{
"doubleValue": 2000.0
}
]
}
}
},
{
"key": "counts",
"value": {
"arrayValue": {
"values": [
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "4"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
}
]
}
}
}
]
}
}
},
{
"key": "saved_pct",
"value": {
"kvlistValue": {
"values": [
{
"key": "edges",
"value": {
"arrayValue": {
"values": [
{
"doubleValue": 0.5
},
{
"doubleValue": 5.0
},
{
"doubleValue": 10.0
},
{
"doubleValue": 20.0
},
{
"doubleValue": 40.0
},
{
"doubleValue": 60.0
}
]
}
}
},
{
"key": "counts",
"value": {
"arrayValue": {
"values": [
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "4"
},
{
"intValue": "0"
},
{
"intValue": "0"
}
]
}
}
}
]
}
}
},
{
"key": "ttfb_ms",
"value": {
"kvlistValue": {
"values": [
{
"key": "edges",
"value": {
"arrayValue": {
"values": [
{
"doubleValue": 200.0
},
{
"doubleValue": 500.0
},
{
"doubleValue": 1000.0
},
{
"doubleValue": 2500.0
},
{
"doubleValue": 5000.0
},
{
"doubleValue": 15000.0
}
]
}
}
},
{
"key": "counts",
"value": {
"arrayValue": {
"values": [
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "4"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
}
]
}
}
}
]
}
}
},
{
"key": "turn_tokens",
"value": {
"kvlistValue": {
"values": [
{
"key": "edges",
"value": {
"arrayValue": {
"values": [
{
"intValue": "1000"
},
{
"intValue": "4000"
},
{
"intValue": "16000"
},
{
"intValue": "64000"
},
{
"intValue": "128000"
},
{
"intValue": "256000"
}
]
}
}
},
{
"key": "counts",
"value": {
"arrayValue": {
"values": [
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "4"
},
{
"intValue": "0"
},
{
"intValue": "0"
}
]
}
}
}
]
}
}
}
]
}
}
},
{
"key": "shapes",
"value": {
"kvlistValue": {
"values": [
{
"key": "by_content",
"value": {
"arrayValue": {
"values": []
}
}
},
{
"key": "by_tool",
"value": {
"arrayValue": {
"values": []
}
}
},
{
"key": "truncated",
"value": {
"boolValue": false
}
}
]
}
}
},
{
"key": "cache",
"value": {
"kvlistValue": {
"values": [
{
"key": "gap_edges_s",
"value": {
"arrayValue": {
"values": [
{
"doubleValue": 30.0
},
{
"doubleValue": 60.0
},
{
"doubleValue": 120.0
},
{
"doubleValue": 300.0
},
{
"doubleValue": 600.0
},
{
"doubleValue": 1800.0
}
]
}
}
},
{
"key": "hits",
"value": {
"arrayValue": {
"values": [
{
"intValue": "0"
},
{
"intValue": "3"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
}
]
}
}
},
{
"key": "misses",
"value": {
"arrayValue": {
"values": [
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
}
]
}
}
},
{
"key": "write_5m",
"value": {
"intValue": "24000"
}
},
{
"key": "write_1h",
"value": {
"intValue": "8000"
}
},
{
"key": "inferred_turns",
"value": {
"intValue": "0"
}
}
]
}
}
},
{
"key": "trajectory",
"value": {
"kvlistValue": {
"values": [
{
"key": "buckets",
"value": {
"intValue": "10"
}
},
{
"key": "turns",
"value": {
"arrayValue": {
"values": [
{
"intValue": "1"
},
{
"intValue": "2"
},
{
"intValue": "1"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
}
]
}
}
},
{
"key": "tokens",
"value": {
"arrayValue": {
"values": [
{
"intValue": "120000"
},
{
"intValue": "240000"
},
{
"intValue": "120000"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
}
]
}
}
},
{
"key": "saved",
"value": {
"arrayValue": {
"values": [
{
"intValue": "30000"
},
{
"intValue": "60000"
},
{
"intValue": "30000"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
},
{
"intValue": "0"
}
]
}
}
},
{
"key": "kinds",
"value": {
"stringValue": "s4"
}
},
{
"key": "kinds_truncated",
"value": {
"boolValue": false
}
},
{
"key": "msgs_max",
"value": {
"intValue": "140"
}
}
]
}
}
},
{
"key": "clients",
"value": {
"arrayValue": {
"values": [
{
"kvlistValue": {
"values": [
{
"key": "client",
"value": {
"stringValue": "claude_code"
}
},
{
"key": "n",
"value": {
"intValue": "4"
}
}
]
}
}
]
}
}
},
{
"key": "errors",
"value": {
"kvlistValue": {
"values": [
{
"key": "count",
"value": {
"intValue": "0"
}
},
{
"key": "by_status",
"value": {
"kvlistValue": {
"values": []
}
}
}
]
}
}
},
{
"key": "strata",
"value": {
"arrayValue": {
"values": []
}
}
},
{
"key": "config",
"value": {
"arrayValue": {
"values": []
}
}
}
]
}
}
}
]
}
]
}
]
}