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.

perf(proxy): gate /debug/tasks stack-depth computation behind query param

Adryan Eka Vandra8bbf3afda048
diff --git a/headroom/proxy/debug_introspection.py b/headroom/proxy/debug_introspection.py
index 80e284ed9..60254a8e2 100644
--- a/headroom/proxy/debug_introspection.py
+++ b/headroom/proxy/debug_introspection.py
@@ -113,6 +113,8 @@ def _age_for_named_task(
def collect_tasks(
ws_registry: WebSocketSessionRegistry | None = None,
+ *,
+ with_stack_depth: bool = False,
) -> list[dict[str, Any]]:
"""Enumerate ``asyncio.all_tasks()`` for /debug/tasks.
@@ -121,6 +123,12 @@ def collect_tasks(
and ``done``. Sorted by age descending with ``None`` ages sorted
after known ages. System noise (``None`` tasks, tasks with no
coroutine) is filtered out.
+
+ ``stack_depth`` is only computed when ``with_stack_depth=True``
+ because :meth:`asyncio.Task.get_stack` walks coroutine frames and
+ can noticeably stall the event loop during a storm with 50+ relay
+ tasks. The default returns ``stack_depth=None``; callers that need
+ it (a human debugging one snapshot) can pass ``with_stack_depth=True``.
"""
try:
tasks = asyncio.all_tasks()
@@ -145,7 +153,7 @@ def collect_tasks(
"name": name,
"coro_qualname": qualname,
"age_seconds": age,
- "stack_depth": _stack_depth(task),
+ "stack_depth": _stack_depth(task) if with_stack_depth else None,
"done": bool(task.done()),
}
entries.append(entry)
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index 61f6e8765..5eb9dbd8e 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -1335,9 +1335,19 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
from headroom.proxy.loopback_guard import require_loopback as _require_loopback
@app.get("/debug/tasks", dependencies=[Depends(_require_loopback)])
- async def debug_tasks():
+ async def debug_tasks(stack: bool = False):
+ """Enumerate running asyncio tasks.
+
+ Default is cheap — ``stack_depth`` is ``null`` in every entry so
+ a storm snapshot does not walk 50+ coroutine frames synchronously.
+ Pass ``?stack=true`` to compute ``stack_depth`` for each task
+ (useful for single-shot human debugging).
+ """
ws_registry = getattr(proxy, "ws_sessions", None)
- return JSONResponse(status_code=200, content=_collect_tasks(ws_registry))
+ return JSONResponse(
+ status_code=200,
+ content=_collect_tasks(ws_registry, with_stack_depth=stack),
+ )
@app.get("/debug/ws-sessions", dependencies=[Depends(_require_loopback)])
async def debug_ws_sessions():
diff --git a/tests/test_proxy_debug_endpoints.py b/tests/test_proxy_debug_endpoints.py
index f7b1e1ec2..c64f4228e 100644
--- a/tests/test_proxy_debug_endpoints.py
+++ b/tests/test_proxy_debug_endpoints.py
@@ -256,6 +256,37 @@ def test_debug_tasks_returns_json_array_for_loopback(client):
assert "coro_qualname" in entry
+def test_debug_tasks_stack_depth_is_gated_behind_query(client):
+ """Default response must not compute stack_depth (P3 Fix 29 perf gate).
+
+ ``?stack=true`` opts into the synchronous ``Task.get_stack`` walk; the
+ default stays cheap so snapshotting during a reconnect storm does
+ not stall the event loop.
+ """
+ default = client.get("/debug/tasks")
+ assert default.status_code == 200
+ for entry in default.json():
+ assert entry["stack_depth"] is None, (
+ f"default /debug/tasks must not compute stack_depth; "
+ f"got {entry['stack_depth']!r} for {entry.get('name')!r}"
+ )
+
+ with_stack = client.get("/debug/tasks?stack=true")
+ assert with_stack.status_code == 200
+ entries = with_stack.json()
+ # At least one entry should have a computed depth (the TestClient
+ # itself runs under a task). Some entries may still be None if
+ # get_stack raised defensively — we only require that opting in
+ # produces at least one integer result.
+ integer_depths = [
+ e["stack_depth"] for e in entries if isinstance(e["stack_depth"], int)
+ ]
+ assert integer_depths, (
+ "expected at least one int stack_depth when ?stack=true; "
+ f"got entries={entries!r}"
+ )
+
+
def test_debug_warmup_reports_registry_slots(client):
response = client.get("/debug/warmup")
assert response.status_code == 200