防患未然，OceanBase巡检工具应用实践——《OceanBase诊断系列》之五

1. OceanBase为什么要做巡检功能

尽管OceanBase拥有很好的MySQL兼容性，但在长期的生产环境中，部署不符合标准规范、硬件支持异常，或配置项错误等问题，这些短期不会出现的问题，仍会对数据库集群构成潜在的巨大风险。为了解决这类挑战，OceanBase诊断工具增加了巡检子功能，该功能能够结合过去解决问题的经验，对OceanBase集群进行全面的健康检查，并对存在的或潜在的问题进行提前预警。我们必须防患于未然！

2. 怎么做巡检

已经知道了为什么做，怎么去实现巡检的能力？这是个很现实的工程落地问题，考虑到诊断工具本身就是开源项目，OceanBase社区的同学们也很热情，我们也希望大家可以参与进来，因此设定了两个需求条件：

1. 高可扩展，要给用户更高的参与自由度；
2. 高兼容性，可以适配OceanBase的多个版本；
3. 便捷使用，尽可能少的输入参数

设计的巡检功能架构如下：

用户首先需要完成前置的集群配置（在搭配OBD/OCP使用的时候可以更为便捷），以获取到需要进行巡检的集群信息。然后执行巡检即可，obdiag会根据预设的巡检项目对集群进行检查。从用户的角度看，在完成巡检后会输出对应的巡检报告到指定的路径，若都为pass，那就代表目前未发现存在预设隐患的问题，集群还是相对健康的。

3. 怎么使用巡检功能

使用巡检功能的前提是需要一套正在运行的OceanBase集群（单机/集群均可，也可复用obd/ocp所部署的集群）。

3.1. 独立通过obdiag进行使用

3.1.1. 下载&安装&升级obdiag

注：需确认obdiag 1.4版本以上才支持巡检功能

3.1.1.1. 官网下载安装

进入OceanBase分布式数据库-海量数据 笔笔算数 ，根据用户使用的平台选择对应的RPM包

sudo rpm -ivh oceanbase-diagnostic-tool-XXXX.rpm
source /usr/local/oceanbase-diagnostic-tool/init.sh

3.1.1.2. RPM obdiag升级

请注意：升级后配置文件将会被重置，需要重新配置/usr/local/oceanbase-diagnostic-tool/conf/config.yml

sudo rpm -Uvh oceanbase-diagnostic-tool-XXXX.rpm
source /usr/local/oceanbase-diagnostic-tool/init.sh

3.1.1.3. yum源安装

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://mirrors.aliyun.com/oceanbase/OceanBase.repo
sudo yum install -y oceanbase-diagnostic-tool
source /usr/local/oceanbase-diagnostic-tool/init.sh

3.1.2. 配置obdiag

注：

一下配置详解以最新版本的obdiag（1.5.0）进行描述。

配置文件示例位于~/.obdiag/example/

all-components.yaml # 全量检测示例
docker_ob_cluster.yml # 安装于docker的observer示例
ob_cluster.yml # 仅检测observer的示例
obproxy.yml  # 仅检测obproxy的示例

本文选择全量检测示例作为示例

cd ~/.obdiag/
cp ./example/all-components.yaml ./config.yml
vim ~/.obdiag/config.yml

主要需要自行更改的就是OBCLUSTER和NODES，OBCLUSTER是集群的信息，NODES是部署集群所在节点的登录信息，由于需要进行远程执行信息采集（obdiag本身为离线工具，采集的信息不会进行上传）所以需要进行相关的信息配置。

ocp:
  login:
    url: http://192.168.1.100:8080
    user: admin
    password: admin
