这是本节的多页打印视图。 .

第一次检查

编译二进制、装到数据库主机、连接实例，读懂结论和退出码。

1: 读懂一次真实结果

编译一次 kbdiag，拷到 KingbaseES 主机上，跑 status 和 sessions，再决定哪里需要细看。

1. 准备

一个运行中的 KingbaseES V8R6 实例（在 V008R006C009B0014 上测试）。
数据库主机上 kingbase OS 用户的权限。
一台装了 Go（版本见仓库的 go.mod）和 git 的机器，用来编译。可以就是你的笔记本；数据库主机上除了这个二进制什么都不用装。

2. 编译和安装

在编译机上：

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

ARM 主机用 GOARCH=arm64。产物是一个没有运行时依赖的静态文件，离线主机只要把这个文件拷过去。

在数据库主机上：

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

3. 连接

默认走本地 socket /tmp/.s.KINGBASE.54321，以 system 用户连 test 库，和 ksql test system 一样。用参数换目标：

参数	默认值
`--host`	`/tmp`（socket 目录）；写主机名或 IP 走 TCP
`-p, --port`	`54321`
`-d, --dbname`	`test`
`-U, --user`	`system`
`--timeout`	每条查询 `10s`

密码从 PGPASSWORD 或 ~/.pgpass 取。连不上时 kbdiag 打印错误并以 69 退出；先查端口、socket 目录和 sys_hba.conf。

没有监控角色的账号看不到别人会话的状态、时间和 SQL。kbdiag 把这些字段列进 redacted，结论给 UNKNOWN 而不是 OK；授予 sys_monitor 或者用 system 才能看全。

4. 跑第一次检查

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

$? 要紧跟在命令后面读，下一条命令会覆盖它。status 告诉你这是个什么实例、基本面是否正常：连接、复制、磁盘；sessions 告诉你连接是谁占的、哪些会话在干活，并对停在 idle in transaction 的会话报警。

5. 读懂结论和退出码

每份报告第一行就是结论，退出码说的是同一件事：

退出码	结论	下一步
`0`	OK	这次采样里没有越过阈值的
`1`	WARN	还没坏，但放着不管会出事：逐条看 finding，跑它的 `verify` 命令
`2`	FAIL	同上，而且现在就要处理：业务已经受影响
`3`	UNKNOWN	有东西没采到或看不到；查权限和 `redacted` 列表
`64`	参数错误	检查命令和参数
`69`	连不上	先解决连接；这次什么都没看

WARN 或 FAIL 的 finding 优先于 UNKNOWN：在看得到的范围里发现了问题，就直接报出来。

逐行读一个真实结果

6. 顺着证据往下查

看到	下一条命令	看什么
锁等待	`~/kbdiag session <挡路者 pid>`	挡路者在干什么、事务开了多久
idle in transaction	`~/kbdiag session <pid>`	它持有哪些锁、有没有挡住别人
老事务或两阶段事务	`~/kbdiag txn`	最老的事务号和谁持有它，事务时长，两阶段事务的 gid 和 owner
很多会话在等	`~/kbdiag waits`	它们等的是不是同一个事件
连接占满	`~/kbdiag sessions`	最上面的汇总：按用户、库、应用、客户端看有没有扎堆
未激活的槽	在这个槽的下游节点上跑 `~/kbdiag status`	连不连得上、`inst.upstream` 是不是 `streaming`、`last_msg` 是否一直在涨

每条 finding 的 verify 行已经给出了对应的那一条。

完成标准

你已经编译并装好 kbdiag，连上了正确的实例，跑过 status 和 sessions，也知道它们的退出码是什么意思。

功能概览 · 查阅命令参数

1 - 读懂一次真实结果

一次真实的 WARN 输出，逐行解读，文本和 JSON 两种格式。

采集于 2026-09-27（UTC+08），本地 KingbaseES V008R006C009B0014 主节点，数据库 test。工具是 Go 版源码提交 93bf65d 编译的 ~/kbdiag（linux/amd64 静态二进制）。这是测试环境实测，不代表生产环境验收。PID、计数与时间只属于本次采样。idle in transaction 的会话是故障注入脚本造出来的；用 --idle-in-txn-warn 5 把报警阈值降到 5 秒，免得例子要等默认的 300 秒。

命令和输出

~/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

逐行解读

第一行：命令（sessions）、结论（WARN）和上下文：服务器版本、角色（primary）、用户@位置（local 是 socket）、采集时间。
finding：[WARN]，然后是稳定的 id（session.idle_in_txn），再是症状：会话 1049818 处于 idle in transaction 已 9 秒。脚本应当依赖 id 和 JSON 字段，症状的措辞可能会变。
verify: 下一步该跑的命令和原因。这里是：看会话 1049818 持有哪些锁、有没有挡住别人。出现 fix: 行时，它给的是一条供你审阅的语句，kbdiag 从不执行。
数据：按便于阅读的方式排版。connected 按用户、库、应用、客户端给客户端会话计数；not idle 列出在干活或开着事务的会话，事务最久的在前。- 是空值；? 表示这个账号看不到的值。
esrep 那一行是 repmgr 自己的查询，采样时正好在跑。idle 的会话和后台进程只在标题里计数，要看用 --all。
退出码 1：WARN，表示还没坏，但放着不管会出事。FAIL（业务已经受影响）是 2，UNKNOWN 是 3。

同一份报告的 JSON

--json 带同样的内容，字段名稳定。下面是 ~/kbdiag sessions --idle-in-txn-warn 5 --json 稍后一次运行的 findings 数组：

[
  {
    "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"
      }
    ]
  }
]

完整报告里还有：

command、verdict、context。
data：每个 probe 的 status、columns、rows、truncated。JSON 保留原始值（秒、字节、完整 SQL），而且总是包含全部会话，idle 的会话和后台进程也在内：这里是 12 行，文本只列了 2 行。
redacted：这个账号无权看到的字段。

退出码和文本模式相同。

后来

注入的会话随后被释放，复查确认测试会话已全部清掉。真实场景下，先跑 verify 命令，再和应用负责人一起决定：提交、回滚，还是关掉连接。

排查锁等待 · 回到第一次检查