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.

Fix multi-worker beacon spam, cost dashboard, upsert telemetry; bump 0.5.17

chopratejase963c90b2c10
diff --git a/headroom/__init__.py b/headroom/__init__.py
index f73effd45..6960fe235 100644
--- a/headroom/__init__.py
+++ b/headroom/__init__.py
@@ -153,7 +153,7 @@ from .transforms import (
TransformPipeline,
)
-__version__ = "0.5.16"
+__version__ = "0.5.17"
__all__ = [
# Main client
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index e828b16dc..4f62bce63 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -7309,7 +7309,14 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
proxy = HeadroomProxy(config)
- # Telemetry beacon (anonymous aggregate stats)
+ # Telemetry beacon (anonymous aggregate stats).
+ # With uvicorn workers > 1, each worker runs the lifespan independently.
+ # We must ensure only ONE beacon runs across all workers — otherwise each
+ # worker creates its own beacon, spamming the telemetry table with N rows
+ # per cycle instead of 1 (all reading the same /stats from the same port).
+ #
+ # Strategy: use a file lock to ensure only the first worker starts the
+ # beacon. Other workers see the lock and skip.
from headroom.telemetry.beacon import TelemetryBeacon
_beacon = TelemetryBeacon(
@@ -7317,6 +7324,51 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
sdk=os.environ.get("HEADROOM_SDK", "proxy").strip() or "proxy",
backend=config.backend if hasattr(config, "backend") else "anthropic",
)
+ _beacon_lock_path = Path.home() / ".headroom" / f".beacon_lock_{config.port}"
+ _beacon_lock_fd: list = [None] # mutable holder for the lock file descriptor
+ _beacon_is_owner: list = [False]
+
+ def _try_acquire_beacon_lock() -> bool:
+ """Try to acquire the beacon file lock (non-blocking).
+
+ Returns True if this process is the beacon owner.
+ """
+ try:
+ _beacon_lock_path.parent.mkdir(parents=True, exist_ok=True)
+ import fcntl
+
+ fd = open(_beacon_lock_path, "w") # noqa: SIM115
+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+ fd.write(str(os.getpid()))
+ fd.flush()
+ _beacon_lock_fd[0] = fd
+ return True
+ except (OSError, ImportError):
+ # Lock held by another worker, or fcntl not available (Windows)
+ # On Windows, skip locking — workers are rare on Windows anyway
+ try:
+ import fcntl # noqa: F811
+
+ return False # Lock held by another worker
+ except ImportError:
+ return True # Windows: no fcntl, just allow it
+
+ def _release_beacon_lock() -> None:
+ """Release the beacon file lock."""
+ fd = _beacon_lock_fd[0]
+ if fd:
+ try:
+ import fcntl
+
+ fcntl.flock(fd, fcntl.LOCK_UN)
+ fd.close()
+ except Exception:
+ pass
+ _beacon_lock_fd[0] = None
+ try:
+ _beacon_lock_path.unlink(missing_ok=True)
+ except Exception:
+ pass
@asynccontextmanager
async def lifespan(app: FastAPI): # type: ignore[no-untyped-def]
@@ -7327,12 +7379,20 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
await proxy.usage_reporter.start(proxy)
if proxy.traffic_learner:
await proxy.traffic_learner.start()
- await _beacon.start()
+
+ # Only start beacon if we acquire the lock (first worker wins)
+ _beacon_is_owner[0] = _try_acquire_beacon_lock()
+ if _beacon_is_owner[0]:
+ await _beacon.start()
+ else:
+ logger.debug("Beacon: skipping (another worker owns the lock)")
yield
# Shutdown
- await _beacon.stop()
+ if _beacon_is_owner[0]:
+ await _beacon.stop()
+ _release_beacon_lock()
if proxy.usage_reporter:
await proxy.usage_reporter.stop()
if proxy.traffic_learner:
diff --git a/headroom/telemetry/beacon.py b/headroom/telemetry/beacon.py
index 91a44cd42..abd31285f 100644
--- a/headroom/telemetry/beacon.py
+++ b/headroom/telemetry/beacon.py
@@ -33,7 +33,7 @@ _SUPABASE_KEY = ".".join(
]
)
_TABLE = "proxy_telemetry_v2"
-_ENDPOINT = f"{_SUPABASE_URL}/rest/v1/{_TABLE}"
+_ENDPOINT = f"{_SUPABASE_URL}/rest/v1/{_TABLE}?on_conflict=session_id"
# Report every 5 minutes
_INTERVAL_SECONDS = 300
@@ -74,8 +74,11 @@ class TelemetryBeacon:
if self._task:
self._task.cancel()
self._task = None
- # Final report
- if is_telemetry_enabled():
+ # Final report — but only if the proxy ran for more than 2 minutes.
+ # Short-lived restarts (e.g. crash loops, orchestration churn) would
+ # otherwise spam the telemetry table with duplicate cumulative stats.
+ uptime_seconds = time.time() - self._start_time
+ if is_telemetry_enabled() and uptime_seconds > 120:
await self._report()
async def _loop(self) -> None:
@@ -250,7 +253,7 @@ class TelemetryBeacon:
except Exception:
logger.debug("Beacon: failed to extract waste signals", exc_info=True)
- # ---- Send to Supabase (fire-and-forget) ----
+ # ---- Send to Supabase (fire-and-forget, upsert on session_id) ----
try:
async with httpx.AsyncClient(timeout=10.0) as client:
await client.post(
@@ -260,7 +263,7 @@ class TelemetryBeacon:
"apikey": _SUPABASE_KEY,
"Authorization": f"Bearer {_SUPABASE_KEY}",
"Content-Type": "application/json",
- "Prefer": "return=minimal",
+ "Prefer": "resolution=merge-duplicates,return=minimal",
},
)
except Exception:
diff --git a/pyproject.toml b/pyproject.toml
index 9e3c0ab7e..ad14f702b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "headroom-ai"
-version = "0.5.16"
+version = "0.5.17"
description = "The Context Optimization Layer for LLM Applications - Cut costs by 50-90%"
readme = "README.md"
license = "Apache-2.0"