# Capabilities

> Choose a command by the question you need answered: instance, sessions, locks, transactions, waits, replication slots.

---

LLMS index: [llms.txt](/kbdiag-docs/llms.txt)

---

Start with the question you need to answer. Examples assume the binary is at `~/kbdiag`; see the [user manual](../reference/) for every flag and output field.

## Instance {#instance}

**What is this instance, and do its basics hold?**

```bash
~/kbdiag status
```

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](/kbdiag-docs/docs/reference/status/)

## Sessions {#sessions}

**Who holds the connections, which sessions are doing something, and what is one session doing?**

```bash
~/kbdiag sessions
~/kbdiag session <pid>
```

`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.

→ [sessions](/kbdiag-docs/docs/reference/sessions/) · [session](/kbdiag-docs/docs/reference/session/)

## Locks {#locks}

**Who is waiting for a lock, and which session blocks them?**

```bash
~/kbdiag locks
```

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](/kbdiag-docs/docs/reference/locks/) · [Scenario: lock waits](/kbdiag-docs/docs/scenarios/lock-waits/)

## Transactions {#txn}

**Who holds back the vacuum horizon: a transaction open too long, or a forgotten prepared (2PC) transaction?**

```bash
~/kbdiag txn
```

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](/kbdiag-docs/docs/reference/txn/)

## Waits {#waits}

**What are sessions waiting on right now?**

```bash
~/kbdiag waits
```

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](/kbdiag-docs/docs/reference/waits/) · [Scenario: long-running SQL](/kbdiag-docs/docs/scenarios/slow-sql/)

## Replication slots {#slots}

**Is a slot keeping WAL for a standby that is gone?**

```bash
~/kbdiag slots
```

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](/kbdiag-docs/docs/reference/slots/)

## Script integration {#automation}

Every command sets its exit code from the verdict and supports `--json`:

```bash
~/kbdiag --json locks
echo $?   # 0 OK, 1 WARN, 2 FAIL, 3 UNKNOWN, 64 usage error, 69 cannot connect
```

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](../get-started/#exit-codes).

## Not in this version {#not-yet}

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`](https://github.com/Kevin-wenyu/kbdiag/releases/tag/v1.0.0) still has health checks and reports if you need them.