Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

perf(telemetry): stop making every command wait out its own telemetry POST (#1286)

Raghav Chamadiyaf2215e7c70f6
diff --git a/docs/reference/TELEMETRY.md b/docs/reference/TELEMETRY.md
index c0e8f7bbe..2c9017034 100644
--- a/docs/reference/TELEMETRY.md
+++ b/docs/reference/TELEMETRY.md
@@ -123,6 +123,18 @@ username, or any machine identifier, so it cannot be reversed to a person. It
only lets us count distinct installs. Delete the file and a new, unrelated id
is generated; nothing links the two.
+## When events are sent
+
+A command never waits on the network to record an event. It appends the
+envelope to `~/.repowise/telemetry-spool.jsonl` and, on exit, starts a small
+detached process that sends what is queued and removes the file. So the send
+costs you nothing in command time, and you can read the queued file to see
+exactly what is about to leave your machine.
+
+If the send fails the queued events are discarded, not retried. Disabling
+telemetry also discards anything still queued, so a disable is never followed
+by one last batch.
+
## Verify it yourself
Run any command with `REPOWISE_TELEMETRY_DEBUG=1` to print the exact payload to
diff --git a/packages/cli/src/repowise/cli/platform/telemetry/emitter.py b/packages/cli/src/repowise/cli/platform/telemetry/emitter.py
index a73b02fef..c6dcdddd2 100644
--- a/packages/cli/src/repowise/cli/platform/telemetry/emitter.py
+++ b/packages/cli/src/repowise/cli/platform/telemetry/emitter.py
@@ -1,9 +1,24 @@
"""Build the wire envelope for an event and send it, best-effort.
-Sending is fire-and-forget on a daemon thread so a slow or unreachable backend
-never delays a CLI command. An ``atexit`` flush briefly joins in-flight sends
-so short-lived invocations still deliver. Everything here is fail-silent: a
-telemetry failure must never surface to the user.
+Recording an event appends it to an on-disk spool and returns, so nothing on
+the recording path talks to the network. On exit the process spawns a detached
+flusher (:mod:`.flusher`) to deliver what is queued and dies without waiting
+for it.
+
+That indirection is the point. Sending used to happen on a daemon thread that
+``atexit`` joined for up to 2s, which meant every short command paid the POST
+(~750ms measured) after its output was already printed — the CLI waiting on the
+network is exactly what the fire-and-forget thread was supposed to prevent, and
+a thread cannot outlive the interpreter that owns it. A separate process can,
+so delivery no longer competes with exit: the spawn costs a few milliseconds
+and the network cost lands where nobody is waiting on it.
+
+Delivery is still best-effort — a batch the backend refuses is dropped rather
+than retried (see :mod:`.spool`) — so this trades none of the old design's
+guarantees, only its latency.
+
+Everything here is fail-silent: a telemetry failure must never surface to the
+user.
"""
from __future__ import annotations
@@ -11,19 +26,16 @@ from __future__ import annotations
import atexit
import contextlib
import json
+import os
+import subprocess
import sys
-import threading
from repowise.cli.platform import identity, settings
-from repowise.cli.platform.client import default_client
-from repowise.cli.platform.telemetry import environment
+from repowise.cli.platform.telemetry import environment, spool
from repowise.cli.platform.telemetry.events import TelemetryEvent
-#: Backend ingestion path (joined to the platform base URL by the client).
-_INGEST_PATH = "telemetry/events"
-
-#: In-flight send threads, joined briefly at exit so quick commands deliver.
-_pending: list[threading.Thread] = []
+#: Module the detached flusher runs as.
+_FLUSHER_MODULE = "repowise.cli.platform.telemetry.flusher"
def _cli_version() -> str:
@@ -35,6 +47,18 @@ def _cli_version() -> str:
return "unknown"
+def _under_test() -> bool:
+ """Return whether we are running inside a pytest session.
+
+ The suite drives real CLI commands, and its fixtures relocate the home
+ directory that holds ``anon_id``, so without this every test run delivers
+ events under a freshly minted install. Only delivery is suppressed:
+ consent resolution stays real, so its own tests still exercise the actual
+ precedence rules.
+ """
+ return "PYTEST_CURRENT_TEST" in os.environ or "pytest" in sys.modules
+
+
def build_envelope(event: TelemetryEvent) -> dict[str, object]:
"""Assemble the anonymous wire envelope for *event*."""
envelope: dict[str, object] = {
@@ -49,7 +73,7 @@ def build_envelope(event: TelemetryEvent) -> dict[str, object]:
def record(event: TelemetryEvent) -> None:
- """Record *event*: respect consent, then debug-print or send. Never raises."""
+ """Record *event*: respect consent, then debug-print or queue. Never raises."""
try:
if not settings.is_enabled():
return
@@ -63,35 +87,47 @@ def record(event: TelemetryEvent) -> None:
)
return
- thread = threading.Thread(
- target=default_client.post,
- args=(_INGEST_PATH, envelope),
- daemon=True,
- )
- thread.start()
- # Prune finished sends so a long-lived process (e.g. ``serve``/``watch``)
- # emitting many events never accumulates dead Thread objects.
- _pending[:] = [t for t in _pending if t.is_alive()]
- _pending.append(thread)
+ spool.append(envelope)
except Exception:
# Telemetry must never break a command.
return
-def _flush() -> None:
- """Give in-flight sends a brief moment to complete on process exit.
+def _spawn_flusher() -> bool:
+ """Start the detached delivery process. Returns whether it started.
- Bounded to ~2s total across all pending sends so exit is never noticeably
- delayed even if the backend is hung.
+ Fully detached (own session/console, no inherited streams) so it keeps
+ running after this process exits and can never write to the user's
+ terminal.
"""
- import time
-
- remaining = 2.0
- for thread in _pending:
- if remaining <= 0:
- break
- start = time.monotonic()
- with contextlib.suppress(Exception):
- thread.join(timeout=remaining)
- remaining -= time.monotonic() - start
+ if not sys.executable:
+ return False
+ kwargs: dict[str, object] = {
+ "stdin": subprocess.DEVNULL,
+ "stdout": subprocess.DEVNULL,
+ "stderr": subprocess.DEVNULL,
+ "close_fds": True,
+ "cwd": os.getcwd(),
+ }
+ if os.name == "nt":
+ # DETACHED_PROCESS | CREATE_NO_WINDOW: no console window flashes up
+ # in front of the user between commands.
+ kwargs["creationflags"] = 0x00000008 | 0x08000000
+ else:
+ kwargs["start_new_session"] = True
+ subprocess.Popen([sys.executable, "-m", _FLUSHER_MODULE], **kwargs) # type: ignore[arg-type]
+ return True
+
+
+def _flush() -> None:
+ """Hand queued events to a detached flusher on the way out. Never raises."""
+ with contextlib.suppress(Exception):
+ if _under_test() or not spool.has_events():
+ return
+ if not settings.is_enabled() or settings.debug_mode():
+ # Turning telemetry off must also unsend what is already queued,
+ # or a disable would be followed by one last batch.
+ spool.claim()
+ return
+ _spawn_flusher()
diff --git a/packages/cli/src/repowise/cli/platform/telemetry/flusher.py b/packages/cli/src/repowise/cli/platform/telemetry/flusher.py
new file mode 100644
index 000000000..1d7e8b8c5
--- /dev/null
+++ b/packages/cli/src/repowise/cli/platform/telemetry/flusher.py
@@ -0,0 +1,34 @@
+"""Deliver spooled telemetry events, in a process nobody is waiting on.
+
+Run as ``python -m repowise.cli.platform.telemetry.flusher``. The CLI spawns
+this detached at exit and dies immediately; delivery then takes as long as the
+network takes, instead of being raced by the command's own exit.
+
+Deliberately narrow: it imports the spool and the platform client and nothing
+else. In particular it must never import :mod:`.emitter`, whose ``atexit`` hook
+would have this process spawn another one.
+"""
+
+from __future__ import annotations
+
+import contextlib
+
+#: Backend ingestion path (joined to the platform base URL by the client).
+INGEST_PATH = "telemetry/events"
+
+
+def deliver() -> int:
+ """POST every queued envelope. Returns how many were sent. Never raises."""
+ sent = 0
+ with contextlib.suppress(Exception):
+ from repowise.cli.platform.client import default_client
+ from repowise.cli.platform.telemetry import spool
+
+ for envelope in spool.claim():
+ if default_client.post(INGEST_PATH, envelope):
+ sent += 1
+ return sent
+
+
+if __name__ == "__main__":
+ deliver()
diff --git a/packages/cli/src/repowise/cli/platform/telemetry/spool.py b/packages/cli/src/repowise/cli/platform/telemetry/spool.py
new file mode 100644
index 000000000..94491a1b0
--- /dev/null
+++ b/packages/cli/src/repowise/cli/platform/telemetry/spool.py
@@ -0,0 +1,94 @@
+"""On-disk queue for telemetry envelopes (``~/.repowise/telemetry-spool.jsonl``).
+
+A CLI process records its one ``command_run`` event in the last moments before
+exit, so there is no time left to deliver it without making the user wait. The
+spool decouples the two: recording is a file append, and delivery is the job of
+the detached flusher the process spawns on its way out.
+
+One JSON envelope per line. A flusher claims the whole file with a single
+atomic rename, so several of them running at once (the agent's shell calls are
+routinely concurrent) can never send the same event twice.
+
+A claim is destructive: a batch whose POST fails is dropped, not retried, which
+matches what the previous fire-and-forget send did with anything the backend
+did not accept. Turning this into a real outbox (requeue with a per-event retry
+count) is the upgrade path if offline delivery ever matters; it is not free,
+because a POST that times out after the server accepted it would then arrive
+twice.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+from pathlib import Path
+
+SPOOL_FILENAME = "telemetry-spool.jsonl"
+
+#: Discard the spool outright past this size. Only reachable if delivery has
+#: failed for a very long time (offline machine), where old events are worthless.
+_MAX_BYTES = 1 << 20
+
+#: Most events delivered from one claim; a backlog past this is dropped oldest-first.
+_MAX_BATCH = 100
+
+
+def _path() -> Path:
+ from repowise.cli.helpers import user_global_dir
+
+ return user_global_dir() / SPOOL_FILENAME
+
+
+def append(envelope: dict[str, object]) -> None:
+ """Queue *envelope* for later delivery. Best-effort, never raises."""
+ with contextlib.suppress(Exception):
+ path = _path()
+ with contextlib.suppress(OSError):
+ if path.stat().st_size > _MAX_BYTES:
+ path.unlink()
+ line = json.dumps(envelope, separators=(",", ":"))
+ with path.open("a", encoding="utf-8") as handle:
+ handle.write(line + "\n")
+
+
+def has_events() -> bool:
+ """Return whether anything is queued, without reading the file."""
+ try:
+ return _path().stat().st_size > 0
+ except OSError:
+ return False
+
+
+def claim() -> list[dict[str, object]]:
+ """Take exclusive ownership of everything queued and return it.
+
+ The rename is the mutual exclusion: whichever process renames the spool
+ first owns those events, and every other process sees an empty queue.
+ Events queued after the rename land in a fresh spool file for the next
+ claim, so nothing is stranded.
+ """
+ path = _path()
+ claimed = path.with_name(f"{path.name}.{os.getpid()}.claim")
+ try:
+ os.replace(path, claimed)
+ except OSError:
+ # Nothing queued, or another process claimed it first.
+ return []
+
+ text = ""
+ with contextlib.suppress(OSError):
+ text = claimed.read_text(encoding="utf-8")
+ with contextlib.suppress(OSError):
+ claimed.unlink()
+
+ events: list[dict[str, object]] = []
+ for line in text.splitlines():
+ line = line.strip()
+ if not line:
+ continue
+ with contextlib.suppress(Exception):
+ envelope = json.loads(line)
+ if isinstance(envelope, dict):
+ events.append(envelope)
+ return events[-_MAX_BATCH:]
diff --git a/tests/conftest.py b/tests/conftest.py
index 0359cf134..9d87e9299 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -8,8 +8,8 @@ import pytest
@pytest.fixture(scope="session", autouse=True)
-def _no_telemetry_network():
- """Guarantee no test emits core-layer telemetry over the network.
+def _no_telemetry_network(tmp_path_factory: pytest.TempPathFactory):
+ """Guarantee no test emits telemetry over the network or into real state.
The MCP instrument seam emits an ``mcp_tool_call`` event via the core
emitter's ``_post``; a test that drives the real wrapper with consent
@@ -17,9 +17,13 @@ def _no_telemetry_network():
sink to a no-op. Tests that assert emit behaviour re-patch it at function
scope and still never touch the network.
- The CLI's ``command_run`` path is intentionally left alone: its tests patch
- ``PlatformClient.post`` at the class level, so patching the ``default_client``
- instance here would shadow those patches.
+ The CLI's ``command_run`` path is not patched here — its tests patch
+ ``PlatformClient.post`` at the class level, so patching the
+ ``default_client`` instance would shadow those patches. Its delivery is
+ already off under pytest (``emitter._under_test``); what this fixture adds
+ is redirecting the event spool, so a test that records an event cannot
+ leave it queued in the real ``~/.repowise`` for a later real invocation to
+ deliver.
"""
from _pytest.monkeypatch import MonkeyPatch
@@ -30,6 +34,13 @@ def _no_telemetry_network():
mp.setattr(_core_telemetry, "_post", lambda envelope: None, raising=False)
except Exception:
pass
+ try:
+ from repowise.cli.platform.telemetry import spool as _cli_spool
+
+ spool_path = tmp_path_factory.mktemp("telemetry") / _cli_spool.SPOOL_FILENAME
+ mp.setattr(_cli_spool, "_path", lambda: spool_path)
+ except Exception:
+ pass
yield
mp.undo()
diff --git a/tests/unit/cli/test_telemetry.py b/tests/unit/cli/test_telemetry.py
index 6600b5090..3912bd565 100644
--- a/tests/unit/cli/test_telemetry.py
+++ b/tests/unit/cli/test_telemetry.py
@@ -14,21 +14,23 @@ import pytest
from click.testing import CliRunner
from repowise.cli.platform import identity, settings, store
-from repowise.cli.platform.telemetry import emitter
+from repowise.cli.platform.telemetry import emitter, spool
from repowise.cli.platform.telemetry.events import CommandRunEvent
@pytest.fixture(autouse=True)
def isolated_store(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
- """Point platform.json at a temp dir so tests never touch real ~/.repowise."""
+ """Point platform.json and the event spool at a temp dir.
+
+ Tests must never touch the real ``~/.repowise``, and a leftover spool file
+ would otherwise carry a test's fake events into the next test.
+ """
monkeypatch.setattr(store, "_path", lambda: tmp_path / "platform.json")
+ monkeypatch.setattr(spool, "_path", lambda: tmp_path / spool.SPOOL_FILENAME)
# Clear any inherited telemetry env so each test controls precedence.
for var in ("DO_NOT_TRACK", "REPOWISE_TELEMETRY_DISABLED", "REPOWISE_TELEMETRY_DEBUG"):
monkeypatch.delenv(var, raising=False)
- # Isolate the module-global pending-send list between tests.
- emitter._pending.clear()
- yield
- emitter._pending.clear()
+ monkeypatch.setattr(emitter, "_flush_thread", None, raising=False)
class TestConsentPrecedence:
@@ -140,64 +142,118 @@ class TestFlagNormalization:
class TestEmitterRespectsConsent:
- def test_disabled_sends_nothing(self, monkeypatch: pytest.MonkeyPatch):
- sent: list = []
- monkeypatch.setattr(emitter.default_client, "post", lambda *a, **k: sent.append(a) or True)
+ def test_disabled_queues_nothing(self, monkeypatch: pytest.MonkeyPatch):
monkeypatch.setenv("DO_NOT_TRACK", "1")
emitter.record(CommandRunEvent(command="health"))
- emitter._flush()
- assert sent == []
+ assert spool.claim() == []
- def test_debug_prints_does_not_send(
+ def test_debug_prints_does_not_queue(
self, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture
):
- sent: list = []
- monkeypatch.setattr(emitter.default_client, "post", lambda *a, **k: sent.append(a) or True)
monkeypatch.setenv("REPOWISE_TELEMETRY_DEBUG", "1")
emitter.record(CommandRunEvent(command="health"))
captured = capsys.readouterr()
assert "would send" in captured.err
- assert sent == []
+ assert spool.claim() == []
-class TestCommandWrapper:
- def test_status_command_records_one_event(self, monkeypatch: pytest.MonkeyPatch):
- from repowise.cli.main import cli
+class TestSpooledDelivery:
+ """Recording queues and exit hands the queue to a detached flusher.
+
+ The command itself must never wait on the network — that is the whole point
+ of the spool, and it is what the previous ``atexit`` join gave away.
+ """
+
+ def test_record_only_queues(self, monkeypatch: pytest.MonkeyPatch):
+ spawned: list = []
+ monkeypatch.setattr(emitter, "_spawn_flusher", lambda: spawned.append(True) or True)
+
+ emitter.record(CommandRunEvent(command="health"))
+
+ assert spawned == [] # nothing happens until exit
+ assert len(spool.claim()) == 1
+
+ def test_exit_spawns_the_flusher_once_events_are_queued(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ spawned: list = []
+ monkeypatch.setattr(emitter, "_spawn_flusher", lambda: spawned.append(True) or True)
+ monkeypatch.setattr(emitter, "_under_test", lambda: False)
- recorded: list[dict] = []
+ emitter._flush()
+ assert spawned == [] # empty spool, no process to start
+
+ emitter.record(CommandRunEvent(command="health"))
+ emitter._flush()
+ assert spawned == [True]
- def fake_post(path, payload, **kwargs):
- recorded.append(payload)
- return True
+ def test_exit_spawns_nothing_under_pytest(self, monkeypatch: pytest.MonkeyPatch):
+ spawned: list = []
+ monkeypatch.setattr(emitter, "_spawn_flusher", lambda: spawned.append(True) or True)
- monkeypatch.setattr(emitter.default_client, "post", fake_post)
- # Force synchronous delivery so we can assert without races.
+ emitter.record(CommandRunEvent(command="health"))
+ emitter._flush()
+
+ assert spawned == []
+
+ def test_flusher_posts_and_drains(self, monkeypatch: pytest.MonkeyPatch):
+ from repowise.cli.platform import client
+ from repowise.cli.platform.telemetry import flusher
+
+ sent: list[dict] = []
monkeypatch.setattr(
- emitter.threading,
- "Thread",
- lambda target, args, daemon: type(
- "T", (), {"start": lambda s: target(*args), "join": lambda s, timeout=None: None}
- )(),
+ client.default_client, "post", lambda path, payload, **k: sent.append(payload) or True
)
+ emitter.record(CommandRunEvent(command="health"))
+ emitter.record(CommandRunEvent(command="status"))
+ assert flusher.deliver() == 2
+
+ assert [e["properties"]["command"] for e in sent] == ["health", "status"]
+ # Delivered events are not re-sent by the next flusher.
+ assert spool.claim() == []
+
+ def test_disabling_drops_what_is_already_queued(self, monkeypatch: pytest.MonkeyPatch):
+ spawned: list = []
+ monkeypatch.setattr(emitter, "_spawn_flusher", lambda: spawned.append(True) or True)
+ monkeypatch.setattr(emitter, "_under_test", lambda: False)
+
+ emitter.record(CommandRunEvent(command="health"))
+ monkeypatch.setenv("DO_NOT_TRACK", "1")
+ emitter._flush()
+
+ assert spawned == []
+ assert spool.claim() == []
+
+ def test_claim_is_exclusive(self):
+ """Two concurrent flushers cannot send the same event twice."""
+ emitter.record(CommandRunEvent(command="health"))
+ first = spool.claim()
+ second = spool.claim()
+ assert len(first) == 1
+ assert second == []
+
+
+class TestCommandWrapper:
+ def test_status_command_records_one_event(self):
+ from repowise.cli.main import cli
+
res = CliRunner().invoke(cli, ["telemetry", "status"])
assert res.exit_code == 0
- assert len(recorded) == 1
- assert recorded[0]["event"] == "command_run"
- assert recorded[0]["properties"]["command"] == "telemetry"
- assert recorded[0]["properties"]["subcommand"] == "status"
- assert recorded[0]["properties"]["status"] == "ok"
- def test_help_records_nothing(self, monkeypatch: pytest.MonkeyPatch):
+ queued = spool.claim()
+ assert len(queued) == 1
+ assert queued[0]["event"] == "command_run"
+ assert queued[0]["properties"]["command"] == "telemetry"
+ assert queued[0]["properties"]["subcommand"] == "status"
+ assert queued[0]["properties"]["status"] == "ok"
+
+ def test_help_records_nothing(self):
from repowise.cli.main import cli
- recorded: list = []
- monkeypatch.setattr(
- emitter.default_client, "post", lambda *a, **k: recorded.append(a) or True
- )
res = CliRunner().invoke(cli, ["--help"])
assert res.exit_code == 0
- assert recorded == []
+ assert spool.claim() == []
class TestOutcomeClassification:
@@ -208,19 +264,6 @@ class TestOutcomeClassification:
from repowise.cli._instrumented_group import InstrumentedGroup
- recorded: list[dict] = []
- monkeypatch.setattr(
- emitter.default_client, "post", lambda path, payload, **k: recorded.append(payload) or True
- )
- # Force synchronous delivery so the assert doesn't race the daemon send.
- monkeypatch.setattr(
- emitter.threading,
- "Thread",
- lambda target, args, daemon: type(
- "T", (), {"start": lambda s: target(*args), "join": lambda s, timeout=None: None}
- )(),
- )
-
@click.group(cls=InstrumentedGroup)
def root() -> None: ...
@@ -229,7 +272,7 @@ class TestOutcomeClassification:
body()
CliRunner().invoke(root, ["sub"])
- return recorded
+ return spool.claim()
def test_abort_is_interrupted(self, monkeypatch: pytest.MonkeyPatch):
import click