utils/app_errors/README.md
Krzysztof kuhy Rudnicki 62e7ff801e app_errors 0.1.0: shared error ingest + timer
RTDB and local spool reports merged by signature into the board's
app-error contract; resolve command; systemd --user timer via deploy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:51:18 +01:00

53 lines
2.1 KiB
Markdown

# app_errors
The PC side of kuhy's app error and slow-wait reporting. Every app reports
errors, and every wait the user sees over 1 s (`perf.slow`). This ingest merges
the reports by signature and writes `~/.local/state/app-errors/<app>.json` in
the todoImplementer `contracts/app-error.schema.json` `report` shape. The board
reads that folder and turns each open error into a self-fixing ticket
(todoImplementer `DOCS-errors.md`).
Generalised from kartka's `tools/errors`. Dart signatures are byte-identical to
kartka's. See `DOCS-app-errors.md` at the repo root for the whole pipeline.
## Where reports come from
| Reporter | Runs on | Writes |
|---|---|---|
| `crdt_sync_flutter` `installErrorReporting` | phone, desktop, web | RTDB `/<app>/errors/<device>/<id>` |
| `gatelock.error_report.install` | PC (Tk) | spool `~/.local/state/app-errors-spool/<app>.jsonl` |
| Godot `addons/app_errors` (`godot_dev_tools/`) | PC | the same spool |
The ingest skips `kartka` in RTDB, because kartka still runs its own ingest.
## Entry (one report, every language)
`at` (ISO UTC), `kind` (`uncaught.flutter`, `uncaught.python`, `uncaught.gdscript`,
`ui.snackbar`, `perf.slow`, ...), `error`, `stack` (list of frames), plus these
optional fields:
- `repo` (`owner/name`, default `kuhyx/<app>`)
- `mark` (the substring that marks the app's own frames: `package:todo/`,
`leetcode_guard/`, `res://`)
- `route`
- `operation`, `durationMs`, `waitId` and `still` (slow waits)
- `build` (versionCode, 0 when unknown) and `version`
## Commands
```bash
app-errors ingest # what the timer runs every 5 min
app-errors ingest --keep # leave RTDB entries in place
app-errors ingest --no-rtdb # local spool only
app-errors resolve <app> <signature> # mark it fixed; a newer build reopens it
```
`app_errors/install.sh` installs the venv
(`~/.local/share/app-errors/venv`), the `app-errors` link and
`app-errors-ingest.timer`. `scripts/deploy.sh` runs it.
RTDB access reuses an already seeded crdt-sync session (`--session`, default
`firebase_backup`), so the ingest needs no sign-in of its own.
Tests: `cd app_errors && python -m pytest` (100 % branch coverage).