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.

feat: allow overriding proxy telemetry sdk via HEADROOM_SDK

Garm8232e7822e75
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1a68f4ac2..224de9dba 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- **Proxy telemetry SDK override** via `HEADROOM_SDK`
+ - Downstream apps can override the anonymous telemetry `sdk` field without patching installed files
+ - Blank values fall back to the default `proxy` label
- **`headroom learn`** — Offline failure learning for coding agents
- Analyzes past conversation history (Claude Code, extensible to Cursor/Codex)
- **Success correlation**: for each failure, finds what succeeded after and extracts the specific correction
diff --git a/docs/proxy.md b/docs/proxy.md
index ef805df17..e1e8a661d 100644
--- a/docs/proxy.md
+++ b/docs/proxy.md
@@ -21,6 +21,8 @@ headroom proxy \
--budget 100.0
```
+Telemetry is enabled by default. Opt out with `HEADROOM_TELEMETRY=off` or `headroom proxy --no-telemetry`. Downstream apps can set `HEADROOM_SDK=headroom-app` to override the anonymous telemetry `sdk` label; the default remains `proxy`.
+
## Command Line Options
### Core Options
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index a5a62c3a2..5e1e4359d 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -6966,7 +6966,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
_beacon = TelemetryBeacon(
port=config.port if hasattr(config, "port") else 8787,
- sdk="proxy",
+ sdk=os.environ.get("HEADROOM_SDK", "proxy").strip() or "proxy",
backend=config.backend if hasattr(config, "backend") else "anthropic",
)
diff --git a/tests/test_proxy_telemetry_env.py b/tests/test_proxy_telemetry_env.py
new file mode 100644
index 000000000..68f9ef866
--- /dev/null
+++ b/tests/test_proxy_telemetry_env.py
@@ -0,0 +1,58 @@
+"""Tests for proxy telemetry environment variable handling."""
+
+from unittest.mock import patch
+
+import pytest
+
+pytest.importorskip("fastapi")
+
+from headroom.proxy.server import ProxyConfig, create_app
+
+
+class TestProxyTelemetrySDKEnv:
+ """Test HEADROOM_SDK handling when the proxy builds telemetry beacons."""
+
+ def test_proxy_telemetry_sdk_defaults_to_proxy(self, monkeypatch):
+ """Telemetry beacon uses the default SDK label when env var is unset."""
+ monkeypatch.delenv("HEADROOM_SDK", raising=False)
+
+ with patch("headroom.telemetry.beacon.TelemetryBeacon") as mock_beacon:
+ create_app(
+ ProxyConfig(
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=False,
+ )
+ )
+
+ assert mock_beacon.call_args.kwargs["sdk"] == "proxy"
+
+ def test_proxy_telemetry_sdk_uses_env_override(self, monkeypatch):
+ """Telemetry beacon uses HEADROOM_SDK when it is non-empty."""
+ monkeypatch.setenv("HEADROOM_SDK", "headroom-app")
+
+ with patch("headroom.telemetry.beacon.TelemetryBeacon") as mock_beacon:
+ create_app(
+ ProxyConfig(
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=False,
+ )
+ )
+
+ assert mock_beacon.call_args.kwargs["sdk"] == "headroom-app"
+
+ def test_proxy_telemetry_sdk_empty_env_falls_back_to_proxy(self, monkeypatch):
+ """Telemetry beacon falls back to proxy when HEADROOM_SDK is blank."""
+ monkeypatch.setenv("HEADROOM_SDK", " ")
+
+ with patch("headroom.telemetry.beacon.TelemetryBeacon") as mock_beacon:
+ create_app(
+ ProxyConfig(
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=False,
+ )
+ )
+
+ assert mock_beacon.call_args.kwargs["sdk"] == "proxy"