Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

docs(telemetry): document headroom_stack and install_mode beacon fields

Garmd81b677f8025
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 33b09f290..4e75a837b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- **Telemetry stack & install-mode identity fields** — anonymous beacon now
+ reports `headroom_stack` (how Headroom is invoked: `proxy`, `wrap_claude`,
+ `adapter_ts_openai`, ...) and `install_mode` (`wrapped` / `persistent` /
+ `on_demand`), plus `requests_by_stack` for proxies that serve multiple
+ integrations. Proxy exposes a `by_stack` bucket alongside `by_provider` /
+ `by_model` on `/stats`, a matching `headroom_requests_by_stack` Prometheus
+ counter, and an `X-Headroom-Stack` header honored by the FastAPI middleware.
+ `headroom wrap <tool>` sets `HEADROOM_STACK=wrap_<agent>`; the TS SDK and
+ all four adapters (`openai`, `anthropic`, `gemini`, `vercel-ai`) tag their
+ compress calls. Schema migration:
+ [`sql/upgrade_telemetry_stack_context.sql`](sql/upgrade_telemetry_stack_context.sql).
- **Canonical filesystem contract** (issue #175) — new `HEADROOM_CONFIG_DIR`
(default `~/.headroom/config`, read-mostly) and `HEADROOM_WORKSPACE_DIR`
(default `~/.headroom`, read-write state) env vars recognized by the Python
diff --git a/wiki/metrics.md b/wiki/metrics.md
index 608ee9036..2b85e4ce2 100644
--- a/wiki/metrics.md
+++ b/wiki/metrics.md
@@ -162,6 +162,10 @@ headroom_tokens_saved_total 5678900
headroom_requests_by_provider{provider="anthropic"} 800
headroom_requests_by_provider{provider="openai"} 434
+# HELP headroom_requests_by_stack Requests by Headroom integration stack
+headroom_requests_by_stack{stack="wrap_claude"} 612
+headroom_requests_by_stack{stack="adapter_ts_openai"} 48
+
# HELP headroom_transform_timing_ms_sum Sum of transform timing in milliseconds
headroom_transform_timing_ms_sum{transform="router"} 5123.7
@@ -237,6 +241,27 @@ Headroom has two separate systems:
They are independent by design so you can disable the anonymous beacon while keeping OTEL metrics enabled, or vice versa.
+#### Beacon identity fields
+
+When the anonymous beacon is enabled, each report includes two identity fields
+so usage can be segmented by integration surface and deployment shape:
+
+- `headroom_stack` — how Headroom is invoked in this process. Values:
+ `proxy`, `wrap_<agent>` (e.g. `wrap_claude`, `wrap_codex`),
+ `adapter_<lang>_<provider>` (e.g. `adapter_ts_openai`), `mixed`
+ (multi-stack proxy with no dominant caller), or `unknown`. Overridable via
+ `HEADROOM_STACK`; `headroom wrap <tool>` sets it automatically.
+- `install_mode` — how the proxy is deployed. Values: `wrapped` (spawned by
+ `headroom wrap`), `persistent` (long-lived service on a fixed port),
+ `on_demand` (short-lived direct invocation), or `unknown`.
+- `requests_by_stack` — for proxies serving multiple integrations (e.g. a
+ persistent proxy hit by both `wrap_claude` and a TS adapter), a per-stack
+ request count dict mirroring the `headroom_requests_by_stack` counter.
+
+Clients tag requests with an `X-Headroom-Stack` header; the proxy's FastAPI
+middleware buckets these on `/v1/*`. Detection is best-effort — any failure
+falls back to `"unknown"` and never breaks the proxy.
+
### Langfuse
Langfuse fits next to this implementation as a **trace backend**, not as a metrics backend.