总览 - 敏捷诊断工具 V2.4.0 | OceanBase 文档中心

总览

更新时间：2026-04-13 17:11:17

本文适用于独立部署 obdiag 的场景，使用 obdiag gather 命令可帮助 OceanBase 数据库相关的诊断信息收集。gather scenes 命令可以一键执行将某些问题场景所需要的排查信息统一捞回，解决分布式节点信息捞取难的痛点。

前提条件

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

查看当前支持的场景

obdiag gather scene list

obdiag gather scene run 使用

obdiag gather scene run --scene={SceneName}

选项说明如下：

选项名	是否必选	数据类型	默认值	说明
--scene	是	string	默认为空	场景名，可以通过obdiag gather scene list 查看当前版本支持哪些场景
--from	否	string	默认为空	日志收集的开始时间，格式为: `yyyy-mm-dd hh:mm:ss`。说明若使用的 obdiag 为 V2.0.0 之前版本，配置该选项时无需加引号，否则会报错。V2.0.0 及之后版本不再限制配置该选项时是否加引号。
--to	否	string	默认为空	日志收集的结束时间，格式为: `yyyy-mm-dd hh:mm:ss`。说明若使用的 obdiag 为 V2.0.0 之前版本，配置该选项时无需加引号，否则会报错。V2.0.0 及之后版本不再限制配置该选项时是否加引号。
--since	否	string	默认为空	日志收集最近的某段时间，格式为: `<n> <m\|h\|d>`，其中，n 表示待输入的时间数字，m 表示分钟，h 表示小时，d 表示天，例如 `30m` 表示收集最近 30 分钟的日志。
--env	否	string	默认为空	部分场景需要额外的参数才能支持，统一放到了 --env 这个参数里边
--store_dir	否	string	默认为命令执行的当前路径	存储结果的本地路径。
--temp_dir	否	string	`/tmp`	远端节点在日志收集过程中产生的临时文件存储目录
-c	否	string	`~/.obdiag/config.yml`	配置文件路径。
--inner_config	否	string	默认为空	obdiag 自用的配置。
--config	否	string	默认为空	obdiag 被诊断集群的配置，固定样式：--config key1=value1 --config key2=value2。

说明

如果不特别指定存储目录 store_dir ，收集的结果会存放在当前目录下 gather_pack_xxxx 的文件夹中

使用示例

方式一：无配置文件使用（开箱即用）

说明

本节命令中使用的详细配置介绍可参见 obdiag 配置。

obdiag gather scene run --scene={SceneName} \
    --config db_host=xx.xx.xx.xx \
    --config db_port=xxxx \
    --config tenant_sys.user=root@sys \
    --config tenant_sys.password=*** \
    --config obcluster.servers.nodes[0].ip=xx.xx.xx.1 \
    --config obcluster.servers.nodes[1].ip=xx.xx.xx.xx.2 \
    --config obcluster.servers.nodes[2].ip=xx.xx.xx.xx.3 \
    --config obcluster.servers.global.ssh_username=test \
    --config obcluster.servers.global.ssh_password=****** \
    --config obcluster.servers.global.home_path=/home/admin/oceanbase \
    --config obproxy.servers.nodes[0].ip=xx.xx.xx.3 \
    --config obproxy.servers.nodes[1].ip=xx.xx.xx.xx.4 \
    --config obproxy.servers.global.ssh_username=test \
    --config obproxy.servers.global.ssh_password=****** \
    --config obproxy.servers.global.home_path=/home/admin/obproxy

方式二：有配置文件使用

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

obdiag gather scene run --scene={SceneName}

自定义场景编写教程

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

开始编写前

编写前需要确定yaml需要放在哪

可以先进入 /usr/local/oceanbase-diagnostic-tool/conf/inner_config.yml 文件中设置 gather.scenes_base_path 所标识的目录里，看下编写的采集场景是否属于已有的大类，若没有就创建一个文件夹用于声明这个大类

例：

#先进入 ${gather.scenes_base_path} ,并创建我们的示例文件 test.yaml (以 observer 为测试目标)
cd ~/.obdiag/gather/tasks/observer
touch test.yaml

以上便完成了编写前的步骤

开始编写

开始编写就是开始编辑我们的 test.yaml

# 首先需要声明下这个场景的作用，为了让大家看得懂

info: "for test"

简单的内容已经结束，开始复杂的编写，注意细节

场景编写

task 的作用是声明场景采集执行的步骤，为了兼容不同版本可能导致的步骤的不同，其基础结构是一个 list。

task 的一个元素的结构如下：

参数名	是否必填	说明	数据类型
version	否	表示适用的版本，使用方式见下示例	用 str 的形式表示范围，需要完整的数字的版本号，3.x 版本为三位，4.x 版本为四位如：[3.1.1,3.2.0]，版本支持遵循左开又闭的原则
steps	是	所执行步骤	为 list 结构

如下就是一个示例：

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}

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

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

参数名	是否必填	说明
type	是	表示适用的执行类型，目前支持 ssh/sql/log/obproxy_log/sysstat, 后续会持续增加支持的类型
{ssh/sql/log/obproxy_log/sysstat}	是	根据所选的类型提供的参数，这块比较依赖代码里的对执行类型的逻辑说明，本章节后续会对支持的进行类型进行详细的使用说明

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

ssh

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

step:
  type: ssh
  ssh: wc -l /proc/${task_OBServer_pid}/maps | awk '{print $1}'
  global: false # 此处的全局字段是相对于节点来说的，标记为true的时候只会在第一个节点执行的时候执行一次，如果标记为false则会在每个节点进行执行

sql

执行sql并获取对应的值

step:
 type: sql
 sql: select tenant_name from oceanbase.__all_tenant;
 global: false

log

收集 OceanBase 数据库的日志

step:
 type: log
 grep: "" # 过滤字段
 global: false

obproxy_log

收集 OBProxy 的日志

step:
 type: obproxy_log
 grep: "" # 过滤字段
 global: false

sysstat

收集主机的信息

step:
 type: sysstat
 sysstat: ""
 global: false

说明

global 字段是相对于节点来说的，标记为 true 的时候只会在第一个节点执行的时候执行一次，如果标记为 false 则会在每个节点进行执行