V5.0.0

Version Information / 版本信息

• Release Date / 发布时间：May 2026 / 2026 年 05 月
• Version / 版本号：V5.0.0

What's Changed

• feat(check): add ob_vector_memory_limit_percentage inspection by @wayyoungboy in #1232 and #1233
• feat(check): add load_vector_index_on_follower inspection; skill/docs updates by @wayyoungboy in #1234
• feat(check): detect CLOG write throttling via log and GV$OB_PARAMETERS by @wayyoungboy in #1235
• chore: bump obdiag version to 5.0.0 by @wayyoungboy in #1236
• feat(check/rca): connection-category checks, new observer tasks, RCA ob_connector hardening by @wayyoungboy in #1240
• feat(agent): migrate to deepagents-cli TUI and update skills by @wayyoungboy in #1243
• feat(agent): improve non-interactive TUI workflow by @wayyoungboy in #1244
• fix: gather/Agent bugfixes for 5.0.0 (incl. PyMySQL callproc / ASH) by @wayyoungboy in #1245

New Features and Changes / 新版本变更功能点

New Commands / 新增命令

• 本版本无新增顶层子命令；能力主要体现在 Agent TUI、巡检任务 与 RCA/Check 分类 调整上。 / No new top-level CLI commands in this release; changes focus on the Agent TUI, check tasks, and RCA/check layout.

Feature Enhancements / 功能增强

• 【新增】巡检：增加 ob_vector_memory_limit_percentage 相关检查（#1232、#1233）。 / Check: adds inspection around ob_vector_memory_limit_percentage (#1232, #1233).

• 【新增】巡检：增加 load_vector_index_on_follower 检查；对参数为 false 等场景给出提示（与 RT 敏感负载相关说明）；最低 Observer 版本要求 4.4.1.0（#1231，合入 #1234）。 / Check: adds load_vector_index_on_follower inspection with warnings when the parameter is false (per workload guidance); requires Observer 4.4.1.0+ (#1231 via #1234).

• 【新增】巡检：结合日志与 GV$OB_PARAMETERS 探测 CLOG 写入限流（write throttling） 迹象（#1235）。 / Check: detects CLOG write throttling signals using logs and GV$OB_PARAMETERS (#1235).

• 【优化】RCA / 巡检连接类：将 ObProxy diagnosis_connection_error 从 log/ 调至 connection/ 分类；在 lock_conflict、major_hold 等 RCA 场景中补充 ob_connector 空指针 防护；新增多项 Observer 侧检查任务（如 server_load_error、session_killed、transaction_killed、disk_space_full 等）（#1240）。 / RCA / connection checks: moves ObProxy diagnosis_connection_error to connection/; hardens ob_connector null handling in lock_conflict and major_hold; adds Observer tasks such as server_load_error, session_killed, transaction_killed, disk_space_full (#1240).

• 【变更】Agent：迁移至 deepagents-cli 体系下的 TUI（vendored 至 src/handler/agent/tui/），重构 Agent handler 与 toolsets；新增/更新多份 SKILL.md；更新 pyproject.toml 依赖与 conf/agent.yml.example；移除由新 TUI 层替代的遗留 mcp/、tools/ 模块；同步 CodeQL / 许可证头与 vendored MIT 声明（src/handler/agent/tui/LICENSE）（#1243）。 / Agent: migrates to deepagents-cli-style TUI (vendored under src/handler/agent/tui/), refactors handler/toolsets, refreshes skills and conf/agent.yml.example, updates pyproject.toml, removes legacy mcp//tools/, and addresses CodeQL / MIT attribution for vendored code (#1243).

• 【优化】Agent：改进非交互运行路径、resume、绝对路径与工具调用展示/修复等体验（#1244、#1245）。 / Agent: improves non-interactive runs, resume handling, absolute paths, and tool-call display/repair (#1244, #1245).

