obdiag-usage

name: obdiag-usage description: obdiag agent 工具使用指南：配置文件生成、gather/analyze/check/rca 各命令的调用方式、参数说明与典型场景。用户询问"怎么用 obdiag"、"如何采集日志"、"怎么生成配置"、"如何巡检/根因分析"，或 agent 自身不确定该调哪个工具时加载本 skill。

obdiag Agent 工具使用指南

一、配置文件生成（generate_obdiag_config）

触发：用户尚无 ~/.obdiag/config.yml，或明确要求生成/更新配置。

必填参数

常用可选参数

行动原则

1. 用户未提供必填项时，逐一追问，不要猜测。
2. 已有 config.yml 时，工具会自动备份为 config.yml.backup_<timestamp>。
3. 生成后用 list_obdiag_clusters 确认写入成功，再继续诊断。

示例

generate_obdiag_config(
    ob_cluster_name="prod-cluster",
    db_host="10.0.0.1",
    tenant_sys_password="",
    nodes=[{"ip": "10.0.0.1"}, {"ip": "10.0.0.2"}, {"ip": "10.0.0.3"}],
    global_ssh_username="admin",
    global_home_path="/home/admin/oceanbase"
)

二、多集群管理

所有 gather/analyze/check/rca 工具均支持 cluster_config_path 参数（传短名如 "test-cluster" 或完整路径），用于切换到非默认集群。

三、Gather 采集工具

采集完成后，工具输出中会包含 obdiag_gather_pack_* 打包目录路径。 若用户同时要求分析，在同一轮内继续对该目录执行 file_list → file_read → 总结。

3.1 gather_log — 集群侧日志（observer/election/rootservice）

仅用于 OceanBase 节点侧，不用于 OBProxy 或 OMS。

gather_log(since="30m", scope="observer", grep="ERROR")
gather_log(from_time="2024-01-01 10:00:00", to_time="2024-01-01 11:00:00", grep=["trace_id_xxx"])

3.2 gather_obproxy_log — OBProxy 日志

仅用于 OBProxy 节点，不用于 observer。

3.3 gather_oms_log — OMS 组件日志

需要 config.yml 中存在 oms 段，否则报错。

3.4 gather_sysstat — 系统资源快照

采集各节点 CPU、内存、磁盘、网络等系统指标，无时间范围参数。

gather_sysstat()
gather_sysstat(store_dir="/tmp/sysstat_out")

3.5 gather_perf — 性能剖析（火焰图/pstack）

采集实时性能数据，适用于高 CPU/卡顿场景。无额外必填参数。

gather_perf()

3.6 gather_ash — 活跃会话历史（ASH）

3.7 gather_awr — AWR 报告

3.8 gather_plan_monitor — SQL 执行计划监控

仅用于采集指定 trace_id 的执行计划，不用于"收集日志"。收日志请用 gather_log(grep=trace_id)。

gather_plan_monitor(trace_id="Y123456789-0001")

四、Analyze 分析工具

analyze_log — 集群侧日志分析

仅支持 observer/election/rootservice，不支持 OBProxy 和 OMS 日志。

典型用法：先 gather_log 得到 pack 目录，再 analyze_log 做统计分析，最后 file_read 读原始行级内容。

analyze_log(scope="observer", from_time="2024-01-01 10:00:00", to_time="2024-01-01 11:00:00")
analyze_log(files=["/tmp/obdiag_gather_pack_xxx/observer.log"], log_level="ERROR")

五、Check 巡检工具

5.1 check_list — 列出可用巡检项

在执行 check 前，可先调用 check_list 了解有哪些巡检任务。

check_list()

5.2 check_cluster — 执行巡检

所有参数均省略 → 加载全部任务，排除 filter 套餐中的项，执行完整默认巡检套件。

check_cluster()                                              # 全量巡检（排除 filter 套餐）
check_cluster(cases="k8s_basic")                            # 跑 k8s_basic 套餐中的所有任务
check_cluster(observer_tasks="cluster.*")                   # 只跑 cluster 目录下所有任务（正则匹配）
check_cluster(observer_tasks="disk.data_disk_full;cluster.no_leader")  # 指定多个任务（分号分隔）
check_cluster(cases="k8s_basic", cluster_config_path="prod")           # 指定非默认集群

六、RCA 根因分析

6.1 rca_list — 列出 RCA 场景

rca_list()

6.2 rca_run — 执行 RCA

注意：agent 工具 rca_run 不支持 --env 参数。部分 scene 在 CLI 层需要 --env，通过 agent 调用时直接传 scene 即可；若因缺少 env 参数导致失败，进入 obdiag-rca 手动降级步骤。

rca_run(scene="disconnection")
rca_run(scene="major_hold")

行动原则：

1. 用户描述故障症状时，加载 obdiag-rca skill，按其"场景速查表"将症状（如"合并卡住"、"断连"、"OOM"）映射到正确 scene 名称；再调 rca_run。
2. 不确定 scene 时可先调 rca_list 确认 scene 在当前环境中可用。
3. rca_run 无结论时，按 obdiag-rca 的手动降级步骤继续分析，不要直接告知用户"无法定位"。
4. 完全无匹配场景时，转向 gather_log + analyze_log 手动排查。

七、辅助工具

tool_io_performance — 磁盘 IO 检测

tool_io_performance(disk="sda")          # 检测 sda 盘
tool_io_performance(disk="data")         # 检测 data 盘
tool_io_performance(date="20240101")     # 查历史数据

tool_sql_syntax — SQL 语法/语义检验

使用 EXPLAIN 验证，不实际执行 SQL。

tool_sql_syntax(sql="SELECT * FROM t1 WHERE id = 1")
tool_sql_syntax(sql="SELECT * FROM t1", env=["host=10.0.0.1", "port=2881"])

八、工具选择速查表

九、通用行动原则

1. 配置优先：调任何 gather/analyze/check/rca 前，先确认 show_current_cluster 返回有效路径；无效则引导用户生成配置。
2. 采集+分析链式：用户同时要求"采集+分析"时，在同一轮内完成：gather → file_list → file_read/analyze_log → 总结，不得仅 gather 后停止。
3. 日志边界严守：analyze_log 仅用于 observer 侧；OBProxy 日志用 gather_obproxy_log 后 file_read；OMS 日志用 gather_oms_log 后 file_read。
4. 时间窗默认值：用户未指定时间时默认 since="30m"，或询问用户。
5. 零命中处理：analyze_log 或 file_read 无匹配时，不要回复"未发现问题"——建议扩大 since、去掉 grep 过滤或换 scope。
6. 只读原则：db_query 仅执行只读 SQL；涉及 ALTER SYSTEM 等变更时，输出建议 SQL 由 DBA 手工执行。