kbdiag · KingbaseES diagnostics on kbdiag

Find long-running SQL

Mon, 01 Jan 0001 00:00:00 +0000

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. A fault-injection script started select pg_sleep(3600);, a statement that only sleeps. It tests detection, not CPU or disk pressure.

kbdiag 2.0 has no slow-SQL threshold yet: a long statement is listed and sorted, but not a WARN on its own. It becomes a finding when it holds a transaction open too long (txn) or makes others wait for a lock (locks).

Read a real result

Mon, 01 Jan 0001 00:00:00 +0000

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.

sessions: list sessions

Mon, 01 Jan 0001 00:00:00 +0000

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. The application sessions named kbdiag_inj_* were created by fault-injection scripts. PIDs, counts and timings belong to this capture only.

Usage

kbdiag sessions [--all] [--limit N] [--idle-in-txn-warn SECONDS] [--json]

Flag	Effect
`--all`	List every session, including idle ones and background processes
`--limit N`	Show at most N rows, default 50; `0` shows all
`--idle-in-txn-warn SECONDS`	WARN when a session is idle in transaction longer than this, default 300
`--json`	Print the report as JSON

Connection flags --host, -p, -d, -U and --timeout are global. Defaults: local socket in /tmp, port 54321, database test, user system. The password comes from PGPASSWORD or ~/.pgpass. The connection runs read-only transactions and sets lock_timeout.

Investigate lock waits

Mon, 01 Jan 0001 00:00:00 +0000

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. A fault-injection script opened a transaction that took an ACCESS EXCLUSIVE lock on a test table and then sat idle, and a second session tried to read the table.

1. Who is waiting?

~/kbdiag locks
echo EXIT_CODE=$?

locks WARN (KingbaseES V008R006C009B0014, primary, system@local, 2026-09-27T13:36:33+08:00)

[WARN] lock.waiting session 1048829 has waited 13s for AccessShareLock on public.kbdiag_inj_lock, blocked by 1048819
 verify: kbdiag session 1048819 # what the blocking session is doing

blockers: 1
 pid blocks holds
 1048819 1 public.kbdiag_inj_lock AccessExclusiveLock

waiting: 1
 pid object wants waited blocked by
 1048829 public.kbdiag_inj_lock AccessShareLock 13s 1048819
EXIT_CODE=1

Session 1048829 has waited 13 seconds for AccessShareLock on public.kbdiag_inj_lock; the direct blocker is 1048819. Waits over 10 seconds are a WARN (--lock-wait-warn changes this).
blockers comes first, because the first question is who is in the way. It shows 1048819 blocks one session and holds AccessExclusiveLock on the table. When one blocker holds up dozens of sessions, it is the top row.
waiting lists each waiting session, longest wait first. The wait is measured from the waiter’s last state change, so it can overstate the wait a little, never understate it.

2. What is the blocker doing?

Follow the verify line:

session: one session

Mon, 01 Jan 0001 00:00:00 +0000

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. The sessions in the examples were created by fault-injection scripts: 1045715 holds an exclusive lock on table kbdiag_inj_lock idle in transaction, 1045724 waits for it, and 1045809 is a second session idle in transaction. PIDs, counts and timings belong to this capture only.

locks: lock waits

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-09-27 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 93bf65d (static linux/amd64 binary). This is lab evidence, not production validation. The lock waits were created by fault-injection scripts. On the primary, 1045715 holds an exclusive lock on table kbdiag_inj_lock idle in transaction and 1045724 waits for it. A prepared (two-phase) transaction holds a lock on kbdiag_inj_2pc, and 1046007 waits for that. PIDs, counts and timings belong to this capture only.

txn: transactions

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-09-27 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 93bf65d (static linux/amd64 binary). This is lab evidence, not production validation. The transactions in the examples were created by fault-injection scripts: two sessions idle in transaction (one holding a table lock), sessions waiting for locks, a pg_sleep(3600), and kbdiag_inj_2pc, a prepared transaction that was neither committed nor rolled back. PIDs, counts and timings belong to this capture only.

