诊断工具#

概述#

为了方便排查用户环境中的常见问题,OpenMLDB提供了诊断工具。

使用#

安装方式与使用:

pip install openmldb-tool # openmldb-tool[pb]
openmldb_tool # 注意下划线

有以下几个子命令可选择执行:

usage: openmldb_tool [-h] [--helpfull] {status,inspect,rpc,test,static-check} ...

注意-c/--cluster参数,格式为<zk_cluster>/<zk_root_path>,默认将访问127.0.0.1:2181/openmldb。如果是自行设置的OpenMLDB集群,请配置此参数。其他参数根据子命令不同而不同,可以使用-h查看,或查看各个子命令的详细文档。

一键inspect#

openmldb_tool inspect [--cluster=0.0.0.0:2181/openmldb]可以一键查询,得到完整的集群状态报告。如果需要局部视角或额外的诊断功能,才需要其他子命令。

报告分为几个板块,其中如果所有表都是健康的,不会展示Ops和Partitions板块。用户首先看报告末尾的总结 summary & hint,如果存在server offline(红色),需先重启server,保证server尤其是TabletServer都在线。server重启后,集群可能会尝试自动修复,自动修复也可能会失败,所以,用户有必要等待一定时间后再次inspect。此时如果仍然有不健康的表,可以检查它们的状态,Fatal表需要尽快修复,它们可能会读写失败,Warn表,用户可以考虑推迟修复。修复方式见报告末尾提供的文档。

inspect可配置参数除了--cluster/-c,还可配置不显示彩色--nocolor/-noc方便复制,以及--table_width/-tw n配置表格宽度,--offset_diff_thresh/-od n配置offset diff的报警阈值。

diagnosing cluster xxx


Server Detail
{server map}
{server online/offline report}


Table Partitions Detail
tablet server order: {tablet ip -> idx}
{partition tables of unhealthy tables}
Example:
{a detailed description of partition table}


Ops Detail
> failed ops do not mean cluster is unhealthy, just for reference
last one op(check time): {}
last 10 ops != finished:
{op list}



==================
Summary & Hint
==================
Server:

{online | offline servers ['[tablet]xxx'], restart them first}

Table:
{all healthy | unhealthy tables desc}
[]Fatal/Warn table, {read/write may fail or still work}, {repair immediatly or not}
{partition detail: if leader healthy, if has unhealthy replicas, if offset too large, related ops}

    Make sure all servers online, and no ops for the table is running.
    Repair table manually, run recoverdata, check https://openmldb.ai/docs/zh/main/maintain/openmldb_ops.html.
    Check 'Table Partitions Detail' above for detail.

其他常用命令#

除了一键inspect,在这样几个场景中,我们推荐使用诊断工具的子命令来帮助用户判断集群状态、简化运维。

  • 部署好集群后,可以使用test测试集群是否能正常工作,不需要用户手动测试。如果发现问题,再使用inspect诊断。

  • 组件都在线,但出现超时或错误提示某组件无法连接时,可以使用status --conn检查与各组件的连接,会打印出简单访问的耗时。也可以用它来测试客户端主机与集群的连接情况,及时发现网络隔离。

  • 离线job如果出现问题,SHOW JOBLOG id可以查看日志,但经验较少的用户可能会被日志中的无关信息干扰,可以使用inspect job来提取job日志中的关键信息。

  • 离线job太多时,CLI中的展示会不容易读,可以使用inspect offline筛选所有failed的job,或者inspect job --state <state>来筛选出特定状态的job。

  • 在一些棘手的问题中,可能需要用户通过RPC来获得一些信息,帮助定位问题。openmldb_tool rpc可以帮助用户简单快速地调用RPC,降低运维门槛。

  • 没有Prometheus监控时,可以通过inspect online --dist获得数据分布信息。

  • 如果你的操作节点到各个组件的机器是ssh免密的,那么,可以使用static-check检查配置文件是否正确,版本是否统一,避免部署失败。还可以一键收集整个集群的日志,方便打包并提供给开发人员分析。

子命令详情#

status 状态#

status用于查看OpenMLDB集群的状态,包括服务组件的地址,角色,连接时间,状态等,等价于SHOW COMPONENTS。如果发现集群表现不正常,请先查询各服务组件的实时状态。

openmldb_tool status -h
usage: openmldb_tool status [-h] [--helpfull] [--diff]