• 【修复】Gather：修复在 PyMySQL ≥ 1.1.3 下 cursor.callproc() 对反引号转义导致 OceanBase 报 1305（存储过程不存在）的问题；对 DBMS_WORKLOAD_REPOSITORY.ASH_REPORT 等路径改为使用 CALL ... 的 execute 方式绕过该转义（#1245）。 / Gather: fixes 1305 “procedure does not exist” with PyMySQL ≥ 1.1.3 due to backtick escaping in cursor.callproc(); uses raw CALL ... via execute for DBMS_WORKLOAD_REPOSITORY.ASH_REPORT and similar (#1245).

Installation and Build / 安装与构建

• 【变更】版本号提升至 5.0.0（#1236）。 / Version bump to 5.0.0 (#1236).

• 【变更】Agent 依赖与打包随 TUI / LangChain 栈更新；请以当前 pyproject.toml 为准安装（#1243）。 / Agent install/bundle follows updated TUI / LangChain deps per pyproject.toml (#1243).

Dependency Changes / 依赖变更

• 【变更】Agent 侧引入/对齐 deepagents、textual、langchain 等与 TUI 相关的依赖版本（详见 #1243 与 pyproject.toml）。 / Agent stack pins/updates deepagents, textual, langchain, etc. — see #1243 and pyproject.toml.

Notes / 注意

1. V4.3.0 → V5.0.0：若你仍保留 v4.3.0 时代的 ai.yml / Agent 配置，请对照仓库内 conf/agent.yml.example 升级到 5.0.0 推荐的 TUI 配置格式。 / v4.3.0 → v5.0.0: migrate Agent config using conf/agent.yml.example for the new TUI-oriented layout.

2. load_vector_index_on_follower 巡检项要求 Observer ≥ 4.4.1.0；不满足版本时行为以任务内说明/告警为准。 / The load_vector_index_on_follower check targets Observer ≥ 4.4.1.0; expect skips or warnings on older versions.

3. 中文文档入口：obdiag 文档（中文）。 / Chinese docs: obdiag (CN).

Full Changelog: v4.3.0...v5.0.0

obdiag V4.3.0

RN 链接：https://www.oceanbase.com/docs/obdiag-cn

📌【新增】AI 助手重构为基于 Pydantic-AI 与 MCP 的 Agent 能力，并配套 skills、会话与工具集扩展；支持 OpenAI 兼容请求头等集成方式。具体介绍可参见官方文档与仓库内 Agent 相关说明。

📌【新增】SQL 语法校验工具（#1224），便于在诊断流程中前置发现 SQL 语法问题。

📌【新增】SQL Review（sqlreview）相关能力（#1213）。

📌【优化】Check 任务增加超时能力并重构检查配置，提升巡检可控性与可维护性。

📌【优化】多处在 SQL 处理中将 query_sql 转为 utf8mb4，改善字符集一致性（#1218）。

📌【优化】Check 相关逻辑与配置更新（#1217）；CI 与命令初始化脚本、Roadmap 等随版本演进更新（#1223、#1215）。

📌【优化】代码质量改进：收敛裸 except、清理无效代码等（#1212）。

📌【修复】修复 gather plan_monitor 在校验 database 场景下的问题（#1210）。

📌【修复】修复 glibc 版本范围相关问题（bug469，#1211）。

📌【修复】及其他问题修复与行为优化（如 #1221 issue 934、Agent GenAI 价格相关 #1220 等）。

📌【变更】随 4.3.0 发版更新内置 skills 与助手相关行为（#1226、#1229）。

Full Changelog: v4.2.0...v4.3.0

v4.2.0

obdiag V4.2.0

What's Changed

