Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.mdindex 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. Itonly lets us count distinct installs. Delete the file and a new, unrelated idis 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 yourselfRun any command with `REPOWISE_TELEMETRY_DEBUG=1` to print the exact payload todiff --git a/packages/cli/src/repowise/cli/platform/telemetry/emitter.py b/packages/cli/src/repowise/cli/platform/telemetry/emitter.pyindex 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 annotationsimport atexitimport contextlibimport json+import os+import subprocessimport sys-import threadingfrom 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, spoolfrom 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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 coreemitter'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 functionscope 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:+ passyieldmp.undo()diff --git a/tests/unit/cli/test_telemetry.py b/tests/unit/cli/test_telemetry.pyindex 6600b5090..3912bd565 100644--- a/tests/unit/cli/test_telemetry.py+++ b/tests/unit/cli/test_telemetry.py@@ -14,21 +14,23 @@ import pytestfrom click.testing import CliRunnerfrom repowise.cli.platform import identity, settings, store-from repowise.cli.platform.telemetry import emitter+from repowise.cli.platform.telemetry import emitter, spoolfrom 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