optional arguments:
  -h, --help  show this help message and exit
  --helpfull  show full help message and exit
  --diff      check if all endpoints in conf are in cluster. If set, need to set `-f,--conf_file`
  --conn                check network connection of all servers
  • 简单查询集群状态:

    openmldb_tool status [--cluster=...]
    

    输出类似下表:

    +-----------------+-------------+---------------+--------+---------+
    |     Endpoint    |     Role    |  Connect_time | Status | Ns_role |
    +-----------------+-------------+---------------+--------+---------+
    | localhost:10921 |    tablet   | 1677398926974 | online |   NULL  |
    | localhost:10922 |    tablet   | 1677398926978 | online |   NULL  |
    |  localhost:7527 |  nameserver | 1677398927985 | online |  master |
    |  localhost:9902 | taskmanager | 1677398934773 | online |   NULL  |
    +-----------------+-------------+---------------+--------+---------+
    
  • 检查并测试集群链接与版本:

    openmldb_tool status --conn
    

检查配置文件与集群状态是否一致#

如果指定--diff参数,会检查配置文件中的所有节点是否都在已经启动的集群中,如果有节点不在集群中,会输出异常信息。如果集群中有节点不在配置文件中,不会输出异常信息。需要配置-f,--conf_file,例如,你可以在镜像里这样检查:

openmldb_tool status --diff -f=/work/openmldb/conf/hosts

inspect 检查#

如果是为了检查集群状态,更推荐一键inspect获取集群完整检查报告,inspect子命令是更具有针对性的检查。

openmldb_tool inspect -h
usage: openmldb_tool inspect [-h] [--helpfull] {online,offline,job} ...

positional arguments:
  {online,offline,job}
    online              only inspect online table.
    offline             only inspect offline jobs.
    job                 show jobs by state, show joblog or parse joblog by id.

online在线检查#

inspect online检查在线表的健康状态,并输出有异常的表,包括表的状态,分区信息,副本信息等,等价于SHOW TABLE STATUS并筛选出有异常的表。

检查在线数据分布#

可以使用inspect online --dist检查在线数据分布,默认检查所有数据库,可以使用--db指定要检查的数据库。若要查询多个数据库,请使用 ‘,’ 分隔数据库名称。会输出数据库在各个节点上的数据分布情况。

offline离线检查#

inspect offline离线检查会输出最终状态为失败的任务(不检查“运行中”的任务),等价于SHOW JOBS并筛选出失败任务。更多功能待补充。

JOB 检查#

JOB 检查是更灵活的离线任务检查命令,可以按条件筛选job,或针对单个job日志进行分析。

按state筛选#

可以使用inspect jobinspect job --state all查询所有任务,等价于SHOW JOBS并按job_id排序。使用inspect job --state <state>可以筛选出特定状态的日志,可以使用 ‘,’ 分隔,同时查询不同状态的日志。例如:inspect offline 相当于inspect job --state failed,killed,lost即筛选出所有失败的任务。

以下是一些常见的state:

state

描述

finished

成功完成的任务

running

正在运行的任务

failed

失败的任务

killed

被终止的任务

更多state信息详见Spark StateYarn State

解析单个JOB日志#

使用inspect job --id <job_id>查询指定任务的log日志,其结果会使用配置文件筛选出主要错误信息。

解析依靠配置文件,默认情况会自动下载。如需更新配置文件,可以--conf-update,它将会在解析前强制下载一次配置文件。如果默认下载源不合适,可以同时配置--conf-url配置镜像源,例如使用--conf-url https://openmldb.ai/download/diag/common_err.yml配置国内镜像。

如果只需要完整的日志信息而不是解析日志的结果,可以使用--detail获取详细信息,不会打印解析结果。

test 测试#

test将执行一些测试SQL,包括:创建库,创建表,在线插入数据,在线查询数据,删除表,删除库。如果TaskManager组件存在,还会执行离线查询任务,由于没有做离线导入数据,查询结果理应为空。

在新建好集群时或发现集群表现不正常时,可以执行test测试集群是否能工作。

static-check 静态检查#

static-check静态检查,根据集群部署配置文件(通过参数-f,--conf_file指定),登录各个服务组件的部署地址,可以收集版本信息、配置文件、日志文件,检查版本是否一致,对收集到的配置文件和日志文件做分析。可以在集群未部署前进行检查,避免因程序版本或配置文件错误导致的集群部署失败。或在集群异常时,将分布式的日志文件收集在一起,方便调查问题。

openmldb_tool static-check -h
usage: openmldb_tool static-check [-h] [--helpfull] [--version] [--conf] [--log]

