gatelock 0.15.0: error and slow-wait reporter

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Krzysztof Rudnicki 2026-11-17 21:37:27 +01:00
parent 62e7ff801e
commit 1ea7dfd6d5
4 changed files with 621 additions and 1 deletions

View File

@ -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/<app>.jsonl`. The `app-errors` ingest timer
turns them into board tickets. Nothing shows on screen.
## Development
```bash

View File

@ -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/<app>.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

View File

@ -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) == []

View File

@ -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