obcluster:
  ob_cluster_name: test
  db_host: 192.168.1.1
  db_port: 2881 # default 2881
  tenant_sys:
    user: root@sys # default root@sys
    password: ""
  servers:
    nodes:
      - ip: 192.168.1.1
      - ip: 192.168.1.2
      - ip: 192.168.1.3
    global:
      ssh_username: admin # your username
      ssh_password: admin # password if need
      # ssh_port: 22 # your ssh port, default 22
      # ssh_key_file: "" # your ssh-key file path if need
      # ssh_type: remote # ssh_type choice [remote, docker, kube] default remote
      # container_name: xxx # container_name for ssh_type is docker
      # The directory for oceanbase installed
      home_path: /root/observer
      # The directory for data storage. The default value is $home_path/store.
      # data_dir: /root/observer/store 
      # The directory for clog, ilog, and slog. The default value is the same as the data_dir value.
      # redo_dir: /root/observer/store
obproxy:
  obproxy_cluster_name: obproxy
  servers:
    nodes:
      - ip: 192.168.1.4
      - ip: 192.168.1.5
      - ip: 192.168.1.6
    global:
      ssh_username: admin # your username
      ssh_password: admin # password if need
      # ssh_port: 22 # your ssh port, default 22
      # ssh_key_file: "" # your ssh-key file path if need
      # ssh_type: remote # ssh_type choice [remote, docker, kube] default remote
      # container_name: xxx # container_name for ssh_type is docker
      # The directory for obproxy installed
      home_path: /root/obproxy

3.1.3. 运行巡检项目

接下来可以对OceanBase集群进行巡检了

obdiag check

在某些时候，可以巡检特定的巡检项目，以避免由于查询动作对集群增加负担

obdiag check --cases=XXXX

这里的XXXX是位于配置文件中${CHECK.package_file}中的套餐名，套餐本身是一个list会维护在指定情况下执行的巡检项目集合。这个套餐支持自定义用户可以自行修改。

注：由于task的灵活性，我们将会在代码仓库中不定时更新和优化巡检项及巡检套餐，用户可以自行在仓库下载{code}/check_package.yaml和{code}/handler/checker/tasks，分别覆盖本地的~/.obdiag/check_package.yaml和~/.obdiag/tasks

# 更新脚本如下，需要有连接外网权限
# 用于更新tasks
curl https://codeload.github.com/oceanbase/oceanbase-diagnostic-tool/tar.gz/master | tar -xz -C ~/.obdiag/ --strip=3 oceanbase-diagnostic-tool-master/handler/checker/tasks
# 用于更新套餐包信息，注意这个更新会覆盖原有的套餐文件,原文件会被转移至 ~/.obdiag/check_package.yaml.old
cp ~/.obdiag/check_package.yaml ~/.obdiag/check_package.yaml.old && curl https://codeload.github.com/oceanbase/oceanbase-diagnostic-tool/tar.gz/master | tar -xz -C  ~/.obdiag/ --strip=1 oceanbase-diagnostic-tool-master/check_package.yaml

3.1.4. 获取&查看巡检报告

在完成巡检后会输出一个cat命令，复制执行即可获取对应的体检报告啦

3.2. 通过obd进行调度使用

注：

obd2.4.0版本开始支持obdiag1.4版本；

预计obd2.5.0版本开始支持obdiag1.5版本。

详见obdiag&obd的release note。

3.2.1. obd中部署obdiag插件

参考3.1.1下载obdiag，并在obd加载obdiag插件

# obd加载obdiag插件
obd mirror clone oceanbase-diagnostic-tool-XXXX.rpm
obd obdiag deploy

3.2.2. obd obdiag执行巡检

与独立通过obdiag使用不同，在obd中使用需要额外加上deploy_name作为集群指定

obd obdiag check ${deploy_cluster_name}

#指定巡检集
obd obdiag check ${deploy_cluster_name}

obd obdiag巡检报告查看与独立使用时一样使用cat进行查看

3.2.3. 独立通过obdiag使用与obd obdiag使用不同点

3.2.3.1. 巡检套餐文件${package_file}文件不同

package_file（保存巡检套餐的文件）强制为obdiag插件安装路径下的/check_package.yaml。例如

~/.obd/repository/oceanbase-diagnostic-tool/1.4.0/8d4b6d8ca87d7843b5508f388206a6c41aa93834/oceanbase-diagnostic-tool/check_package.yaml

3.2.3.2. 巡检项目文件基础路径${tasks_base_path}不同