waits: wait events

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-09-27 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 93bf65d (static linux/amd64 binary). This is lab evidence, not production validation. The sessions in the examples were created by fault-injection scripts: two sessions idle in transaction, two waiting for table locks, and a pg_sleep(3600). PIDs, counts and timings belong to this capture only.

Usage

kbdiag waits [--json]

No options of its own. Connection options are the same as for sessions.

status: instance overview

Mon, 01 Jan 0001 00:00:00 +0000

Usage

kbdiag status [--json]

status has no options of its own. Connection options are the same as for sessions.

slots: replication slots

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-09-27 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 93bf65d (static linux/amd64 binary). This is lab evidence, not production validation. The WARN example was created by a fault-injection script. It pauses the standby’s WAL receiver (SIGSTOP), so after wal_sender_timeout (30 seconds here) the primary’s slot turns inactive, as it does when a standby dies. Values belong to this capture only.

space: disk, WAL, databases

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-10-07 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 96c874f (static linux/amd64 binary). This is lab evidence, not production validation. Everything here comes from the healthy lab and from two accounts that cannot see everything: kbdiag_ro (no monitoring role) over 127.0.0.1, and kbdiag_ro over the node’s network address. No fault was injected for this command. The one FAIL it can report was not produced in the lab (see the last section). Values belong to this capture only.

freeze: wraparound distance

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-10-07 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 96c874f (static linux/amd64 binary). This is lab evidence, not production validation. Both nodes were healthy and nothing was injected, so every example is OK. The WARN and FAIL cases were not produced in the lab (see the last section). Values belong to this capture only.

Usage

kbdiag freeze [--limit N] [--json]

Option	Effect
`--limit N`	Show at most N tables; default 20, `0` for all
`--json`	Print JSON

Connection options are the same as for sessions. --limit only trims the table list; the findings always cover every database and every table.

vacuum: dead tuples and autovacuum

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-10-07 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 96c874f (static linux/amd64 binary). This is lab evidence, not production validation. The WARN example was created by an injection script: it made table public.kbdiag_inj_dead with autovacuum_enabled=off, inserted 10000 rows and deleted 5000, so the table holds 5000 dead tuples that nothing will clean. Values belong to this capture only.

archive: WAL archiving

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-10-07 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 96c874f (static linux/amd64 binary). This is lab evidence, not production validation. No fault was injected. The primary’s WAL archiving was already failing in the lab (its archive_command runs sys_rman archive-push, and the last success was 21 days earlier), so the WARN below is what the lab really looks like; why it fails was not investigated for this page, because kbdiag does not read the server log. Values belong to this capture only.

params: changed parameters

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-10-07 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 96c874f (static linux/amd64 binary). This is lab evidence, not production validation. The WARN example was created by an injection script: it changed max_files_per_process (a parameter that needs a restart) with ALTER SYSTEM, reloaded the configuration, and did not restart, so the running value differs from the file. Values belong to this capture only.

repl: replication from this node

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-10-07 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 96c874f (static linux/amd64 binary). This is lab evidence, not production validation. The WARN example was created by a fault-injection script that pauses the standby’s WAL receiver (SIGSTOP), the same one used on the slots page. Values belong to this capture only.

Usage

kbdiag repl [--json]

No options of its own. Connection options are the same as for sessions.

cluster: repmgr's view

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-10-07 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 96c874f (static linux/amd64 binary). This is lab evidence, not production validation. The cluster is managed by repmgr, with its metadata in database esrep. The WARN example was created by the fault-injection script that pauses the standby’s WAL receiver (SIGSTOP) until the standby is no longer attached to the primary, the same one used on the slots page. Values belong to this capture only.

top-objects: largest tables and indexes

Mon, 01 Jan 0001 00:00:00 +0000

Usage

kbdiag top-objects [--limit N] [--json]

Option	Effect
`--limit N`	Show at most N rows per list; default 20, `0` for all
`--json`	Print JSON