optional arguments:
  -h, --help     show this help message and exit
  --helpfull     show full help message and exit
  --version, -V  check version
  --conf, -C     check conf
  --log, -L      check log

部署配置文件#

-f,--conf_file部署配置文件格式可以是hosts风格或yaml风格,描述集群中有哪些组件,分布在哪个节点以及部署目录。

  • hosts风格(参考release包中的conf/hosts

[tablet]
localhost:10921 /tmp/openmldb/tablet-1
localhost:10922 /tmp/openmldb/tablet-2

[nameserver]
localhost:7527

[apiserver]
localhost:9080

[taskmanager]
localhost:9902

[zookeeper]
localhost:2181:2888:3888 /tmp/openmldb/zk-1
  • 集群版yaml

mode: cluster
zookeeper:
  zk_cluster: 127.0.0.1:2181
  zk_root_path: /openmldb
nameserver:
  -
    endpoint: 127.0.0.1:6527
    path: /work/ns1
tablet:
  -
    endpoint: 127.0.0.1:9527
    path: /work/tablet1
  -
    endpoint: 127.0.0.1:9528
    path: /work/tablet2
taskmanager:
  -
    endpoint: 127.0.0.1:9902
    path: /work/taskmanager1

如果是分布式部署,诊断工具需要到部署节点上拉取文件,所以需要添加机器互信免密。设置方法参考这里

如果hosts/yaml中某些组件没有配置path,将会使用--default_dir作为部署目录,默认值为/work/openmldb。如果你的部署目录不是这个,可以通过--default_dir指定。

如果是onebox部署,可以指定--local,我们会把所有节点当作本地节点,不会尝试ssh登录。如果部分节点是本地节点,只能使用yaml格式的部署配置文件,对本地节点配置is_local: true。例如:

nameserver:
  -
    endpoint: 127.0.0.1:6527
    path: /work/ns1
    is_local: true

检查内容#

检查可通过组合FLAG来来指定检查哪些内容,例如,-V只检查版本,-CL只检查配置文件和日志,-VCL检查全部。

  • -V,--version检查版本,检查各个组件的版本是否一致,如果不一致,会输出不一致的组件和版本信息(由于复杂度较高,openmldb-batch包的地址可能查不到,将忽略检查,替换batch包非常容易,可以推后检查)。

  • -C,--conf收集配置文件,检查各个组件的配置文件中ZooKeeper地址是否一致等。

  • -L,--log收集日志,输出WARNING及以上的日志。

如果检查配置文件或日志,将会把收集到的文件保存在--collect_dir中,默认为/tmp/diag_collect。你也也可以访问此目录查看收集到的配置或日志,进行更多的分析。

检查示例#

在镜像容器中可以这样静态检查:

openmldb_tool static-check --conf_file=/work/openmldb/conf/hosts -VCL --local

RPC 接口#

openmldb_tool还提供了一个RPC接口,它可以让我们发送RPC更容易,不需要定位Server的IP,拼接RPC方法URL路径,也可以提示所有RPC方法和RPC方法的输入结构。使用方式是openmldb_tool rpc,例如,openmldb_tool rpc ns ShowTable --field '{"show_all":true}'可以调用nameserverShowTable接口,获取表的状态信息。

其中组件不使用ip,可以直接使用角色名。NameServer与TaskManager只有一个活跃,所以我们用ns和tm来代表这两个组件。而TabletServer有多个,我们用tablet1tablet2等来指定某个TabletServer,从1开始,顺序可通过openmldb_tool rpcopenmldb_tool status来查看。

如果对RPC服务的方法或者输入参数不熟悉,可以通过openmldb_tool rpc <component> [method] --hint查看帮助信息。但它是一个额外组件,需要通过pip install openmldb-tool[pb]安装。hint还需要额外的pb文件,帮助解析输入参数,默认是从/tmp/diag_cache中读取,如果不存在则自动下载。如果你已有相应的文件,或者已经手动下载,可以通过--pbdir指定该目录。自行编译pb文件,见openmldb tool开发文档

例如:

$ openmldb_tool rpc ns ShowTable --hint
...
server proto version is 0.7.0-e1d35fcf6
hint use pb2 files from /tmp/diag_cache
You should input json like this, ignore round brackets in the key and double quotation marks in the value: --field '{
    "(optional)name": "string",
    "(optional)db": "string",
    "(optional)show_all": "bool"
}'

附加#

可使用openmldb_tool --helpfull查看所有配置项。例如,--sdk_log可以打印sdk的日志(zk,glog),可用于调试。