OceanBase 数据库是原生分布式数据库系统，故障根因分析通常涉及机器环境、配置参数、运行负载等多方面因素。专家在排查问题时需要获取大量分散在各节点的信息。OceanBase 敏捷诊断工具（OceanBase Diagnostic Tool，简称 obdiag）致力于高效采集与分析故障场景下的诊断信息。obdiag 代码完全开源，详见 GitHub 代码仓库。
什么是 obdiag
obdiag 是一款专为 OceanBase 打造的黑屏诊断工具，支持对集群日志、SQL 审计、进程堆栈等信息的扫描、收集与分析，可在 OCP、OBD 或用户手工部署等不同部署模式下实现一键执行，完成诊断信息的展示、收集、分析、巡检与根因分析。在线体验请移步 在线体验。
obdiag 功能特点
- 部署简单：提供 RPM/DEB 包及 obd 集成部署，可部署在任意能连通集群各节点的机器上，不限于 OBServer 节点。
- 集中式收集：单点部署，在部署机上执行收集、巡检或分析命令即可。
- 简单易用：一条命令完成安装；一键集群巡检、一键信息采集、一键诊断分析、一键根因分析、一键集群洞察均可通过命令完成。
- 完全开源：基于 Python 开发，源代码 100% 开源，详见 GitHub 代码仓库。
- 高度可扩展：一键巡检、场景化采集、根因分析、集群洞察均为插件化设计，可低成本扩展自定义场景。
obdiag 核心功能概览
功能模块 |
说明 |
|---|---|
| obdiag config | 快速生成/编辑集群配置文件（默认 ~/.obdiag/config.yml）。 |
| obdiag gather | 一键采集诊断信息：日志、参数/变量、主机信息、堆栈、perf、clog/slog、AWR、ASH、OBProxy/OMS 日志、场景化采集、表导出（tabledump）、DBMS_XPLAN、core 等。 |
| obdiag display | 一键集群洞察：按场景展示集群信息、合并状态(compaction)等，黑屏输出不落盘。 |
| obdiag check | 一键集群巡检：对 OceanBase 数据库/OBProxy 执行巡检任务，支持 YAML 与 Python 脚本，输出表格/JSON/XML/YAML/HTML 报告。 |
| obdiag analyze | 一键诊断分析：日志分析、FLT trace 全链路、参数/变量比对、队列积压、索引空间、内存分析、SQL 审计规则审核、SQL 文件规则审核等。 |
| obdiag rca | 一键根因分析：按场景执行根因分析（断连、锁冲突、磁盘满、事务超时、OMS/OBCDC 等）。 |
| obdiag update | 热更新巡检与场景化采集的任务文件（支持在线/本地文件）。 |
| obdiag agent | 智能诊断 Agent（BETA）：基于 LangChain/LangGraph 与 MCP，支持自然语言描述诊断需求，并调用 obdiag 的采集、分析、巡检、根因分析等能力。 |
| obdiag tool | 工具箱：配置文件加密（crypto_config）、SQL 语法校验（sql_syntax）、磁盘 IO 性能检测（io_performance）、配置校验（config_check）。 |
| obdiag display-trace | 根据 Trace ID 查看当次执行的详细日志。 |
obdiag V5.0.0 及当前版本支持能力
信息采集 (gather)
- 一键收集 OceanBase 集群日志（observer/election/rootservice）、OBProxy 日志、OMS 日志；支持时间范围、关键字过滤、按文件数量限制、日志脱敏。
- 一键收集集群参数/变量、主机信息（sysstat）、堆栈（stack）、perf（sample/flame/pstack）、clog/slog、AWR（依赖企业版 OCP）、ASH、并行 SQL 执行详情（plan_monitor）、表导出（tabledump）、DBMS_XPLAN、core 诊断信息。
- 场景化采集：支持 observer/obproxy/other 多类场景（如 CPU 高、SQL 异常、集群宕机、合并、备份恢复、回滚事务、OBProxy 重启等），支持
obdiag gather scene list与obdiag gather scene run --scene=xxx。
集群洞察 (display)
- 一键按场景展示集群信息（集群/节点/Zone/RS/租户/事件/锁持有/TopSQL/慢 SQL/表信息/进程列表/执行计划/数据量/合并状态等），支持
obdiag display scene list与obdiag display scene run --scene=xxx。 - V4.0.0 起支持合并状态展示场景：
obdiag display scene run --scene=observer.compaction。 - V4.1.0 起支持 clog 日志量/容量统计场景：
obdiag display scene run --scene=observer.clog_volume_statistics。
- 一键按场景展示集群信息（集群/节点/Zone/RS/租户/事件/锁持有/TopSQL/慢 SQL/表信息/进程列表/执行计划/数据量/合并状态等），支持
集群巡检 (check)
一键对 OceanBase 集群执行巡检，支持 OBServer 节点与 OBProxy 的 YAML/Python 任务，输出 table/json/xml/yaml/html 报告；支持obdiag check list与obdiag check run。可通过系统配置inner_config.yml调整并发（check.max_workers）、单任务超时（check.task_timeout_seconds）及 SSH 连接池（check.ssh_manager）等。诊断分析 (analyze)
- 一键分析 OceanBase 集群日志（在线/离线）、FLT trace 全链路、参数/变量 diff 与默认值、队列积压、索引（含预创建）空间、内存（在线/离线）。
obdiag analyze sql：按时间范围从 SQL 审计拉取语句并做内置规则审核，输出 HTML/JSON。具体介绍可参见 SQL 审计分析与规则审核。obdiag analyze sql_review：对本地 SQL 文件/目录做相同规则审核，输出 HTML/JSON。具体介绍可参见 SQL 文件审核。
根因分析 (rca)
按场景一键根因分析（断连、major 卡住、锁冲突、DDL/clog 盘满、日志错误、事务断连/超时/不结束/回滚、OMS 全量/OBCDC、挂起事务、unit GC、回放卡住、内存满、删 server 异常、GC/弱读/分裂调度等），支持obdiag rca list与obdiag rca run --scene=xxx。智能诊断 Agent (agent)（BETA）
obdiag agent：交互或非交互模式，调用内置 MCP 工具完成诊断。V5.0.0 版本开始底层迁移至 deepagents-cli TUI，支持更丰富的终端交互体验；具体介绍可参见 智能诊断 Agent。工具箱 (tool)
- crypto_config：对 config 文件进行加密/解密。
- sql_syntax：对单条 SQL 使用 EXPLAIN 做语法/语义校验（不执行原语句）。具体介绍可参见 SQL 语法校验工具。
- io_performance：磁盘 IO 性能检测（基于 tsar，支持指定磁盘或 clog/data 自动识别）。
- config_check：校验
--config参数是否合法。
其他
支持 Docker、Kubernetes（ob-operator）部署的集群诊断；支持 IPv6；gather stack 支持 ARM；巡检与场景化采集支持热更新；支持通过--config无配置文件开箱即用；支持加密配置与--config_password。