mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
53be64ca12
## Description
Removes the anonymous-telemetry **beacon** — the only external,
third-party data flow Headroom ever initiated. When telemetry was opted
in, it POSTed aggregate `/stats` to a hardcoded **Supabase** REST
endpoint (with an embedded anon API key in the source). For
enterprise/on-prem deployments this is exactly the kind of
vendor-controlled data egress a security review flags, so it's gone
entirely — **zero "Supabase" references remain in the codebase.**
What stays (by design): the **local** telemetry collector + the
`HEADROOM_TELEMETRY` opt-in (it only feeds `/stats` and `/v1/telemetry`
— nothing leaves the process), **OpenTelemetry export**
(`HEADROOM_OTEL_METRICS_*`, so operators send operational metrics to
*their own* collector), and the license usage reporter (your own domain,
license-key-gated).
Also fixes the contact domain: `headroom.dev` → `headroomlabs.ai`
everywhere.
Closes # (no tracking issue)
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)
> Non-breaking: `HEADROOM_TELEMETRY` is still accepted (now gates local
collection only). The only behavior change is that no telemetry is ever
sent externally.
## Changes Made
- **Deleted the Supabase beacon**: `TelemetryBeacon` class,
`_SUPABASE_URL`/`_SUPABASE_KEY`/`_TABLE`/`_ENDPOINT`, the JSONB
projection helper, the proxy-lifespan beacon wiring, the `SUPABASE_`
install env passthrough, and `tests/test_strategy_stats_supabase.py`.
- **Kept** the local opt-in predicate (`is_telemetry_enabled` etc.) in
`beacon.py` — still used by the local collector + CLI — reworded to
"local only".
- **Retained** the single-worker-owner file lock (the cc-switch
reconciler depends on it); updated its comments to drop the beacon
framing.
- `/stats` `anon_telemetry_shipping` is now always `False` (nothing
ships externally); startup log reworded to "Local telemetry".
- Reworded remaining "Supabase" comments in `collector.py`,
`context.py`, `prometheus_metrics.py`, and two test docstrings.
- Contact domain: `security@headroom.dev` → `security@headroomlabs.ai`,
`conduct@headroom.dev` → `conduct@headroomlabs.ai`, FUNDING.yml sponsor
URL.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check`)
- [x] Type checking passes (`mypy`)
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ grep -rniI "supabase" --include=*.py --include=*.md --include=*.mdx . # (excl .venv/sbom)
>>> ZERO Supabase references
$ grep -rniI "headroom.dev" .
>>> ZERO headroom.dev references
$ ruff check <changed files> -> All checks passed!
$ ruff format --check <changed files> -> 10 files already formatted
$ mypy <changed telemetry files> -> Success: no issues found
$ pytest tests/test_telemetry.py tests/test_telemetry_warning.py \
tests/test_proxy_telemetry_env.py tests/test_compression_observability.py \
tests/test_paths.py tests/test_paths_backward_compat.py -q
============================= 173 passed in 6.67s ==============================
```
## Real Behavior Proof
- **Environment:** macOS, Python 3.12 (`.venv`).
- **Exact command / steps:** repo-wide grep for
`supabase`/`headroom.dev`; `create_app(...)` driven through a full
`TestClient` lifespan (startup + shutdown) in
`test_proxy_telemetry_env.py`; `/stats` exercised in
`test_telemetry_warning.py`.
- **Observed result:** zero `supabase`/`headroom.dev` strings remain;
the proxy starts and shuts down cleanly with the beacon removed (the
worker-owner lock + reconciler still elect a single owner);
`/stats.anon_telemetry_shipping` is `False` even with
`HEADROOM_TELEMETRY=on`; local collector + OTEL paths unchanged.
- **Not tested:** no live network call was ever made (the point — the
external POST is gone). OTEL export and the license reporter were not
exercised (unchanged by this PR).
## 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
- [ ] 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
- [ ] I have updated the CHANGELOG.md if applicable
## Additional Notes
- The license usage reporter (`reporter.py` → `app.headroomlabs.ai`) is
intentionally **kept** — it's license-key-gated (dormant for
unlicensed/OSS deployments) and goes to your own domain, not a third
party.
- Docs/CHANGELOG left unchecked: a couple of docs mention the telemetry
beacon and may want a follow-up note that it now collects locally only;
happy to add.
60 lines
2.4 KiB
Python
60 lines
2.4 KiB
Python
"""Telemetry opt-in state for Headroom.
|
|
|
|
Headroom collects only **local**, aggregate telemetry (tokens saved, compression
|
|
ratios, timings) for the in-process collector and the ``/stats`` /
|
|
``/v1/telemetry`` endpoints. **Nothing is sent to Headroom Labs:** the anonymous
|
|
telemetry beacon that previously shipped aggregate stats has been removed.
|
|
Operational metrics can still be exported to *your own* OpenTelemetry collector
|
|
via ``HEADROOM_OTEL_METRICS_*`` (a destination you control).
|
|
|
|
This module holds the ``HEADROOM_TELEMETRY`` opt-in predicate (off by default)
|
|
that gates local collection, plus the CLI notice helpers.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import os
|
|
|
|
_OFF_VALUES = frozenset(("off", "false", "0", "no", "disable", "disabled"))
|
|
_ON_VALUES = frozenset(("on", "true", "1", "yes", "enable", "enabled"))
|
|
|
|
|
|
def is_telemetry_enabled() -> bool:
|
|
"""Check if local telemetry collection is enabled (off by default, opt-in).
|
|
|
|
Fail-closed: only enabled when HEADROOM_TELEMETRY is set to an explicit
|
|
on-value (on/true/1/yes/enable/enabled). Anything else — including unset,
|
|
empty, or an unrecognized value — leaves it disabled. Local collection only
|
|
feeds the in-process collector and the ``/stats`` endpoint; nothing is
|
|
transmitted to Headroom Labs.
|
|
"""
|
|
val = os.environ.get("HEADROOM_TELEMETRY", "").lower().strip()
|
|
return val in _ON_VALUES
|
|
|
|
|
|
def is_telemetry_warn_enabled() -> bool:
|
|
"""Check if telemetry warnings are enabled (feature flag, on by default).
|
|
|
|
Set HEADROOM_TELEMETRY_WARN=off to suppress startup/wrap notices.
|
|
This is a build/pack-time feature flag intended for operators who want
|
|
to disable the notice without disabling telemetry itself.
|
|
"""
|
|
val = os.environ.get("HEADROOM_TELEMETRY_WARN", "on").lower().strip()
|
|
return val not in _OFF_VALUES
|
|
|
|
|
|
def format_telemetry_notice(*, prefix: str = "") -> str:
|
|
"""Return a single-line telemetry notice suitable for CLI output.
|
|
|
|
Args:
|
|
prefix: Optional leading whitespace / box-drawing prefix.
|
|
|
|
Returns an empty string when telemetry or warnings are disabled so callers
|
|
can unconditionally include the result in their output.
|
|
"""
|
|
if not is_telemetry_enabled() or not is_telemetry_warn_enabled():
|
|
return ""
|
|
return (
|
|
f"{prefix}Telemetry: ENABLED (local aggregate stats only — nothing sent externally) | "
|
|
"Disable: HEADROOM_TELEMETRY=off or --no-telemetry"
|
|
)
|