This is the multi-page printable view of this section. .

Return to the regular view of this page.

Your first check

Build the binary, install it on the database host, connect, and read the verdict and exit code.

1: Read a real result

Build kbdiag once, copy it to the KingbaseES host, and run status and sessions. Then decide what needs a closer look.

1. Prepare

A running KingbaseES V8R6 instance (tested on V008R006C009B0014).
Access to the kingbase OS user on the database host.
A machine with Go (the version in the repository’s go.mod) and git, to build the binary. It can be your laptop; the database host needs nothing but the binary.

2. Build and install

On the build machine:

git clone https://github.com/Kevin-wenyu/kbdiag.git
cd kbdiag
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.version=$(git describe --tags --match 'v2*' --always)" -o kbdiag ./cmd/kbdiag
scp kbdiag kingbase@db-host:~/kbdiag

Use GOARCH=arm64 for ARM hosts. The result is one static file with no runtime dependencies, so an offline host only needs the file copied over.

On the database host:

sudo -iu kingbase
chmod +x ~/kbdiag
~/kbdiag --version

3. Connect

By default kbdiag connects over the local socket /tmp/.s.KINGBASE.54321 to database test as user system, the way ksql test system does. Change the target with flags:

Flag	Default
`--host`	`/tmp` (socket directory); a host name or IP for TCP
`-p, --port`	`54321`
`-d, --dbname`	`test`
`-U, --user`	`system`
`--timeout`	`10s` per query

The password comes from PGPASSWORD or ~/.pgpass. If kbdiag cannot connect, it prints the error and exits with 69; check the port, socket directory and sys_hba.conf before anything else.

An account without a monitoring role cannot see other sessions’ state, timings or SQL. kbdiag lists those fields under redacted and answers UNKNOWN rather than OK; grant sys_monitor or use system for the full picture.

4. Run your first checks

~/kbdiag status
echo "exit code: $?"
~/kbdiag sessions
echo "exit code: $?"

Read $? right after the command; the next command replaces it. status tells you what the instance is and whether its basics hold: connections, replication, disk. sessions shows who holds the connections and which sessions are doing something, and warns about sessions left idle in transaction.

5. Read the verdict and exit code

The first line of every report carries the verdict, and the exit code says the same thing:

Exit code	Verdict	Next step
`0`	OK	Nothing crossed a threshold in this sample
`1`	WARN	Nothing is broken yet, but it will be if left alone: read each finding and run its `verify` command
`2`	FAIL	Same, now: the application is already affected
`3`	UNKNOWN	Something could not be collected or seen; check privileges and the `redacted` list
`64`	Usage error	Check the command and flags
`69`	Cannot connect	Check the connection first; nothing was looked at

A WARN or FAIL finding wins over UNKNOWN: if kbdiag found a problem in what it could see, it says so.

Read a real result line by line

6. Follow the evidence

You see	Next command	Look for
A lock wait	`~/kbdiag session <blocker pid>`	What the blocker is doing and how long its transaction has been open
Idle in transaction	`~/kbdiag session <pid>`	The locks it holds and whether it blocks anyone
An old or prepared transaction	`~/kbdiag txn`	The oldest xid and who holds it, transaction age, the prepared transaction’s gid and owner
Many sessions waiting	`~/kbdiag waits`	Which wait event they share
Connections used up	`~/kbdiag sessions`	The summary at the top: a pile-up by user, database, application or client
An inactive slot	`~/kbdiag status` on the slot’s downstream node	Whether it answers, whether `inst.upstream` is `streaming`, and whether `last_msg` keeps growing

Each finding already prints the right one of these as its verify line.

Done

You have built and installed kbdiag, connected to the right instance, run status and sessions, and know what their exit codes mean.

Explore capabilities · Look up command options

1 - Read a real result

Real lab output of a WARN, line by line, in text and JSON.

Captured on 2026-09-27 (UTC+08) on a local KingbaseES V008R006C009B0014 primary, database test, using ~/kbdiag built from Go source commit 93bf65d (static linux/amd64 binary). This is lab evidence, not production validation. PIDs, counts and timings belong to this capture only. The idle-in-transaction session was created by a fault-injection script. The warning threshold was lowered to 5 seconds with --idle-in-txn-warn 5 so the example did not have to wait the default 300.

Command and output

~/kbdiag sessions --idle-in-txn-warn 5
echo EXIT_CODE=$?

sessions  WARN  (KingbaseES V008R006C009B0014, primary, system@local, 2026-09-27T13:37:04+08:00)

[WARN] session.idle_in_txn  session 1049818 has been idle in transaction for 9s
  verify: kbdiag session 1049818  # which locks it holds, whether it blocks anyone

connected: 4 client sessions (not counting kbdiag), 1 walsender, 7 background
  count  user    database  application          client
  2      esrep   esrep     internal_rwcmgr      192.168.105.10
  1      esrep   esrep     internal_rwcmgr      192.168.105.11
  1      system  test      kbdiag_inj_idle_txn  local

not idle: 2
  pid      user    database  application          client          state                xact  query  wait  sql
  1049818  system  test      kbdiag_inj_idle_txn  local           idle in transaction  11s   10s    -     select txid_current() as kbdiag_last, pg_sleep(1);
  179417   esrep   esrep     internal_rwcmgr      192.168.105.10  active               0s    0s     -     SELECT n.node_id, n.type, n.upstream_node_id, n.node_name...
EXIT_CODE=1

Line by line

First line: the command (sessions), the verdict (WARN) and the context: server version, role (primary), user@location (local is the socket) and when the data was collected.
Finding: [WARN], then a stable id (session.idle_in_txn), then the symptom: session 1049818 has been idle in transaction for 9 seconds. Scripts should rely on the id and the JSON fields; the wording of a symptom may change.
verify: the next command to run and why. Here: look at session 1049818 to see which locks it holds and whether it blocks anyone. A fix: line, when present, is a statement for you to review; kbdiag never runs it.
Data: laid out for reading. connected counts the client sessions by user, database, application and client. not idle lists the ones doing something or holding a transaction open, longest transaction first. - is null; ? would be a value this account may not see.
The esrep row is repmgr’s own query, caught while it ran. Idle sessions and background processes are only counted in the headings; --all lists them.
Exit code 1: WARN, meaning nothing is broken yet but it will be if left alone. A FAIL (the application is already affected) would be 2, UNKNOWN 3.

The same report in JSON

--json carries the same content with stable field names. This is the findings array of ~/kbdiag sessions --idle-in-txn-warn 5 --json, taken a moment later:

[
  {
    "id": "session.idle_in_txn",
    "level": "WARN",
    "symptom": "session 1049818 has been idle in transaction for 9s",
    "evidence": [
      {
        "probe_id": "session.activity",
        "fields": {
          "backend_xid": 6353,
          "pid": 1049818,
          "state": "idle in transaction",
          "state_age_s": 9.1
        }
      }
    ],
    "cause": null,
    "next": [
      {
        "kind": "verify",
        "command": "kbdiag session 1049818",
        "note": "which locks it holds, whether it blocks anyone"
      }
    ]
  }
]

The full report also has:

command, verdict and context.
data: each probe with its status, columns, rows and truncated. JSON keeps raw values (seconds, bytes, full SQL) and always carries every session, idle ones and background processes included. Here that is 12 rows, where the text lists 2.
redacted: the fields the account was not allowed to see.

The exit code is the same as in text mode.

What happened next

The injected session was released and a follow-up check found no test sessions left. In a real case, run the verify command and decide with the application owner whether the transaction should be committed, rolled back or the connection closed.

Investigate lock waits · Back to your first check