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(proxy): allow disabling periodic TOIN stats logging (#1265)

wstczywb5f63d8fa9f8
diff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdx
index 98e20ad65..83f5993ef 100644
--- a/docs/content/docs/configuration.mdx
+++ b/docs/content/docs/configuration.mdx
@@ -235,6 +235,7 @@ headroom proxy --learn --min-evidence 3
| `HEADROOM_TOIN_PATH` | Override TOIN telemetry file location. Always wins when set. | derived from `${HEADROOM_WORKSPACE_DIR}` |
| `HEADROOM_SUBSCRIPTION_STATE_PATH` | Override subscription tracker state file. Always wins when set. | derived from `${HEADROOM_WORKSPACE_DIR}` |
| `HEADROOM_TELEMETRY` | Set to `on` to opt in to anonymous telemetry | `off` |
+| `HEADROOM_PERIODIC_TOIN_STATS` | Controls periodic TOIN stats logging in long-lived proxy workers. Set to `0`, `false`, `off`, or `no` to disable the 5-minute stats loop without disabling TOIN learning or request-time feedback. | `true` |
| `HEADROOM_MEMORY_INJECTION_MODE` | Memory-context routing mode: `live_zone_tail` (default) or `disabled`. The legacy `system_prompt` mode was retired by PR-A2; supplying it raises. | `live_zone_tail` |
| `HEADROOM_PROXY_PYTHON_FORWARDER_MODE` | Python forwarder serialization mode. `byte_faithful` (default) forwards original request bytes verbatim when no transform mutated the body and re-serializes canonically only when needed — keeps Anthropic prompt-cache hit-rate intact. `legacy_json_kwarg` is an explicit operator opt-in for emergency rollback to the historical `httpx ... json=body` behavior. NOT a fallback — only flip on explicit operator decision. | `byte_faithful` |
| `HEADROOM_STRIP_INTERNAL_HEADERS` | Python proxy: whether to strip internal `x-headroom-*` request headers (e.g. `x-headroom-bypass`, `x-headroom-mode`, `x-headroom-user-id`, `x-headroom-stack`, `x-headroom-base-url`) before every upstream forwarder call (PR-A5, fixes P5-49). `enabled` (default) stops fingerprinting / leakage. `disabled` is an explicit operator opt-in for diagnostic shadow tracing — NOT a fallback. Inbound reads of these headers (bypass gating, memory user-id resolution) are unaffected because they read `request.headers` directly. | `enabled` |
diff --git a/headroom/proxy/models.py b/headroom/proxy/models.py
index 83b578bca..bd32fbc83 100644
--- a/headroom/proxy/models.py
+++ b/headroom/proxy/models.py
@@ -294,6 +294,12 @@ class ProxyConfig:
subscription_poll_interval_s: int = 300
subscription_active_window_s: int = 60
+ # Periodic TOIN stats logging. Enabled by default for observability, but
+ # operators of long-lived proxies can disable it if TOIN stats collection
+ # causes avoidable memory pressure on their platform.
+ # Env: HEADROOM_PERIODIC_TOIN_STATS=0.
+ periodic_toin_stats_enabled: bool = True
+
# Stateless mode — disable all filesystem writes for read-only / container deployments
stateless: bool = False
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index f38b4aa6c..4a736f9c9 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -1810,7 +1810,8 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
try:
# Startup
await proxy.startup()
- asyncio.create_task(_log_toin_stats_periodically())
+ if config.periodic_toin_stats_enabled:
+ asyncio.create_task(_log_toin_stats_periodically())
if proxy.usage_reporter:
await proxy.usage_reporter.start(proxy)
if proxy.traffic_learner:
@@ -3740,6 +3741,7 @@ def _proxy_config_from_env() -> ProxyConfig:
max_connections=_get_env_int("HEADROOM_MAX_CONNECTIONS", 500),
max_keepalive_connections=_get_env_int("HEADROOM_MAX_KEEPALIVE", 100),
http2=_get_env_bool("HEADROOM_HTTP2", True),
+ periodic_toin_stats_enabled=_get_env_bool("HEADROOM_PERIODIC_TOIN_STATS", True),
mode=normalize_proxy_mode(_get_env_str("HEADROOM_MODE", PROXY_MODE_TOKEN)),
)
diff --git a/tests/test_proxy_telemetry_env.py b/tests/test_proxy_telemetry_env.py
index 68f9ef866..489f8293b 100644
--- a/tests/test_proxy_telemetry_env.py
+++ b/tests/test_proxy_telemetry_env.py
@@ -1,12 +1,15 @@
"""Tests for proxy telemetry environment variable handling."""
+import asyncio
from unittest.mock import patch
import pytest
pytest.importorskip("fastapi")
-from headroom.proxy.server import ProxyConfig, create_app
+from fastapi.testclient import TestClient
+
+from headroom.proxy.server import ProxyConfig, _proxy_config_from_env, create_app
class TestProxyTelemetrySDKEnv:
@@ -56,3 +59,58 @@ class TestProxyTelemetrySDKEnv:
)
assert mock_beacon.call_args.kwargs["sdk"] == "proxy"
+
+
+class TestProxyPeriodicTOINStatsEnv:
+ """Test HEADROOM_PERIODIC_TOIN_STATS handling for long-lived proxy workers."""
+
+ def test_periodic_toin_stats_enabled_by_default(self, monkeypatch):
+ """Periodic TOIN stats logging remains enabled unless explicitly disabled."""
+ monkeypatch.delenv("HEADROOM_PERIODIC_TOIN_STATS", raising=False)
+
+ config = _proxy_config_from_env()
+
+ assert config.periodic_toin_stats_enabled is True
+
+ @pytest.mark.parametrize("value", ["0", "false", "off", "no"])
+ def test_periodic_toin_stats_can_be_disabled_by_env(self, monkeypatch, value):
+ """HEADROOM_PERIODIC_TOIN_STATS=0/false/off/no disables periodic logging."""
+ monkeypatch.setenv("HEADROOM_PERIODIC_TOIN_STATS", value)
+
+ config = _proxy_config_from_env()
+
+ assert config.periodic_toin_stats_enabled is False
+
+ def test_lifespan_skips_periodic_toin_stats_when_disabled(self, monkeypatch):
+ """Disabling periodic TOIN stats avoids scheduling the stats loop."""
+ monkeypatch.setenv("HEADROOM_SKIP_UPSTREAM_CHECK", "1")
+ requested = False
+
+ def fake_periodic_toin_stats():
+ nonlocal requested
+ requested = True
+
+ async def noop():
+ await asyncio.sleep(0)
+
+ return noop()
+
+ monkeypatch.setattr(
+ "headroom.proxy.server._log_toin_stats_periodically",
+ fake_periodic_toin_stats,
+ )
+
+ app = create_app(
+ ProxyConfig(
+ optimize=False,
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=False,
+ periodic_toin_stats_enabled=False,
+ )
+ )
+
+ with TestClient(app):
+ pass
+
+ assert requested is False