diff --git a/gatelock/README.md b/gatelock/README.md index abf7fb5..9a15701 100644 --- a/gatelock/README.md +++ b/gatelock/README.md @@ -125,6 +125,24 @@ lower ranks keep queueing), waits windowless, and re-arms fully once nothing outranks it. `scripts/verify_all_lockers.py` checks this with five real processes on a private Xvfb. +## Error and slow-wait reporting + +`gatelock.error_report` is the Python reporter of the shared app-errors pipeline +(utils `DOCS-app-errors.md`). Call it once at start-up, then watch the Tk loop: + +```python +from gatelock import error_report + +rep = error_report.install("leetcode-guard", "kuhyx/leetcode-guard") +error_report.watch_stalls(root, rep) # a frozen loop over 1 s -> perf.slow +with rep.wait("coach.load"): # or rep.begin(...).end() across callbacks + ... +``` + +Uncaught, thread and Tk callback errors and waits over 1 s go to +`~/.local/state/app-errors-spool/.jsonl`. The `app-errors` ingest timer +turns them into board tickets. Nothing shows on screen. + ## Development ```bash diff --git a/gatelock/gatelock/error_report.py b/gatelock/gatelock/error_report.py new file mode 100644 index 0000000..5601299 --- /dev/null +++ b/gatelock/gatelock/error_report.py @@ -0,0 +1,312 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Report every error and every wait over 1 s of a Tk (or any Python) app. + +The Python reporter of kuhy's shared app-errors pipeline (utils +``DOCS-app-errors.md``; the Dart one is crdt_sync_flutter's, generalised from +kartka). ``install`` once at start-up hooks ``sys.excepthook``, +``threading.excepthook`` and Tk callback errors (``Misc._report_exception``, +which every root, ``GateRoot`` included, goes through), each chained to the +hook it replaces. ``Reporter.begin``/``wait`` time a user-visible wait, and +``watch_stalls`` reports a frozen Tk loop with no call-site work. + +A report is one JSON line in ``$XDG_STATE_HOME/app-errors-spool/.jsonl``. +The PC's ``app-errors`` ingest (utils ``app_errors/``) reads it, groups it by +signature and hands it to the board, which files a ticket. Reporting shows +nothing on screen, never raises and never reports from inside a report. +Identical errors within ``WINDOW`` seconds are dropped and at most +``MAX_PER_MINUTE`` are written per minute (an error loop cannot fill the disk). +""" + +from __future__ import annotations + +from contextlib import contextmanager +from dataclasses import dataclass, field +import datetime as dt +import json +import os +from pathlib import Path +import sys +import threading +import time +import tkinter as tk +import traceback +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from collections.abc import Callable, Iterator + from types import TracebackType + +#: The kind the board files as "bring this wait under 1 s". +SLOW_KIND = "perf.slow" +#: How often the stall watch ticks, milliseconds. +STALL_TICK_MS = 100 + +_TK_DOOR = "_report_exception" + +_installed: Reporter | None = None + + +def _default_spool() -> Path: + base = os.environ.get("XDG_STATE_HOME") or str(Path.home() / ".local" / "state") + return Path(base) / "app-errors-spool" + + +def _short(path: str, mark: str) -> str: + """Return ``path`` from the package that holds it: no home directory in a report.""" + for anchor in ("site-packages/", "dist-packages/"): + if anchor in path: + return path.rsplit(anchor, 1)[1] + if mark in path: + return mark + path.rsplit(mark, 1)[1] + return Path(path).name + + +@dataclass +class Reporter: + """Writes one app's error and slow-wait reports to the spool.""" + + #: Seconds an identical error stays suppressed. + WINDOW = 30.0 + #: Most error reports written per minute. + MAX_PER_MINUTE = 20 + #: Most slow-wait reports written per minute. + MAX_SLOW_PER_MINUTE = 30 + + app: str + repo: str + mark: str = "" + spool: Path = field(default_factory=_default_spool) + build: int = 0 + version: str | None = None + threshold: float = 1.0 + still_after: float = 5.0 + clock: Callable[[], float] = time.time + _seen: dict[str, float] = field(default_factory=dict) + _minutes: dict[str, tuple[float, int]] = field(default_factory=dict) + _busy: bool = False + _serial: int = 0 + _lock: threading.Lock = field(default_factory=threading.Lock) + + def __post_init__(self) -> None: + """Default the frame mark to the app's module directory.""" + self.mark = self.mark or self.app.replace("-", "_") + "/" + + def _allowed(self, bucket: str, cap: int) -> bool: + now = self.clock() + start, count = self._minutes.get(bucket, (now, 0)) + if now - start >= 60: # noqa: PLR2004 -- one minute + start, count = now, 0 + if count >= cap: + return False + self._minutes[bucket] = (start, count + 1) + return True + + def _write(self, entry: dict[str, object]) -> None: + at = dt.datetime.fromtimestamp(self.clock(), dt.UTC) + entry |= { + "at": at.strftime("%Y-%m-%dT%H:%M:%S.") + f"{at.microsecond // 1000:03d}Z", + "repo": self.repo, + "mark": self.mark, + "build": self.build, + } + if self.version: + entry["version"] = self.version + line = json.dumps(entry, sort_keys=True) + "\n" + with self._lock: + self.spool.mkdir(parents=True, exist_ok=True) + with (self.spool / f"{self.app}.jsonl").open("a", encoding="utf-8") as f: + f.write(line) + + def report(self, kind: str, error: object, tb: TracebackType | None = None) -> None: + """Record ``error`` (exception or message) as ``kind``, unless suppressed.""" + if self._busy: + return + self._busy = True + try: + text = ( + f"{type(error).__name__}: {error}" + if isinstance(error, BaseException) + else str(error) + ) + now = self.clock() + key = f"{kind}|{text}" + self._seen = {k: t for k, t in self._seen.items() if now - t < self.WINDOW} + if key in self._seen or not self._allowed("error", self.MAX_PER_MINUTE): + return + self._seen[key] = now + frames = traceback.extract_tb(tb) if tb is not None else [] + stack = [ + f"{_short(f.filename, self.mark)}:{f.lineno} in {f.name}" + for f in reversed(frames) + ] + self._write({"kind": kind, "error": text, "stack": stack}) + except Exception: # noqa: BLE001, S110 -- never raise into the app it watches + pass + finally: + self._busy = False + + def slow( + self, + operation: str, + ms: int, + *, + wait_id: str, + route: str | None = None, + still: bool = False, + ) -> None: + """Record one wait of ``ms`` milliseconds on ``operation``.""" + try: + if not self._allowed("slow", self.MAX_SLOW_PER_MINUTE): + return + entry: dict[str, object] = { + "kind": SLOW_KIND, + "error": f"{operation} waited {ms} ms", + "operation": operation, + "durationMs": ms, + "waitId": wait_id, + "still": still, + } + if route: + entry["route"] = route + self._write(entry) + except Exception: # noqa: BLE001, S110 -- never raise into the app + pass + + def begin(self, operation: str, *, route: str | None = None) -> SlowWait: + """Start timing a wait on ``operation`` (``coach.load``); ``end`` it after.""" + self._serial += 1 + return SlowWait( + self, + operation, + route, + self.clock(), + f"{int(self.clock() * 1000):x}-{self._serial}", + ) + + @contextmanager + def wait(self, operation: str, *, route: str | None = None) -> Iterator[SlowWait]: + """Time the ``with`` block as a wait on ``operation``.""" + handle = self.begin(operation, route=route) + try: + yield handle + finally: + handle.end() + + +@dataclass +class SlowWait: + """One timed wait: reported when it ends after the threshold, or is still going.""" + + reporter: Reporter + operation: str + route: str | None + started: float + id: str + _ended: bool = False + _reported_still: bool = False + _timer: threading.Timer = field(init=False) + + def __post_init__(self) -> None: + """Arm the still-waiting report (a hung load never ends).""" + self._timer = threading.Timer(self.reporter.still_after, self._still) + self._timer.daemon = True + self._timer.start() + + def _ms(self) -> int: + return round((self.reporter.clock() - self.started) * 1000) + + def _still(self) -> None: + if self._ended: + return + self._reported_still = True + self.reporter.slow( + self.operation, self._ms(), wait_id=self.id, route=self.route, still=True + ) + + def end(self) -> None: + """End the wait; write it if it outlasted the threshold; repeats do nothing.""" + if self._ended: + return + self._ended = True + self._timer.cancel() + ms = self._ms() + if self._reported_still or ms > self.reporter.threshold * 1000: + self.reporter.slow(self.operation, ms, wait_id=self.id, route=self.route) + + +def watch_stalls(root: tk.Misc, reporter: Reporter) -> None: + """Report each time ``root``'s event loop froze past the threshold. + + The operation is ``tk.mainloop``: a blocking call on the Tk thread. + """ + last = [reporter.clock()] + + def tick() -> None: + now = reporter.clock() + late = round((now - last[0]) * 1000) - STALL_TICK_MS + last[0] = now + if late > reporter.threshold * 1000: + reporter.slow("tk.mainloop", late, wait_id=f"stall-{int(now * 1000):x}") + try: + root.after(STALL_TICK_MS, tick) + except tk.TclError: + return # the window is gone + + root.after(STALL_TICK_MS, tick) + + +def install( + app: str, + repo: str, + *, + mark: str = "", + build: int = 0, + version: str | None = None, +) -> Reporter: + """Hook uncaught, thread and Tk callback errors once; return the reporter. + + The spool is ``$XDG_STATE_HOME/app-errors-spool``; tests build a + ``Reporter`` with their own ``spool`` instead. + """ + global _installed # noqa: PLW0603 -- one set of process-wide hooks + if _installed is not None: + return _installed + rep = Reporter( + app=app, + repo=repo, + mark=mark, + build=build, + version=version, + ) + prior_sys = sys.excepthook + + def sys_hook( + kind: type[BaseException], value: BaseException, tb: TracebackType | None + ) -> None: + rep.report("uncaught.python", value, tb) + prior_sys(kind, value, tb) + + prior_thread = threading.excepthook + + def thread_hook(args: threading.ExceptHookArgs) -> None: + value: object = args.exc_value + if value is None: + value = args.exc_type.__name__ + rep.report("uncaught.thread", value, args.exc_traceback) + prior_thread(args) + + # Misc._report_exception is the one door every Tk callback error passes, + # whatever root subclass overrides report_callback_exception. + prior_tk: Callable[[tk.Misc], None] = getattr(tk.Misc, _TK_DOOR) + + def tk_hook(widget: tk.Misc) -> None: + _, value, tb = sys.exc_info() + if value is not None: + rep.report("uncaught.tk", value, tb) + prior_tk(widget) + + sys.excepthook = sys_hook + threading.excepthook = thread_hook + setattr(tk.Misc, _TK_DOOR, tk_hook) + _installed = rep + return rep diff --git a/gatelock/gatelock/tests/test_error_report.py b/gatelock/gatelock/tests/test_error_report.py new file mode 100644 index 0000000..8e043ef --- /dev/null +++ b/gatelock/gatelock/tests/test_error_report.py @@ -0,0 +1,290 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""The Tk app error and slow-wait reporter: hooks, dedup, spool lines, stalls.""" + +from __future__ import annotations + +import json +import sys +import threading +import tkinter as tk +from typing import TYPE_CHECKING +from unittest.mock import MagicMock + +import pytest + +from gatelock import error_report +from gatelock.error_report import Reporter + +DOOR = "_report_exception" + +if TYPE_CHECKING: + from collections.abc import Iterator + from pathlib import Path + + +class Clock: + """A settable wall + monotonic clock.""" + + def __init__(self) -> None: + self.t = 1_800_000_000.0 + + def __call__(self) -> float: + return self.t + + +@pytest.fixture +def clock() -> Clock: + return Clock() + + +@pytest.fixture +def reporter(tmp_path: Path, clock: Clock) -> Reporter: + return Reporter( + app="leetcode-guard", + repo="kuhyx/leetcode-guard", + spool=tmp_path, + build=5, + version="0.3.0", + clock=clock, + ) + + +def _lines(tmp_path: Path, app: str = "leetcode-guard") -> list[dict[str, object]]: + path = tmp_path / f"{app}.jsonl" + if not path.exists(): + return [] + return [json.loads(line) for line in path.read_text().splitlines()] + + +def _raise() -> BaseException: + try: + raise ValueError("bad 12") # noqa: EM101, TRY003, TRY301 -- a real traceback for the test + except ValueError as e: + return e + + +def test_report_writes_one_entry(reporter: Reporter, tmp_path: Path) -> None: + exc = _raise() + reporter.report("uncaught.python", exc, exc.__traceback__) + (entry,) = _lines(tmp_path) + assert entry["kind"] == "uncaught.python" + assert entry["error"] == "ValueError: bad 12" + assert entry["repo"] == "kuhyx/leetcode-guard" + assert entry["mark"] == "leetcode_guard/" + assert entry["build"] == 5 + assert entry["version"] == "0.3.0" + assert entry["at"] == "2027-01-15T08:00:00.000Z" + stack = entry["stack"] + assert isinstance(stack, list) + assert "test_error_report.py" in stack[0] + assert " in _raise" in stack[0] + + +def test_identical_errors_within_window_are_dropped( + reporter: Reporter, tmp_path: Path, clock: Clock +) -> None: + for _ in range(5): + reporter.report("k", "same") + assert len(_lines(tmp_path)) == 1 + clock.t += Reporter.WINDOW + 1 + reporter.report("k", "same") + assert len(_lines(tmp_path)) == 2 + + +def test_rate_cap_per_minute(reporter: Reporter, tmp_path: Path, clock: Clock) -> None: + for i in range(Reporter.MAX_PER_MINUTE + 5): + reporter.report("k", f"e{i}") + assert len(_lines(tmp_path)) == Reporter.MAX_PER_MINUTE + clock.t += 61 + reporter.report("k", "later") + assert len(_lines(tmp_path)) == Reporter.MAX_PER_MINUTE + 1 + + +def test_report_never_raises(reporter: Reporter, tmp_path: Path) -> None: + class Bad: + def __str__(self) -> str: + raise RuntimeError + + reporter.report("k", Bad()) + (tmp_path / "leetcode-guard.jsonl").mkdir() # an unwritable spool file + reporter.report("k", "other") + assert True + + +def test_report_inside_report_is_ignored(reporter: Reporter, tmp_path: Path) -> None: + reporter._busy = True + reporter.report("k", "x") + assert _lines(tmp_path) == [] + + +def test_slow_wait_over_threshold_is_written( + reporter: Reporter, tmp_path: Path, clock: Clock +) -> None: + wait = reporter.begin("coach.load", route="coach") + clock.t += 2.0 + wait.end() + wait.end() # repeat ends do nothing + (entry,) = _lines(tmp_path) + assert entry["kind"] == "perf.slow" + assert entry["operation"] == "coach.load" + assert entry["durationMs"] == 2000 + assert entry["route"] == "coach" + assert entry["still"] is False + assert entry["error"] == "coach.load waited 2000 ms" + + +def test_fast_wait_writes_nothing( + reporter: Reporter, tmp_path: Path, clock: Clock +) -> None: + with reporter.wait("quick"): + clock.t += 0.5 + assert _lines(tmp_path) == [] + + +def test_still_waiting_is_written_then_the_end( + reporter: Reporter, tmp_path: Path, clock: Clock +) -> None: + wait = reporter.begin("hung") + clock.t += 6 + wait._still() + clock.t += 1 + wait.end() + still, end = _lines(tmp_path) + assert still["still"] is True + assert end["still"] is False + assert still["waitId"] == end["waitId"] + + +def test_slow_rate_cap(reporter: Reporter, tmp_path: Path, clock: Clock) -> None: + for _ in range(Reporter.MAX_SLOW_PER_MINUTE + 3): + w = reporter.begin("op") + clock.t += 1.5 + w.end() + assert len(_lines(tmp_path)) == Reporter.MAX_SLOW_PER_MINUTE + + +@pytest.fixture +def hooks() -> Iterator[None]: + saved = (sys.excepthook, threading.excepthook, getattr(tk.Misc, DOOR)) + yield + sys.excepthook, threading.excepthook = saved[:2] + setattr(tk.Misc, DOOR, saved[2]) + error_report._installed = None + + +def _install(spool: Path) -> Reporter: + rep = error_report.install("tk-app", "kuhyx/tk-app") + rep.spool = spool + return rep + + +def test_install_chains_sys_and_thread_hooks(hooks: None, tmp_path: Path) -> None: + prior = MagicMock() + sys.excepthook = prior + prior_thread = MagicMock() + threading.excepthook = prior_thread + rep = _install(tmp_path) + assert _install(tmp_path) is rep # idempotent + exc = _raise() + sys.excepthook(ValueError, exc, exc.__traceback__) + prior.assert_called_once() + args = MagicMock( + exc_type=RuntimeError, exc_value=RuntimeError("thread boom"), exc_traceback=None + ) + threading.excepthook(args) + prior_thread.assert_called_once_with(args) + kinds = [e["kind"] for e in _lines(tmp_path, "tk-app")] + assert kinds == ["uncaught.python", "uncaught.thread"] + + +def test_thread_hook_without_value(hooks: None, tmp_path: Path) -> None: + threading.excepthook = MagicMock() + _install(tmp_path) + threading.excepthook( + MagicMock(exc_type=SystemExit, exc_value=None, exc_traceback=None) + ) + assert _lines(tmp_path, "tk-app")[0]["error"] == "SystemExit" + + +def test_install_reports_tk_callback_errors(hooks: None, tmp_path: Path) -> None: + prior = MagicMock() + setattr(tk.Misc, DOOR, prior) + _install(tmp_path) + widget = MagicMock() + try: + raise KeyError("cb") # noqa: EM101, TRY301 + except KeyError: + getattr(tk.Misc, DOOR)(widget) + prior.assert_called_once_with(widget) + (entry,) = _lines(tmp_path, "tk-app") + assert entry["kind"] == "uncaught.tk" + assert entry["error"] == "KeyError: 'cb'" + + +def test_tk_hook_without_active_exception(hooks: None, tmp_path: Path) -> None: + setattr(tk.Misc, DOOR, MagicMock()) + _install(tmp_path) + getattr(tk.Misc, DOOR)(MagicMock()) + assert _lines(tmp_path, "tk-app") == [] + + +def test_default_spool_and_mark( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path)) + rep = Reporter(app="diet-guard", repo="kuhyx/diet-guard") + assert rep.spool == tmp_path / "app-errors-spool" + assert rep.mark == "diet_guard/" + monkeypatch.delenv("XDG_STATE_HOME") + assert Reporter(app="a", repo="kuhyx/a").spool.name == "app-errors-spool" + + +def test_stall_watch_reports_a_frozen_loop( + reporter: Reporter, tmp_path: Path, clock: Clock +) -> None: + root = MagicMock() + error_report.watch_stalls(root, reporter) + tick = root.after.call_args.args[1] + clock.t += 0.1 + tick() # on time: nothing + clock.t += 2.5 # the loop was blocked 2.5 s + tick() + (entry,) = _lines(tmp_path) + assert entry["operation"] == "tk.mainloop" + assert entry["durationMs"] == 2500 - error_report.STALL_TICK_MS + + +def test_stall_watch_stops_with_the_window(reporter: Reporter, clock: Clock) -> None: + root = MagicMock() + error_report.watch_stalls(root, reporter) + tick = root.after.call_args.args[1] + root.after.side_effect = tk.TclError("destroyed") + tick() # must not raise + assert root.after.call_count == 2 + + +def test_frame_paths(reporter: Reporter) -> None: + assert ( + error_report._short("/x/lib/python3.15/site-packages/gatelock/a.py", "m/") + == "gatelock/a.py" + ) + assert error_report._short( + "/home/u/src/leetcode-guard/leetcode_guard/ui.py", "leetcode_guard/" + ) == ("leetcode_guard/ui.py") + assert error_report._short("/somewhere/else.py", "m/") == "else.py" + + +def test_slow_never_raises(reporter: Reporter, tmp_path: Path) -> None: + (tmp_path / "leetcode-guard.jsonl").mkdir() + reporter.slow("op", 2000, wait_id="w") + assert True + + +def test_still_after_end_does_nothing( + reporter: Reporter, tmp_path: Path, clock: Clock +) -> None: + wait = reporter.begin("op") + wait.end() + clock.t += 9 + wait._still() + assert _lines(tmp_path) == [] diff --git a/gatelock/pyproject.toml b/gatelock/pyproject.toml index 684ba3e..ab96d42 100644 --- a/gatelock/pyproject.toml +++ b/gatelock/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "gatelock" -version = "0.14.0" +version = "0.15.0" description = "Shared per-output lock-window + HMAC log-integrity backend for blocking-overlay apps" requires-python = ">=3.14" dependencies = [] # pure stdlib — tkinter is bundled with Python