Connection options are the same as for sessions and it looks at the database you are connected to. This command only shows; it has no findings.

table: one table

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-10-07 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 96c874f (static linux/amd64 binary). This is lab evidence, not production validation. Two WARN/OK examples were created by injection scripts: public.kbdiag_inj_dead (table with autovacuum_enabled=off, 10000 rows inserted and 5000 deleted) and public.kbdiag_inj_tbl (20000 rows inserted, 5000 deleted, with a primary key and a second index). Values belong to this capture only.

top: cumulative top SQL

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-10-07 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 96c874f (static linux/amd64 binary). This is lab evidence, not production validation. Nothing was injected. In the lab sys_stat_statements.track is none on both nodes, so statements are not being collected and top has no rows to show. This page shows that case, which is what the lab really looks like. The case with statistics on was not captured (see the last section).

progress: long operations

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-10-07 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 96c874f (static linux/amd64 binary). This is lab evidence, not production validation. The running example was created by an injection script that ran CREATE INDEX on public.orders (1,000,000 rows) and was read three times while it ran, once by kbdiag_ro. PIDs and timings belong to this capture only.

Usage

kbdiag progress [--json]

No options of its own. Connection options are the same as for sessions.

checkpoint: checkpoint activity

Mon, 01 Jan 0001 00:00:00 +0000

Usage

kbdiag checkpoint [--json]

No options of its own. Connection options are the same as for sessions.

Primary

~/kbdiag checkpoint
echo EXIT_CODE=$?

checkpoint OK (KingbaseES V008R006C009B0014, primary, system@local, 2026-10-07T17:20:59+08:00)

last checkpoint
 time 2026-10-07 17:18:33 (2m 26s ago)
 redo 0/C651C548 (0000000300000000000000C6)

since the statistics reset 2026-09-15 23:12:34 (21d 18h ago)
 checkpoints 1606: 1606 timed, 0 requested (0%; requested covers WAL volume, CHECKPOINT, base backups, promotion)
 write, sync time 6m 54s, 490 ms
 buffers written 17029: checkpointer 10565 (62%), bgwriter 0 (0%), backends and others 6464 (38%)
 buffers allocated 37300
 backend fsyncs 0
 bgwriter stopped 0 times at bgwriter_lru_maxpages

settings
 checkpoint_timeout 5m 0s
 max_wal_size 1024 MB
 checkpoint_completion_target 0.5
 checkpoint_warning 30s
 log_checkpoints on
EXIT_CODE=0

last checkpoint is the time and the redo position (with its WAL file) of the latest checkpoint.
checkpoints counts timed and requested checkpoints since the statistics reset. “Requested” is not only WAL volume: a manual CHECKPOINT, a base backup (including a repmgr clone), a promotion, and creating or dropping a database count too. kbdiag gives the share but draws no conclusion. The server’s own “checkpoints too frequent” warning looks at the interval between two checkpoints (checkpoint_warning), which cumulative counters cannot give.
buffers written splits dirty-buffer writes into three: the checkpointer, the background writer, and “backends and others”. The third is not “the checkpointer cannot keep up”: in PG12 buffers_backend also counts relation extension, the ring buffers of VACUUM and COPY, and the standby’s startup process, so an idle node can show 60-70% there (65% and 70% were measured in this lab).
backend fsyncs above 0 is shown, not reported as a WARN. It means an fsync request could not be handed to the checkpointer, which happens when the queue is full or the checkpointer was not running at that moment (9 was measured earlier on this lab’s node2, which kbha had restarted).
settings is the relevant parameters.
Display only, so any probe that is not collected makes the verdict UNKNOWN; OK means “all collected”, not “good numbers”.

Standby

~/kbdiag checkpoint
echo EXIT_CODE=$?

checkpoint OK (KingbaseES V008R006C009B0014, standby, system@local, 2026-10-07T17:21:06+08:00)

checkpoint record the last restartpoint started from (written by the primary)
 time 2026-10-07 17:18:33 (2m 33s ago)
 redo 0/C651C548 (0000000300000000000000C6)