• 420 check refactor by @wayyoungboy in #1189
• Enhancement: Add deduplication of parse tables in GatherPlanMonitorHa… by @wayyoungboy in #1191
• 420 Obdiag supports collecting perf information of obproxy processes by @wayyoungboy in #1190
• close #1010 || close #1010 by @wayyoungboy in #1192
• Issue 982 by @wayyoungboy in #1194
• Issue 1109 by @wayyoungboy in #1193
• Issue 228 by @wayyoungboy in #1196
• Issue 727 by @wayyoungboy in #1195
• feat(analyze memory): optimize result style for issue #559 by @wayyoungboy in #1197
• feat(check): add docker0 interface check for build_before deployment env (issue #1198) by @wayyoungboy in #1199
• chore: update version to 4.2.0 by @wayyoungboy in #1200
• fix(check): improve SSH connection handling for check run by @wayyoungboy in #1201
• Enhance deduplication, logging, and CREATE TABLE DDL handling by @wayyoungboy in #1203
• 420 update obdiag command generator by @wayyoungboy in #1204
• update: ddl_disk_full.py cpu_high.py by @wayyoungboy in #1206

Full Changelog: v4.1.0...v4.2.0

v4.1.0

obdiag V4.1.0

Version Information / 版本信息

• Release Date / 发布时间：February 2026 / 2026 年 02 月
• Version / 版本号：V4.1.0

What's Changed

• build(deps): bump pynacl from 1.5.0 to 1.6.2 by @dependabot[bot] in #1156
• 410 gather update by @wayyoungboy in #1160
• 410 check update by @wayyoungboy in #1161
• Fix (analyzer): Fix tenant dictionary initialization issue in memory … by @wayyoungboy in #1162
• feat(rca): Added memory throttling issue detection functionality by @wayyoungboy in #1164
• feat(observer): Add dump merge and freeze information query by @wayyoungboy in #1165
• refactor(rca): Unify file naming conventions by @wayyoungboy in #1166
• feat(obi): Integrate OceanBase Intelligence (OBI) client for enhanced by @wayyoungboy in #1167
• Feature (monitor): Add histogram statistics function for SQL plan mon… by @wayyoungboy in #1168
• Refactor (analyze-log): Optimize log analysis and processing logic by @wayyoungboy in #1170
• Feature (display): Added configuration for clog capacity statistics task by @wayyoungboy in #1171
• Feature (gather_perf): Add flame map generation function by @wayyoungboy in #1172
• Feature (analyze-log): Add tenant filtering for log analysis by @wayyoungboy in #1173
• feat：src/common/tool.py — SQLTableExtractor by @wayyoungboy in #1174
• Feature (analyzer): Optimize flt trace log analysis logic by @wayyoungboy in #1175
• Refactor: Transition to pyproject.toml for dependency management by @wayyoungboy in #1176
• Chore: Update obdiag version to 4.1.0 by @wayyoungboy in #1177
• Feature: Add obdiag command line entry by @wayyoungboy in #1178
• Chore: Shorten the accuracy of build timestamps by @wayyoungboy in #1179
• Enhancement: Update configuration and improve error handling in netwo… by @wayyoungboy in #1180
• Feature (gather): Improve the path processing of flame graph scripts by @wayyoungboy in #1182
• 410 close obi by @wayyoungboy in #1183
• 410 ci fix by @wayyoungboy in #1184
• 410 add httml by @wayyoungboy in #1185

New Features and Changes / 新版本变更功能点

New Commands / 新增命令

• 【新增】obdiag display scene run command adds CLOG log volume/capacity statistics scene (observer.log_volume_statistics), supporting display of CLOG log disk capacity and usage for each node/tenant. / obdiag display scene run 命令新增 CLOG 日志量/容量统计场景（observer.log_volume_statistics），支持展示各节点/租户 CLOG 日志盘容量与使用情况。

• 【新增】obdiag display-trace <trace_id> command for viewing detailed logs of a single obdiag execution, facilitating troubleshooting of command execution issues. The terminal will prompt available trace_id after executing some commands. / obdiag display-trace <trace_id> 命令，用于查看单次 obdiag 执行的详细日志，便于排查命令执行问题。执行部分命令后终端会提示可用的 trace_id。

Feature Enhancements / 功能增强

• 【新增】obdiag gather perf command supports generating flame graph SVG for analyzing CPU hotspots. Requires flamegraph.pl and stackcollapse-perf.pl in dependencies/bin. / obdiag gather perf 命令支持生成火焰图 SVG，便于分析 CPU 热点。需在 dependencies/bin 下提供 flamegraph.pl 与 stackcollapse-perf.pl。

• 【新增】obdiag analyze log command adds --tenant_id parameter, supporting tenant-based error statistics filtering; analysis logic refactored to support collecting compressed packages first and then decompressing locally for analysis, improving efficiency of large log analysis. / obdiag analyze log 命令新增 --tenant_id 参数，支持按租户过滤错误统计；分析逻辑重构，支持先收集压缩包再本地解压分析，提升大日志分析效率。

• 【新增】obdiag analyze flt_trace supports filtering OBProxy nodes by client IP and obtains client IP from SQL audit views, compatible with multiple OceanBase versions. / obdiag analyze flt_trace 支持按客户端 IP 过滤 OBProxy 节点，并从 SQL 审计视图获取 client IP，兼容多版本 OceanBase。

• 【新增】obdiag gather plan_monitor reports now include histogram statistics (table-level/partition-level) for analyzing execution plans and statistics (requires OceanBase 4.0.0.0 and above). / obdiag gather plan_monitor 生成的报告中增加统计信息直方图（表级/分区级），便于分析执行计划与统计信息（需要 OceanBase 4.0.0.0 及以上版本）。

• 【新增】obdiag check run and obdiag rca run commands support HTML report format output, facilitating viewing and sharing of inspection and root cause analysis results. / obdiag check run 和 obdiag rca run 命令支持 HTML 报告格式输出，便于查看和分享巡检与根因分析结果。

• 【优化】Major compaction hold RCA scene (obdiag rca run --scene=major_hold) adds memory throttling checks and dump/merge/freeze related information queries, facilitating identification of compaction hold causes. / 卡合并 RCA 场景（obdiag rca run --scene=major_hold）增加内存节流检查及 dump/merge/freeze 相关信息查询，便于定位合并卡住原因。

• 【优化】RCA scene file naming conventions unified for improved consistency. / RCA 场景文件命名规范统一，提升一致性。

• 【修复】Fixed tenant dictionary initialization issue in memory analysis. / 修复内存分析中租户字典初始化问题。

• 【变更】Check framework refactored from checker to check, adopting TaskBase and Python inspection task system; many inspection tasks migrated from YAML to Python implementation, maintaining behavior consistent with V4.0.0, and supporting flexible execution through obdiag check run options such as --observer_tasks/--obproxy_tasks. / 检查框架由 checker 重构为 check，采用 TaskBase 与 Python 巡检任务体系；大量巡检任务由 YAML 迁移为 Python 实现，行为与 V4.0.0 保持一致，并支持通过 obdiag check run 的 --observer_tasks/--obproxy_tasks 等选项灵活执行。

Installation and Build / 安装与构建

• 【变更】V4.1.0 continues to use pyproject.toml for dependency management and build. / V4.1.0 持续使用 pyproject.toml 管理依赖与构建。

• 【优化】Optimized build timestamp precision display. / 优化构建时间戳精度显示。

• 【优化】Improved network configuration and error handling mechanisms. / 改进网络配置和错误处理机制。

Dependency Changes / 依赖变更

• 【变更】Updated dependency: pynacl upgraded from 1.5.0 to 1.6.2. / 更新依赖：pynacl 从 1.5.0 升级至 1.6.2。

Notes / 注意

1. The plan_monitor histogram statistics feature requires OceanBase 4.0.0.0 and above. / plan_monitor 直方图统计功能需要 OceanBase 4.0.0.0 及以上版本。

2. OBD adaptation for obdiag V4.1.0 requires V3.5.0 and above. / obd 适配 obdiag V4.1.0 版本需要 V3.5.0 及以上版本。

Full Changelog: v4.0.0...v4.1.0

v4.0.0

obdiag V4.0.0

版本信息

• 发布时间：2025 年 12 月
• 版本号：V4.0.0

新版本变更功能点

新增命令

• 【新增】obdiag tool ai_assistant 命令，AI 智能诊断助手（BETA 版本），支持通过自然语言进行诊断交互。需要配置 OpenAI API Key 或兼容接口。

• 【新增】obdiag tool io_performance 命令，磁盘 IO 性能检测工具，支持检测 clog 盘和 data 盘的 IO 性能。

• 【新增】obdiag tool config_check 命令，配置校验工具，支持检查 DB 连接和 SSH 连接状态，可定位具体失败节点。

• 【新增】obdiag display scene run --scene=observer.compaction 命令，合并状态展示场景，支持展示合并状态、进度、诊断信息和建议。

新增 RCA 场景

• 【新增】obdiag rca run --scene=gc_troubleshooting 命令，GC 问题排查场景（仅支持 OceanBase 4.x）。

• 【新增】obdiag rca run --scene=schema_leak 命令，Schema 泄漏排查场景（仅支持 OceanBase 4.x）。

• 【新增】obdiag rca run --scene=split_schedule_error 命令，分区分裂调度错误排查场景。

• 【新增】obdiag rca run --scene=weak_read_troubleshooting 命令，弱读问题排查场景（仅支持 OceanBase 4.x）。

功能增强

• 【新增】obdiag gather log 和 obdiag gather obproxy_log 命令新增 --recent_count 参数，支持仅收集最近指定数量的日志文件。

• 【新增】obdiag gather ash 命令新增 --svr_ip、--svr_port、--tenant_id 参数，支持按指定条件过滤采样数据（仅支持 OceanBase 4.3.5.0 及以上版本）。

• 【新增】obdiag analyze index_space 命令新增 --database 参数，支持指定数据库进行索引空间分析。

• 【新增】obdiag check run 命令新增 deep 巡检包，用于深度巡检（可能影响系统性能，生产环境慎用）。

• 【新增】obdiag check run 命令新增 archive.archive_continuous_error 巡检项，检查归档连续错误。

• 【优化】obdiag rca run --scene=suspend_transaction 场景支持按 tx_id 分析特定事务。

• 【优化】obdiag rca run --scene=lock_conflict 场景新增日志分析能力。

• 【优化】obdiag rca run --scene=major_hold 场景增加重复索引名检测和 DDL 任务状态检查。

• 【优化】事务相关 RCA 场景（transaction_not_ending、transaction_disconnection、transaction_execute_timeout、transaction_wait_timeout、transaction_rollback、transaction_other_error）诊断能力增强。

• 【变更】obdiag gather plan_monitor、obdiag gather scene run、obdiag gather dbms_xplan 命令 --env 参数改为支持多次指定 key=value 格式，例如：--env host=127.0.0.1 --env port=2881 --env user=test@test --env password=****** --env database=test。

• 【变更】obdiag gather log 命令底层日志搜索算法升级至 v2 版本。

依赖变更

• 【变更】新增依赖：openai>=1.0.0、rich>=13.0.0。

• 【变更】移除依赖：bcrypt、constant、protobuf、pick、subprocess32、netifaces、zstandard、pycryptodome。

注意

1. AI 智能诊断助手功能为 BETA 版本，需要配置 OpenAI API Key 或兼容接口。

2. ASH 报告新参数（svr_ip、svr_port、tenant_id）仅支持 OceanBase 4.3.5.0 及以上版本。

3. 新增的 RCA 场景（gc_troubleshooting、schema_leak、weak_read_troubleshooting）仅支持 OceanBase 4.x。

4. deep 巡检包包含可能影响系统性能的检查任务，生产环境慎用。

注意

obd 适配 obdiag V3.7.2 版本需要 V3.5.0 及以上版本。

Full Changelog: v3.7.2...v4.0.0

v3.7.2

obdiag V3.7.2

版本信息

• 发布时间：2025 年 11 月 27 日
• 版本号：V3.7.2

新版本变更功能点

• 【新增】obdiag check run 命令新增 5 个巡检项。

注意

obd 适配 obdiag V3.7.2 版本需要 V3.5.0 及以上版本。

特别鸣谢：@wayyoungboy @Teingi 对本次迭代做出的贡献

v3.7.1

obdiag V3.7.1

版本信息

• 发布时间：2025 年 10 月 22 日
• 版本号：V3.7.1

新版本变更功能点

• 【新增】obdiag check run 命令新增 1 个巡检项。

• 【新增】obdiag check run --observer_tasks="xxx,xxxx" 支持更细粒度的巡检项组合。

• 【修复】obdiag gather plan_monitor 报告中 SQL 文本复制粘贴后格式错乱问题。

注意

obd 适配 obdiag V3.7.1 版本需要 V3.5.0 及以上版本。

特别鸣谢：@wayyoungboy @Teingi 对本次迭代做出的贡献

v3.7.0

obdiag V3.7.0

版本信息

• 发布时间：2025 年 09 月 09 日
• 版本号：V3.7.0

新版本变更功能点

• 【新增】obdiag-mcp server 发布 wheel 包（ 支持 pip install obdiag-mcp 直接安装），具体使用文档参见 obdiag_mcp_server。

• 【新增】obdiag check run 新增 2 个巡检项。

• 【新增】obdiag gather plan_minitor 支持收集 PS SQL 的 plan_minitor 报告。

• 【修复】obdiag analyze queue --config 参数缺失的问题。

• 【修复】修复若干根因分析场景的小问题。

注意

obd 适配 obdiag V3.7.0 版本需要 V3.5.0 及以上版本。

特别鸣谢：@wayyoungboy @Teingi @xiaodong-ji @suyestyle 对本次迭代做出的贡献

Full Changelog: v3.6.0...v3.7.0

v3.6.0

obdiag V3.6.0

版本信息

• 发布时间：2025 年 07 月 31 日
• 版本号：V3.6.0

新版本变更功能点

• 【新增】obdiag 的 MCP 服务可供大模型调用，具体使用文档参见 obdiag_mcp_server。

• 【新增】新增 obdiag gather core 命令支持 core 文件一键收集功能，具体介绍可参见 Core 文件收集。

• 【新增】obdiag gather scene run 命令新增 obproxy.obproxy_parameter 场景，用于一键收集 ODP 的参数。

• 【新增】obdiag 新增 Docker 镜像 quay.io/oceanbase/obdiag:latest。

• 【新增】obdiag 输出结果支持 markdown 样式。

• 【新增】新增 obdiag tool 一级命令用于集成其他工具，并新增 obdiag tool crypto_config 命令支持将 obdiag 配置文件加密，具体介绍可参见 配置文件加密。

• 【新增】obdiag rca run 命令新增 OceanBase 集群回放卡的根因分析场景。

• 【新增】obdiag rca run 命令新增 OceanBase 集群内存爆的根因分析场景。

• 【新增】obdiag rca run 命令新增 OBServer 节点删除异常的根因分析场景。

• 【新增】obdiag check run 新增 8 个巡检项。

注意

obd 适配 obdiag V3.6.0 版本需要 V3.2.0 及以上版本。

特别鸣谢：@wayyoungboy @Teingi @xiaodong-ji 对本次迭代做出的贡献

v3.5.0

obdiag V3.5.0

版本信息

• 发布时间：2025 年 06 月 20 日
• 版本号：V3.5.0

新版本变更功能点

• 【新增】新增 10 个巡检项：集群网卡速度不一致、Local IP 不正确、MemStore 使用率过高、集群无主、会话过多、租户存在锁冲突、数据盘满、租户存在空洞、日志流副本数不足、引用计数泄漏。

• 【新增】obdiag rca run 命令新增 Unit GC 异常的根因分析场景。

• 【新增】obdiag gather scene run --scene=observer.cpu_high 命令新增 processlist 的信息采集。

• 【修复】修复 obdiag gather dbms_xplan 命令中 DBMS_XPLAN.DISPLAY_CURSOR 不准确的问题。

• 【修复】日志收集获取文本时间异常的问题。

• 【修复】修复 obdiag gather plan_minitor 命令生成的报告文件过大问题，并为该命令增加统计信息过期校验逻辑。

• 【变更】（开发者侧）开发环境升级 python >= 3.11。

注意

obd 适配 obdiag V3.5.0 版本需要 V3.2.0 及以上版本。

特别鸣谢：@wayyoungboy @Teingi @duzp111 @CES-dengzeyuan 对本迭代所做出的贡献