`awa doctor`: one-command operational diagnostics
- Dominant language
- Rust
- Stars
- 32
- Forks
- 5
- Avg merge
- 15h 21m
- Merged PRs (30d)
- 21
Description
## Motivation
#169's operational playbook promised an `awa diagnose mvcc` CLI; it never shipped. Meanwhile the troubleshooting surface has grown: storage-transition blockers, ring rotation health, retention pruning, orphaned runtimes. An on-call operator at 3 a.m. should get the whole picture from one command instead of assembling psql queries from four docs pages.
## Scope
`awa doctor --database-url ...` with human-readable and `--json` output, checking:
- schema/binary version match; storage state + any transition blockers (feeds the 0.7 upgrade gate)
- oldest `pg_stat_activity.xact_start` / xmin horizon age vs configured thresholds (the #169 MVCC-discipline check)
- dead-tuple hotspots grouped by known table family, with expected-vs-anomalous framing
- autovacuum recency per hot family
- ring rotation health: `skipped_busy` / `blocked` rates, `current_slot` advancement
- orphaned/stale `runtime_instances`; leader liveness
- LISTEN/NOTIFY round-trip self-test (feeds the pooler-compat issue)
- DLQ depth, failed-retention `pruned_failed` deltas
- clock-skew sanity between client and server
Exit code reflects worst finding severity (ok / warn / critical).
## Acceptance
- Every scenario in `docs/troubleshooting.md` has a corresponding doctor check (and the doc links the command).
- `--json` output schema documented for automation.
- Doctor is referenced from the 0.6→0.7 upgrade guide for diagnosing non-finalized clusters.
## References
Roadmap: `docs/0.7-roadmap.md` (WS-3, NEW-9). Related: #169 (playbook item), #370-style upgrade gate, pooler compat issue, `docs/deploying-on-managed-postgres.md`.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reading docs/troubleshooting.md, docs/0.7-roadmap.md, docs/deploying-on-managed-postgres.md, and the related #169 playbook item. Map each troubleshooting scenario and upgrade-gate concern to a doctor check, then use the acceptance criteria to verify the documented human-readable and --json outputs, command links, and severity-based exit code.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- postgresql, rust
- Domain
- cli, databases, observability
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100