mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
b99869778b
## Description
Anonymous usage telemetry was **on by default** (opt-out). This flips it
to **opt-in**: nothing is collected or shipped unless the user
explicitly turns it on. Small change, but it makes "no data leaves the
proxy by default" the actual default rather than something users have to
discover and disable.
Closes # <!-- N/A: no tracking issue -->
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality) — adds
`--telemetry` opt-in flag
- [x] Breaking change (fix or feature that would cause existing
functionality to change) — telemetry no longer runs unless opted in
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- `is_telemetry_enabled()` is now **fail-closed**: only explicit
on-values (`on`/`true`/`1`/`yes`/`enable`/`enabled`) enable telemetry;
unset, empty, or unrecognized values stay disabled. This single
predicate gates both the Supabase beacon and the local `/v1/telemetry`
collector.
- Added `--telemetry` opt-in flag to `headroom proxy` and `headroom
install apply`; kept `--no-telemetry` and `HEADROOM_TELEMETRY=off` for
back-compat. If both are passed, opt-out wins.
- Install manifests now write `HEADROOM_TELEMETRY` explicitly
(`on`/`off`) plus the matching flag, so generated systemd/docker/launchd
deployments are unambiguous and don't rely on the runtime default.
- Startup banner and proxy log show `DISABLED` by default and surface
how to opt in.
- Updated tests for opt-in defaults; added coverage for the default-off
banner, the `--telemetry` flag, and the explicit-on manifest path.
- Updated docs
(proxy/configuration/installation/benchmarks/community-savings mdx, spec
011/015, wiki proxy/cli/benchmarks/metrics) and `CHANGELOG.md`.
## Testing
- [x] Unit tests pass (`pytest`) — targeted telemetry + install-planner
suites
- [x] Linting passes (`ruff check`)
- [x] Type checking passes (`mypy`)
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ python -m pytest tests/test_telemetry_warning.py tests/test_telemetry.py tests/test_install/test_planner.py -q
81 passed
$ ruff check <changed source + test files>
All checks passed!
$ mypy headroom/telemetry/beacon.py headroom/cli/proxy.py headroom/cli/install.py \
headroom/install/planner.py headroom/proxy/server.py
Success: no issues found in 5 source files
```
## Real Behavior Proof
- **Environment:** macOS (darwin 25.4.0), project `.venv`, `headroom`
CLI.
- **Exact command / steps:**
```
$ python -c "import os; from headroom.telemetry.beacon import
is_telemetry_enabled; \
os.environ.pop('HEADROOM_TELEMETRY', None); print('unset ->',
is_telemetry_enabled()); \
[ (os.environ.__setitem__('HEADROOM_TELEMETRY', v), print(repr(v), '->',
is_telemetry_enabled())) \
for v in ['on','TRUE','1','yes','off','0','garbage',''] ]"
$ headroom proxy --help | grep -i telemetry
$ headroom install apply --help | grep -i telemetry
```
- **Observed result:**
```
unset -> False # off by default
'on' -> True 'TRUE' -> True '1' -> True 'yes' -> True
'off' -> False '0' -> False
'garbage' -> False '' -> False # fail-closed
proxy: --telemetry Opt in to anonymous usage telemetry — off by default
(env: HEADROOM_TELEMETRY=on)
--no-telemetry Force anonymous usage telemetry off (already the default;
env: HEADROOM_TELEMETRY=off)
install: --telemetry Opt in to anonymous telemetry in the runtime (off
by default).
--no-telemetry Force anonymous telemetry off in the runtime (already the
default).
```
- **Not tested:** live Supabase beacon network round-trip (no opt-in
network call was made); full `pytest` suite was not run — only the
telemetry + install-planner targeted suites.
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I have updated the CHANGELOG.md if applicable
## Additional Notes
- "Breaking change" is checked because the default behavior changes
(telemetry stops running unless opted in). It is **not** an API break —
`--no-telemetry` and `HEADROOM_TELEMETRY=off` still work, so existing
opt-out configs are unaffected.
- No tracking issue, so `Closes #` is left N/A.
104 lines
3.7 KiB
Python
104 lines
3.7 KiB
Python
from __future__ import annotations
|
|
|
|
from headroom.install.models import ConfigScope, InstallPreset, ProviderSelectionMode, ToolTarget
|
|
from headroom.install.planner import build_manifest, resolve_targets
|
|
|
|
|
|
def test_resolve_targets_auto_falls_back_when_detection_empty(monkeypatch) -> None:
|
|
monkeypatch.setattr("headroom.install.planner.detect_targets", lambda: [])
|
|
|
|
targets = resolve_targets(ProviderSelectionMode.AUTO.value, [])
|
|
|
|
assert targets == [
|
|
ToolTarget.CLAUDE.value,
|
|
ToolTarget.CODEX.value,
|
|
ToolTarget.COPILOT.value,
|
|
]
|
|
|
|
|
|
def test_build_manifest_for_persistent_docker_sets_expected_defaults() -> None:
|
|
manifest = build_manifest(
|
|
profile="default",
|
|
preset=InstallPreset.PERSISTENT_DOCKER.value,
|
|
runtime_kind="docker",
|
|
scope="user",
|
|
provider_mode="manual",
|
|
targets=["claude", "copilot"],
|
|
port=8787,
|
|
backend="anthropic",
|
|
anyllm_provider=None,
|
|
region=None,
|
|
proxy_mode="token",
|
|
memory_enabled=True,
|
|
telemetry_enabled=False,
|
|
image="ghcr.io/chopratejas/headroom:latest",
|
|
)
|
|
|
|
assert manifest.supervisor_kind == "none"
|
|
assert manifest.runtime_kind == "docker"
|
|
assert manifest.health_url == "http://127.0.0.1:8787/readyz"
|
|
assert manifest.base_env["HEADROOM_PORT"] == "8787"
|
|
assert manifest.base_env["HEADROOM_TELEMETRY"] == "off"
|
|
assert "--no-telemetry" in manifest.proxy_args
|
|
assert manifest.tool_envs["claude"]["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:8787"
|
|
assert manifest.tool_envs["copilot"]["COPILOT_PROVIDER_TYPE"] == "anthropic"
|
|
assert "--memory" in manifest.proxy_args
|
|
|
|
|
|
def test_build_manifest_uses_provider_slice_env_builders_for_all_supported_targets() -> None:
|
|
manifest = build_manifest(
|
|
profile="default",
|
|
preset=InstallPreset.PERSISTENT_SERVICE.value,
|
|
runtime_kind="python",
|
|
scope="user",
|
|
provider_mode="manual",
|
|
targets=["claude", "copilot", "codex", "aider", "cursor"],
|
|
port=9999,
|
|
backend="anyllm",
|
|
anyllm_provider="groq",
|
|
region=None,
|
|
proxy_mode="token",
|
|
memory_enabled=False,
|
|
telemetry_enabled=True,
|
|
image="ghcr.io/chopratejas/headroom:latest",
|
|
)
|
|
|
|
# telemetry_enabled=True must write the explicit opt-in value + flag.
|
|
assert manifest.base_env["HEADROOM_TELEMETRY"] == "on"
|
|
assert "--telemetry" in manifest.proxy_args
|
|
assert manifest.tool_envs["claude"]["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9999"
|
|
assert manifest.tool_envs["codex"]["OPENAI_BASE_URL"] == "http://127.0.0.1:9999/v1"
|
|
assert manifest.tool_envs["aider"] == {
|
|
"OPENAI_API_BASE": "http://127.0.0.1:9999/v1",
|
|
"ANTHROPIC_BASE_URL": "http://127.0.0.1:9999",
|
|
}
|
|
assert manifest.tool_envs["cursor"] == {
|
|
"OPENAI_BASE_URL": "http://127.0.0.1:9999/v1",
|
|
"ANTHROPIC_BASE_URL": "http://127.0.0.1:9999",
|
|
}
|
|
assert manifest.tool_envs["copilot"] == {
|
|
"COPILOT_PROVIDER_TYPE": "openai",
|
|
"COPILOT_PROVIDER_BASE_URL": "http://127.0.0.1:9999/v1",
|
|
"COPILOT_PROVIDER_WIRE_API": "completions",
|
|
}
|
|
|
|
|
|
def test_resolve_targets_provider_scope_auto_excludes_copilot(monkeypatch) -> None:
|
|
monkeypatch.setattr("headroom.install.planner.detect_targets", lambda: [])
|
|
|
|
targets = resolve_targets(
|
|
ProviderSelectionMode.AUTO.value,
|
|
[],
|
|
scope=ConfigScope.PROVIDER.value,
|
|
)
|
|
|
|
assert targets == [ToolTarget.CLAUDE.value, ToolTarget.CODEX.value]
|
|
|
|
|
|
def test_resolve_targets_manual_dedupes_and_filters_invalid() -> None:
|
|
targets = resolve_targets(
|
|
ProviderSelectionMode.MANUAL.value,
|
|
["claude", "copilot", "claude", "invalid"],
|
|
)
|
|
|
|
assert targets == [ToolTarget.CLAUDE.value, ToolTarget.COPILOT.value]
|