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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(proxy): allow disabling periodic TOIN stats logging (#1265)
wstczywb5f63d8fa9f8
diff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdxindex 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.pyindex 83b578bca..bd32fbc83 100644--- a/headroom/proxy/models.py+++ b/headroom/proxy/models.py@@ -294,6 +294,12 @@ class ProxyConfig:subscription_poll_interval_s: int = 300subscription_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 deploymentsstateless: bool = Falsediff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 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:# Startupawait 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.pyindex 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 asynciofrom unittest.mock import patchimport pytestpytest.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_appclass 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