一键集群巡检 - 敏捷诊断工具 V2.3.0

一键集群巡检

更新时间：2026-04-15 12:36:08

本文适用于独立部署 obdiag 的场景，使用 obdiag check run 命令可帮助 OceanBase 数据库集群相关状态巡检，目前支持从系统内核参数、内部表等方式对 OceanBase 的集群进行分析，发现已存在或可能会导致集群出现异常问题的原因分析并提供运维建议。

前提条件

说明

需要确保已经在 obdiag 配置文件 config.yml 中配置好需要收集节点的登录信息。相关的详细配置介绍，参见 obdiag 配置。

check 命令组

总览

# 列出所有巡检套餐
obdiag check list

# 全量巡检 (最常用)
obdiag check run

# 列存POC检查
obdiag check run --cases=column_storage_poc

# obproxy 版本检查
obdiag check run --obproxy_cases=proxy

# 部署环境检查
obdiag check run --cases=build_before

# 执行 sysbench 时的巡检任务集合
obdiag check run --cases=sysbench_run

# 执行 sysbench 前的巡检任务集合
obdiag check run --cases=sysbench_free

语法

obdiag check run [options]

options 说明：

选项名	是否必选	数据类型	默认值	说明
--cases	否	string	``	需要执行的observer巡检项目的集合名。当未赋值时执行所有的 tasks。
--obproxy_cases	否	string	``	需要执行的obproxy巡检项目的集合名。当未赋值时执行所有的 tasks。
-c	否	string	`~/.obdiag/config.yml`	配置文件路径
--report_type	否	string	table	巡检报告的输出格式，目前支持table, json, xml, yaml

示例如下：

obdiag check run

'cat ./check_report/check_report_2023-10-30-16:15:52.table', export type is table
For more details, please run cmd 'cat ./check_report/check_report_2023-10-30-16:15:52.table'
If you want to view detailed obdiag logs, please run:'obdiag display-trace --trace_id a7674ecb-0d99-36fe-b584-3b707b4647bc'

task 编写教程

task 是一个独立的巡检场景，可以理解为一个专业的，用 yaml 编写的，用 obdiag 识别的脚本文件。

task 会包含一些用于巡检的前置声明，用于实现对 OceanBase 进行更为专业的巡检。

开始编写前

在编写 test.yaml 文件前，需要先确认 test.yaml 文件的存放位置。

test.yaml 文件必须存放在 config.yml 文件中设置的 CHECK.tasks_base_path 所标识的目录内，在该目录下，分析编写的巡检场景是否属于已有的大类，若没有则创建一个文件夹用于声明这个大类。

例：

#先进入${CHECK.tasks_base_path}/observer，然后创建一个文件夹 test，并创建示例文件 test.yaml
cd ~/.obdiag/check/tasks/observer
mkdir test
cd test
touch test.yaml

编写 task 脚本

task 的作用是声明巡检执行的步骤，其基础结构是一个 list，用于兼容不同版本可能导致步骤的出入或者该巡检项目无法使用。

task 文件的示例如下：

info: testinfo
task:
  - version: "[3.1.0,3.2.4]"
    steps:
      {steps_object}
  - version: "[4.2.0.0,4.3.0.0]"
    steps:
      {steps_object}

参数说明：

参数名	是否必填	描述
info	是	声明这个 yaml 使用的场景，方便维护。
version	否	表示适用的版本，用 Str 的形式表示范围，需要完整的数字的版本号。 OceanBase 数据库 V3.x 版本为三位，例如 [3.1.1,3.2.0]。 OceanBase 数据库 V4.x 版本为四位，例如：[4.1.0.0,4.2.0.0]。
steps	是	所执行步骤，为 list 结构。

steps 介绍

steps 也是一个 list，用来表示具体的多个执行流程。

steps 的一个元素的结构即单个流程，如下

参数名	是否必填
type	是	表示适用的执行类型，目前支持 `get_system_parameter`/ `ssh`/`sql`。
{parameter_name/ssh/sql}	是	根据所选的类型提供的参数，这块比较依赖代码里的对执行类型的逻辑说明。
result	否	结构为一个单独的对象，用于对这个步骤结束后需要进行的操作进行解析，如校验结果逻辑，逻辑不通过时需要报错的文本信息进行说明等等。具体可参考 `result & verify 功能`

各种类型示例如下，step: 仅为一个标记，无实际作用。

get_system_parameter

steps:
- type: get_system_parameter
  parameter: parameter
  result:
    set_value: servervm.max_map_count

ssh 远程执行指令并获取对应的返回值

steps:
- type: ssh
  ssh: wc -l /proc/${task_OBServer_pid}/maps | awk '{print $1}'
  result:
    set_value: observerMaps

sql 执行 SQL 并获取对应的值。

steps:
- type: sql
  sql: select tenant_name from oceanbase.table_name from where tenant_id=${taskTenantId};
  result:
    set_value: tenant_name

result & verify 功能

这个字段也是 verify 功能的主要依赖字段，用于对 task 获取结果的验证。

其格式如下：

result:
      set_value: {set_value}
      verify_type: {verify_type}
      report_type: {report_type}
      verify: {verify}
      err_msg: {err_msg}

参数说明：

参数名	是否必填	描述
set_value	否	将执行后的值赋值,作为一个适用于整个 task 的变量，例如`set_value: max_map_count`
verify_type	否	用于设置验证的方式，默认为 base，一般需要和 `verify`联动，base 即为通过 `verify`的表达式进行验证，输出结果为 `true`或 `false`，同时提供了以下常见的判断类型，减少编写量。
verify	否	服务于 verify_type，用于验证执行结果是否符合预期，若不符合，会输出 `err_msg`部分的信息。
report_type	否	用于设置本步骤若出现 `verify`为 `false`需要执行的告警级别，默认告警级别为 `critical`。
err_msg	否	用于非正常执行时答应的日志，支持配置全局变量，在 `verify`为 `false`的时候所输出的 msg 建议配置了 `verify`，就一定要配上 `err_msg`。

**verify_type**** 支持的类型：**

目前 verify_type 支持的类型，除了 base 外的类型仅适用于 int 类型。

between：判断 set_value 的值是否在 verify 提供的范围内。
max：判断 set_value 的值是否小于 verify 提供的值。
min：判断 set_value 的值是否大于 verify 提供的值。
equal：判断 set_value 的值是否等于 verify 提供的值。

关于 base 的说明

verify 表达式会用于替换如下 shell 式子中的 new_expr 内进行执行验证，在编写 verify 时可以手动在本地进行逻辑验证。

if ${new_expr}; then
    echo "true"
else
    echo "false"
fi

编写 package 脚本

package 脚本目前包含observer_check_pakage.yaml和obproxy_check_package.yaml，分别对应 observer 和 proxy 的巡检包。

package本身的结构是一个大的dict，结构如下

{case_name}:
  info_en: "" # 对这个package英文解释
  info_cn: "" # 对这个package中文解释
  tasks:
    {tasks_names} # 一个list结构，用于元素为一个或多个task的名称

package 脚本编写完成后可以通过 obdiag check list 命令查看当前可用的 case 列表。

关于 task 的手动更新

为了更好地提供更有效的检测项任务，我们会不定时更新 task 的数量和质量，用户可以在 obdiag 的代码仓库中复制 ${code_path}/handler/check/tasks 文件夹来替换原有文件夹 ~/.obdiag/check/tasks，同时需要的还有 *check_package.yaml(~/.obdiag/check/*check_package.yaml)，用于更新对应的巡检套餐。