Capabilities
Start with the question you need to answer. Examples assume the binary is at ~/kbdiag; see the user manual for every flag and output field.
Instance
What is this instance, and do its basics hold?
Version, role (primary / standby), uptime, connections, which standbys it sends WAL to or where a standby receives WAL from, database sizes, and the disk holding the data directory. FAIL when every connection ordinary users may open is taken (max_connections less superuser_reserved_connections); WARN when a standby is not receiving WAL.
→ status
Sessions
Who holds the connections, which sessions are doing something, and what is one session doing?
sessions counts the connections by user, database, application and client, then lists the client sessions that are not idle, longest transaction first. It warns about sessions idle in transaction for more than 300 seconds. session <pid> shows one session in full: who it is, its whole SQL, the lock it waits for and who blocks it, whom it blocks and what it holds.
Locks
Who is waiting for a lock, and which session blocks them?
The blockers come first, the one blocking the most sessions at the top, then every waiting session, longest wait first. Each wait over 10 seconds is a WARN naming its direct blocker, and the verify line points to the blocker’s session. When a chain is several sessions long, follow it one hop at a time.
→ locks · Scenario: lock waits
Transactions
Who holds back the vacuum horizon: a transaction open too long, or a forgotten prepared (2PC) transaction?
The oldest transaction id first, with the sessions or prepared transaction holding it, then the open transactions and prepared ones. Open transactions WARN at 300 seconds and prepared transactions at 900, with a ROLLBACK PREPARED / COMMIT PREPARED suggestion printed for you to decide. Prepared transactions live on the primary; on a standby they are reported as not applicable.
→ txn
Waits
What are sessions waiting on right now?
The sessions doing something, grouped by wait event and state with their PIDs, biggest pile first. Idle sessions and background processes idling in their main loop are only counted. It summarizes without thresholds; use locks for how long and on whom.
→ waits · Scenario: long-running SQL
Replication slots
Is a slot keeping WAL for a standby that is gone?
Each slot with its consumer, the WAL it keeps and its xmin. An inactive slot keeps WAL and, with an xmin, holds back vacuum, so it is a WARN at once. The verify line sends you to status on the slot’s downstream node to check whether it still receives WAL. kbdiag never drops a slot.
→ slots
Script integration
Every command sets its exit code from the verdict and supports --json:
UNKNOWN means something could not be collected or seen, so kbdiag will not claim OK. 69 only means the connection failed; a database that accepts the connection but cannot answer is UNKNOWN. See exit codes.
Not in this version
Replication lag, repmgr cluster checks, slow-SQL history, vacuum and bloat, deadlock history and correlated diagnosis are not in kbdiag 2.0 yet. The frozen shell toolkit v1.0.0 still has health checks and reports if you need them.