hardbyte / hardbyte/awa

`awa doctor`: one-command operational diagnostics

Open
#373 0 comments 0 reactions 0 assignees View on GitHub
feature operational
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.