since the statistics reset 2026-10-07 16:49:26 (31m 40s ago)
 checkpoints 43 timed, 0 requested restartpoint attempts (a standby counts every try, one every 15s while no new checkpoint record has arrived)
 write, sync time 2m 51s, 26 ms
 buffers written 45117: checkpointer 7496 (17%), bgwriter 0 (0%), backends and others 37621 (83%)
 buffers allocated 38458
 backend fsyncs 1
 bgwriter stopped 0 times at bgwriter_lru_maxpages

settings
 checkpoint_timeout 5m 0s
 max_wal_size 1024 MB
 checkpoint_completion_target 0.5
 checkpoint_warning 30s
 log_checkpoints on
EXIT_CODE=0

On a standby these are not restartpoint counts. In PG12 the checkpointer adds one for every attempt, and with no new checkpoint record it tries every 15 seconds (over four days that was 15917 attempts on this lab’s node2), so the text says restartpoint attempts and gives no ratio.
The header says the checkpoint record the last restartpoint started from was written by the primary: the time is the primary’s.

Exit codes

Code	Meaning
0	OK
3	UNKNOWN: data not collected or not visible
64	Usage error
69	Cannot connect

Back to the manual

wal: WAL position and what keeps it

Mon, 01 Jan 0001 00:00:00 +0000

Usage

kbdiag wal [--json]

No options of its own. Connection options are the same as for sessions.

Primary

~/kbdiag wal
echo EXIT_CODE=$?

wal OK (KingbaseES V008R006C009B0014, primary, system@local, 2026-10-07T17:20:59+08:00)

position
 lsn 0/C9352468
 file 0000000300000000000000C9

sys_wal: 214 files, 3248 MB

what keeps WAL here
 max_wal_size 1024 MB
 wal_keep_segments 8192 MB (512 x 16 MB)
 slot repmgr_slot_2 0 bytes (active)
 archiving 38 .ready files waiting (kbdiag archive)
EXIT_CODE=0

position is the current write position and its WAL file.
sys_wal is the same size as on space: same probe, same columns.
what keeps WAL here puts on one screen what you would otherwise assemble from three commands: the parameters (max_wal_size, wal_keep_segments as its size), each replication slot with the WAL it retains and whether it is active, and the archive backlog. Here the slot retains 0 bytes and is active, but 38 .ready files wait for archiving (the lab’s archiving is failing, see archive).
It shows and does not repeat the judgment. An inactive slot is reported by kbdiag slots and a failing archive by kbdiag archive; this screen only points there. The same problem reported in three commands would look like three problems.
The WAL generation rate needs two samples over time; a single query cannot give it, so this version does not.

Standby

~/kbdiag wal
echo EXIT_CODE=$?

wal OK (KingbaseES V008R006C009B0014, standby, system@local, 2026-10-07T17:21:06+08:00)

position
 replayed 0/C9352A80

sys_wal: 198 files, 3136 MB

what keeps WAL here
 max_wal_size 1024 MB
 wal_keep_segments 8192 MB (512 x 16 MB)
 slots none
 archiving 0 .ready files waiting
EXIT_CODE=0

On a standby position is the replay position (there is no write position, and no WAL file name). This standby has no slots of its own, and nothing waits for archiving.

seq: sequences

Mon, 01 Jan 0001 00:00:00 +0000

Captured on 2026-10-07 (UTC+08) on a local KingbaseES V008R006C009B0014 primary and standby, database test, using ~/kbdiag built from Go source commit 96c874f (static linux/amd64 binary). This is lab evidence, not production validation. The FAIL example was created by an injection script: it created public.kbdiag_inj_seq with maxvalue 3 and used it up with nextval. Values belong to this capture only.

Usage

kbdiag seq [--limit N] [--json]

Option	Effect
`--limit N`	Show at most N sequences; default 20, `0` for all
`--json`	Print JSON

Connection options are the same as for sessions and it looks at the database you are connected to. --limit only trims the list; the finding covers every sequence.