README-CN.md

OceanBase Diagnostic Tool (obdiag)

简介

OceanBase Diagnostic Tool (obdiag) 是一款专门为OceanBase打造的敏捷诊断工具，功能包括诊断信息收集、分析、巡检，可以在OceanBase集群不同的部署模式下（OCP，OBD或用户根据文档手工部署）实现一键执行。

项目价值 & 愿景

安装 obdiag

可通过如下方式安装obdiag

方式一: 通过rpm包安装

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://mirrors.aliyun.com/oceanbase/OceanBase.repo
sudo yum install -y oceanbase-diagnostic-tool
sh /opt/oceanbase-diagnostic-tool/init.sh

方式二：源码安装

源码安装需要在python >= 3.11的环境下进行

make init
source ~/.bashrc

obdiag config

配置文件的默认路径是~/.obdiag/config.yml . 可直接编辑配置文件或者通过obdiag config <option> 命令快速生成配置

obdiag config -h <db_host> -u <sys_user> [-p password] [-P port]

obdiag 功能

• 一键集群巡检
• 一键诊断分析
• 一键根因分析
• 一键信息采集
• 一键集群洞察

参与贡献

obdiag 期望构建一个开放的社区，我们欢迎任何形式的贡献，您可以：

• 通过 Issues 提交 bug。
• 通过 Discussion 参与或发起讨论。
• 通过 Pull requests 提交问题修复或者功能特性。

Roadmap Ahead

版本	迭代周期	发布日期	功能点
1.6.0	2024.01	2024.01.31	场景化信息采集 场景化根因分析
2.0.0	2024.03	2024.04.11	context改造，场景化扩展能力增强 支持在线更新巡检、采集的task 根因分析二期
2.1.0	2024.04	2024.05.13	根因分析场景扩展 新增 ash 报告 采集
2.2.0	2024.05	2024.06.14	根因分析场景扩展 巡检场景扩展
2.3.0	2024.06	2024.07.24	根因分析场景扩展 新增基础采集功能: tabledump 新增参数/变量比对分析功能 执行底座改造，支持 k8s 部署的 OceanBase 集群诊断
2.4.0	2024.07	2024.09.03	易用性改造 索引空间分析
2.5.0	2024.09	2024.10.18	场景化一键展示集群信息功能 队列积压分析 支持对收集的observer日志按指定规则进行敏感内容脱敏
2.6.0	2024.10	2024.11.28	新增 obdiag analyze memory 功能 obdiag display 二期迭代
3.0.0	2024.12	2024.12.31	插件化改造 支持 OMS 诊断
3.1.0	2025.01	2025.01.22	obdiag display 三期迭代
3.2.0	2025.01	2025.03.14	obdiag 适配 ipv6 obdiag gather stack 支持 arm 机器 巡检场景扩展
3.3.0	2025.04	2025.04.18	obdiag check 支持 python 脚本以适应复杂场景的巡检
3.4.0	2025.05	2025.05.15	obdiag rca 支持 OMS obcdc 通用问题根因分析 新增 obdiag gather dbms_xplan
3.5.0	2025.06	2025.06.20	根因分析场景扩展 巡检场景扩展
3.6.0	2025.07	2025.07.31	新增 obdiag tool 功能 支持 MCP
3.7.0	2025.08	2025.09.09	obdiag-mcp 新增 pip 安装方式(pip install obdiag-mcp) 巡检场景扩展
3.7.1	2025.09	2025.10.22	巡检场景扩展
3.7.2	2025.10	2025.11.27	巡检场景扩展
4.0.0	2025.12	2026.01.07	新增 obdiag agent 命令，智能诊断 agent（BETA） 新增 obdiag tool io_performance 命令，磁盘 IO 性能检测工具 新增 obdiag tool config_check 命令，配置校验工具 新增 obdiag display scene run --scene=observer.compaction 命令，合并状态展示场景 根因分析场景扩展
4.1.0	2026.02	2026.02.11	依赖管理迁移至 pyproject.toml 新增 obdiag display-trace 命令，便于排查命令执行问题 新增 obdiag display scene run --scene=observer.log_volume_statistics，CLOG 日志量/容量统计 obdiag gather perf 支持火焰图 SVG 生成 obdiag check run、obdiag rca run 支持 HTML 报告输出 巡检场景扩展、采集场景扩展
4.2.0	2026.03	2026.03.11	巡检重构：优化 SSH 连接处理，新增 docker0 网卡检查 支持采集 OBProxy 进程 perf 信息 gather plan_monitor 增强去重与 CREATE TABLE DDL 处理 优化 analyze memory 结果展示 更新 obdiag 命令生成器，ddl_disk_full、cpu_high RCA 场景更新

支持

如果您在使用 obdiag 时遇到任何问题，欢迎联系我们寻求帮助：

• GitHub Issue
• 官方网站

开发者专区

加入我们

请添加 OB社区小助手（微信号：obce666）并备注“obdiag SIG”，工作人员会联系并指引您加入 SIG 的相关事宜。期待您的积极参与与宝贵贡献！

开发者行动指南

1. Fork并克隆你的专属副本：在我们的GitHub仓库页面右上角点击“Fork”按钮，这样就在你的账号下创建了一份仓库副本。接下来，使用Git命令将这份副本克隆到你的本地计算机上：

git clone https://github.com/your_username/your_repo_here.git

2. 修改代码：无论是修正漏洞还是增添新功能，你的每一份贡献都至关重要。

3. 通过 black 工具统一格式化你的代码 🎨

make format

4. 提交你的改动：完成优化后，利用Git提交你的修改。

5. 推送到你的Fork仓库：将你的改动推送到GitHub上的Fork仓库中。

6. 发起合并请求（PR）：回到你的GitHub分叉页面，点击“Open pull request”按钮。对比你的分支与原始仓库的主分支，描述你的改动内容，然后提交PR！

7. 🚀 自动化流程接棒此处 🤖

接下来，就交给我们的GitHub Actions流水线：

• 代码检查：PR一旦触发，流水线会自动代码格式化检查以及安全检查。
• 自动构建：PR一旦触发，就会自动将你的改动编译成RPM和DEB两种软件包。

许可证

OceanBase Diagnostic Tool 使用 MulanPSL - 2.0 许可证。 您可以免费复制及使用源代码。当您修改或分发源代码时，请遵守木兰协议。