tasks_base_path（保存巡检项的基础路径）强制为obdiag插件安装路径下的/handler/checker/tasks/。例如

~/.obd/repository/oceanbase-diagnostic-tool/1.4.0/8d4b6d8ca87d7843b5508f388206a6c41aa93834/oceanbase-diagnostic-tool//handler/checker/tasks/

4. 怎么自定义巡检项

在实际生成过程中，用户可能需要有自定义巡检的需求，比如运行下部署observer所在节点某个运维工具，采集些节点网络信息等等。巡检功能为了满足用户的不同程度的自定义开放了巡检项目自定义扩展和step_type扩展。

4.1. 巡检项目自定义（编写task）

巡检项目自定义指用户可以自定义需要巡检的流程、验证、验证后需要执行的措施。这个扩展不需要修改obdiag的代码，仅需要编写一个yaml文件即可实现。

4.1.1. 开始编写前

编写前需要确定我们的这个yaml需要放在哪

可以先进入conf.yml文件中设置CHECK.tasks_base_path所标识的目录里（使用obd进行操作时，此路径为~.obdiag/task），看下分析下编写的巡检场景是否属于已有的大类，若没有就创建一个文件夹用于声明这个大类

例：

#先进入${CHECK.tasks_base_path} ,然后创建一个文件夹test,并创建我们的示例文件test.yaml
cd ./handler/check/tasks/
mkdir test
cd test
touch test.yaml

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

4.1.2. 开始编写

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

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

info: "for test"

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

4.1.2.1. task编写

task的作用是声明巡检执行的步骤，其基础结构是一个list

为什么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 | 是 | 表示适用的执行类型，目前支持get_system_parameter/ssh/sql,后续会持续增加支持的类型 |
| {ssh/sql} | 是 | 根据所选的类型提供的参数，这块比较依赖代码里的对执行类型的逻辑说明，本章节后续会对支持的进行类型进行详细的使用说明 |
| result | 否 | 结构为一个单独的对象，用于对这个步骤结束后需要进行的操作进行解析，如校验结果逻辑，逻辑不通过时需要报错的文本信息进行说明等等。具体本章节后续会进行详细说明 |

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

4.1.2.1.1. get_system_parameter

step:
  type: get_system_parameter
  parameter_name: parameter
  result:
    set_value: servervm.max_map_count

4.1.2.1.2. ssh

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

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

4.1.2.1.3. sql

执行sql并获取对应的值

step:
 type: sql
 sql: select tenant_name from oceanbase.__all_tenant from where tenant_id=${taskTenantId};
 result:
  set_value: tenant_name

4.1.3. result&verify编写

result是对step结果的处理，同时这个字段也是verify功能的主要依赖字段，用于对task获取结果的验证

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

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

between：判断set_value的值是否在verify提供的范围内；cd usr/local/oceanbase-diagnostic-tool && sh init.sh && source ~/.bashrc

max：是否小于verify提供的值

min：是否大于min提供的值

equal：是否等于verify（兼容字符串或int，但是${set_value}和verify必须是同类型）

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

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

以上编写的教程基本就结束了，具体的示例可以看下${obdiag源码路径}/handler/check/tasks/里的示例

4.2. step_type扩展（未完待续）

step_type扩展指当前的step_type无法满足巡检流程操作的时候可以由用户自定义实现一个全新的step_type来实现一个自定义的功能。这个扩展涉及obdiag源码的修改，参与度较高，后续将单独出一个博客进行讲解

|-----|----------------------------------------------------------------|
| 第一篇 | 如何修炼成"神医"------《OceanBase诊断系列》之一 |
| 第二篇 | 走进SQL审计视图------《OceanBase诊断系列》之二 |
| 第三篇 | 一键操作敏捷诊断工具obdiag收集诊断信息实践------《OceanBase诊断系列》之三 |
| 第四篇 | 一键操作敏捷诊断工具obdiag分析OB集群日志设计与实践------《OceanBase诊断系列》之四 |
| 第五篇 | 专为OceanBase打造的巡检工具已推出！给OceanBase进行一次体检吧------《OceanBase诊断系列》之五 |