Merge pull request #60 from gglucass/feat/add-headroom-sdk

feat: allow overriding proxy telemetry sdk via HEADROOM_SDK

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

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

headroom/proxy/server.py

@@ -7000,7 +7000,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",
     )
 

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"