---
title: "总览 - 敏捷诊断工具 V2.4.0 | OceanBase 文档中心"
description: 总览 本文适用于独立部署 obdiag 的场景，使用 obdiag gather 命令可帮助 OceanBase 数据库相关的诊断信息收集。gather scenes 命令可以一键执行将某些问题场景所需要的排查信息统一捞回，解决分布式节点信息捞取难的痛点。 前提条件 需要确保已经在 obdiag 配置文件 confi…
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*5ZXST55u540AAAAAAAAAAAAADiGDAQ/original) 敏捷诊断工具V 2.4.0

# 总览

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

[编辑](https://github.com/oceanbase/odt-doc/edit/V2.4.0/zh-CN/400.gather/200.scenes/201.obdiag-gather-scene-guide.md)  

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

## 前提条件

需要确保已经在 obdiag 配置文件 `config.yml` 中配置好需要收集节点的登录信息。相关的详细配置介绍，参见 [obdiag 配置](https://www.oceanbase.com/docs/common-obdiag-cn-1000000001326824)。

## 查看当前支持的场景

```shell
obdiag gather scene list

```

## obdiag gather scene run 使用

```shell
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 配置](https://www.oceanbase.com/docs/common-obdiag-cn-1000000001326824)。

```bash
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 配置](https://www.oceanbase.com/docs/common-obdiag-cn-1000000001326824)。

```bash
obdiag gather scene run --scene={SceneName}

```

## 自定义场景编写教程

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

### 开始编写前

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

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

例：

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

```

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

### 开始编写

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

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

info: "for test"

```

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

#### 场景编写

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

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

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

如下就是一个示例：

```yaml
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

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

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

```

##### sql

执行sql并获取对应的值

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

```

##### log

收集 OceanBase 数据库的日志

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

```

##### obproxy_log

收集 OBProxy 的日志

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

```

##### sysstat

收集主机的信息

```yaml
step:
 type: sysstat
 sysstat: ""
 global: false

```

#### 说明

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

  上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线