feat: full inspect

docs/zh/maintain/diagnose.md

@@ -8,14 +8,80 @@
 
 安装方式与使用：
 ```bash
-pip install openmldb-tool # openmldb-tool[rpc]
+pip install openmldb-tool # openmldb-tool[pb]
 openmldb_tool # 注意下划线
 ```
 有以下几个子命令可选择执行：
 ```bash
-usage: openmldb_tool [-h] [--helpfull] {status,inspect,test,static-check} ...
+usage: openmldb_tool [-h] [--helpfull] {status,inspect,rpc,test,static-check} ...
 ```
-只有`static-check`静态检查命令需要指定`--dist_conf`参数，该参数指定OpenMLDB节点分布的配置文件。其他命令只需要`--cluster`参数，格式为`<zk_cluster>/<zk_root_path>`，默认为镜像中的OpenMLDB集群地址`127.0.0.1:2181/openmldb`。如果是自行设置的OpenMLDB集群，请配置此参数。
+
+注意`-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 Healthy Detail
+summary: {total table cnt}
+{unhealthy tables db.name}
+
+
+Ops Detail
+> failed ops do not mean cluster is unhealthy, just for reference
+last one op(check time): {}
+last 10 unfinished ops:
+{op list}
+
+
+Table Partitions Detail
+tablet server order: {tablet ip -> idx}
+{partition tables of unhealthy tables}
+Example:
+{a detailed description of partition table}
+
+
+==================
+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`检查配置文件是否正确，版本是否统一，避免部署失败。还可以一键收集整个集群的日志，方便打包并提供给开发人员分析。
 
 ## 子命令详情
 
@@ -29,7 +95,8 @@ 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 `--conf_file`
+  --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
 ```
 
 - 简单查询集群状态：
@@ -48,6 +115,11 @@ optional arguments:
   +-----------------+-------------+---------------+--------+---------+
   ```
 
+- 检查并测试集群链接与版本：
+  ```
+  openmldb_tool status --conn
+  ```
+
 #### 检查配置文件与集群状态是否一致
 
 如果指定`--diff`参数，会检查配置文件中的所有节点是否都在已经启动的集群中，如果有节点不在集群中，会输出异常信息。如果集群中有节点不在配置文件中，不会输出异常信息。需要配置`-f,--conf_file`，例如，你可以在镜像里这样检查：
@@ -57,7 +129,8 @@ openmldb_tool status --diff -f=/work/openmldb/conf/hosts
 
 ### inspect 检查
 
-`inspect`用于检查集群的在线和离线两个部分是否正常工作，可以选择单独检查`online`或`offline`，不指定则都检查。可以定期执行检查，以便及时发现异常。
+如果是为了检查集群状态，更推荐一键`inspect`获取集群完整检查报告，`inspect`子命令是更具有针对性的检查。
+
 ```
 openmldb_tool inspect -h
 usage: openmldb_tool inspect [-h] [--helpfull] {online,offline,job} ...
@@ -68,19 +141,26 @@ positional arguments:
     offline             only inspect offline jobs.
     job                 show jobs by state, show joblog or parse joblog by id.
 ```
-在线检查会检查集群中的表状态（包括系统表），并输出有异常的表，包括表的状态，分区信息，副本信息等，等价于`SHOW TABLE STATUS`并筛选出有异常的表。如果发现集群表现不正常，请先检查下是否有异常表。例如，`SHOW JOBS`无法正常输出历史任务时，可以`inspect online`检查一下是否是job系统表出现问题。
+
+#### online在线检查
+
+`inspect online`检查在线表的健康状态，并输出有异常的表，包括表的状态，分区信息，副本信息等，等价于`SHOW TABLE STATUS`并筛选出有异常的表。
 
 ##### 检查在线数据分布
 
-在线检查中，可以使用`inspect online --dist`检查在线数据分布，默认检查所有数据库，可以使用`--db`指定要检查的数据库。若要查询多个数据库，请使用 ',' 分隔数据库名称。会输出数据库在各个节点上的数据分布情况。
+可以使用`inspect online --dist`检查在线数据分布，默认检查所有数据库，可以使用`--db`指定要检查的数据库。若要查询多个数据库，请使用 ',' 分隔数据库名称。会输出数据库在各个节点上的数据分布情况。
 
-#### 离线检查
+#### offline离线检查
 
-离线检查会输出最终状态为失败的任务（不检查“运行中”的任务），等价于`SHOW JOBS`并筛选出失败任务。
+`inspect offline`离线检查会输出最终状态为失败的任务（不检查“运行中”的任务），等价于`SHOW JOBS`并筛选出失败任务。更多功能待补充。
 
 #### JOB 检查
 
-JOB 检查会检查集群中的离线任务，可以使用`inspect job`或`inspect job --state all`查询所有任务，等价于`SHOW JOBS`并按job_id排序。使用`inspect job --state <state>`可以筛选出特定状态的日志，可以使用 ',' 分隔，同时查询不同状态的日志。例如：`inspect offline` 相当于`inspect job --state failed,killed,lost`即筛选出所有失败的任务。
+JOB 检查是更灵活的离线任务检查命令，可以按条件筛选job，或针对单个job日志进行分析。
+
+##### 按state筛选
+
+可以使用`inspect job`或`inspect job --state all`查询所有任务，等价于`SHOW JOBS`并按job_id排序。使用`inspect job --state <state>`可以筛选出特定状态的日志，可以使用 ',' 分隔，同时查询不同状态的日志。例如：`inspect offline` 相当于`inspect job --state failed,killed,lost`即筛选出所有失败的任务。
 
 以下是一些常见的state:
 
@@ -93,8 +173,13 @@ JOB 检查会检查集群中的离线任务，可以使用`inspect job`或`inspe
 
 更多state信息详见[Spark State]( https://spark.apache.org/docs/3.2.1/api/java/org/apache/spark/launcher/SparkAppHandle.State.html)，[Yarn State](https://hadoop.apache.org/docs/current/api/org/apache/hadoop/yarn/api/records/YarnApplicationState.html)
 
+##### 解析单个JOB日志
 
-使用`inspect job --id <job_id>`查询指定任务的log日志，其结果会使用配置文件筛选出主要错误信息。如需更新配置文件，可以添加`--conf-update`，并且可以使用`--conf-url`配置镜像源，例如使用`--conf-url https://openmldb.ai/download/diag/common_err.yml`配置国内镜像。如果需要完整的日志信息，可以添加`--detail`获取详细信息。
+使用`inspect job --id <job_id>`查询指定任务的log日志，其结果会使用配置文件筛选出主要错误信息。
+
+解析依靠配置文件，默认情况会自动下载。如需更新配置文件，可以`--conf-update`，它将会在解析前强制下载一次配置文件。如果默认下载源不合适，可以同时配置`--conf-url`配置镜像源，例如使用`--conf-url https://openmldb.ai/download/diag/common_err.yml`配置国内镜像。
+
+如果只需要完整的日志信息而不是解析日志的结果，可以使用`--detail`获取详细信息，不会打印解析结果。
 
 ### test 测试
 
@@ -185,22 +270,22 @@ nameserver:
 
 如果检查配置文件或日志，将会把收集到的文件保存在`--collect_dir`中，默认为`/tmp/diag_collect`。你也也可以访问此目录查看收集到的配置或日志，进行更多的分析。
 
-
 #### 检查示例
 
 在镜像容器中可以这样静态检查：
 ```bash
 openmldb_tool static-check --conf_file=/work/openmldb/conf/hosts -VCL --local
 ```
 
-### rpc
+### RPC 接口
+
+`openmldb_tool`还提供了一个RPC接口，它可以让我们发送RPC更容易，不需要定位Server的IP，拼接RPC方法URL路径，也可以提示所有RPC方法和RPC方法的输入结构。使用方式是`openmldb_tool rpc`，例如，`openmldb_tool rpc ns ShowTable --field '{"show_all":true}'`可以调用`nameserver`的`ShowTable`接口，获取表的状态信息。
 
-`openmldb_tool`还提供了一个RPC接口，但它是一个额外组件，需要通过`pip install openmldb-tool[rpc]`安装。使用方式是`openmldb_tool rpc`，例如，`openmldb_tool rpc ns ShowTable --field '{"show_all":true}'`可以调用`nameserver`的`ShowTable`接口，获取表的状态信息。
+其中组件不使用ip，可以直接使用角色名。NameServer与TaskManager只有一个活跃，所以我们用ns和tm来代表这两个组件。而TabletServer有多个，我们用`tablet1`，`tablet2`等来指定某个TabletServer，从1开始，顺序可通过`openmldb_tool rpc`或`openmldb_tool status`来查看。
 
-NameServer与TaskManager只有一个活跃，所以我们用ns和tm来代表这两个组件。
-而TabletServer有多个，我们用`tablet1`，`tablet2`等来指定某个TabletServer，顺序可通过`openmldb_tool rpc`或`openmldb_tool status`来查看。
+如果对RPC服务的方法或者输入参数不熟悉，可以通过`openmldb_tool rpc <component> [method] --hint`查看帮助信息。但它是一个额外组件，需要通过`pip install openmldb-tool[pb]`安装。hint还需要额外的pb文件，帮助解析输入参数，默认是从`/tmp/diag_cache`中读取，如果不存在则自动下载。如果你已有相应的文件，或者已经手动下载，可以通过`--pbdir`指定该目录。自行编译pb文件，见[openmldb tool开发文档](https://github.com/4paradigm/OpenMLDB/blob/main/python/openmldb_tool/README.md#rpc)。
 
-如果对RPC服务的方法或者输入参数不熟悉，可以通过`openmldb_tool rpc <component> [method] --hint`查看帮助信息。例如：
+例如：
 ```bash
 $ openmldb_tool rpc ns ShowTable --hint
 ...
@@ -212,9 +297,7 @@ You should input json like this, ignore round brackets in the key and double quo
     "(optional)show_all": "bool"
 }'
 ```
-hint还需要额外的pb文件，帮助解析输入参数，默认是从`/tmp/diag_cache`中读取，如果不存在则自动下载。如果你已有相应的文件，或者已经手动下载，可以通过`--pbdir`指定该目录。
 
 ## 附加
 
 可使用`openmldb_tool --helpfull`查看所有配置项。例如，`--sdk_log`可以打印sdk的日志（zk，glog），可用于调试。
-

docs/zh/quickstart/beginner_must_read.md

@@ -2,6 +2,20 @@
 
 由于OpenMLDB是分布式系统，多种模式，客户端丰富，初次使用可能会有很多疑问，或者遇到一些运行、使用问题，本文从新手使用的角度，讲解如何进行诊断调试，需求帮助时如何提供有效信息给技术人员等等。
 
+## 错误诊断
+
+在使用OpenMLDB的过程中，除了SQL语法错误，其他错误信息可能不够直观，但很可能与集群状态有关。所以，错误诊断需要**先确认集群状态**。在发现错误时，请先使用诊断工具的一键诊断功能。一键诊断可以输出全面直观的诊断报告，如果不能使用此工具，可以手动执行`SHOW COMPONENTS;`和`SHOW TABLE STATUS LIKE '%';`提供部分信息。
+
+报告将展示集群的组件、在线表等状态，也会提示用户如何修复，请按照报告内容进行操作，详情见[一键inspect](../maintain/diagnose.md#一键inspect)。
+
+```
+openmldb_tool inspect [-c=0.0.0.0:2181/openmldb]
+```
+
+需要注意，由于离线存储只会在执行离线job时被读取，而离线job也不是一个持续的状态，所以，一键诊断只能展示TaskManager组件状态，不会诊断离线存储，也无法诊断离线job的执行错误，离线job诊断见[离线SQL执行](#离线)。
+
+如果诊断报告认为集群健康，但仍然无法解决问题，请提供错误和诊断报告给我们。
+
 ## 创建OpenMLDB与连接
 
 首先，我们建议不熟悉分布式多进程管理的新手使用docker创建OpenMLDB，方便快速上手。熟悉OpenMLDB各组件之后，再尝试分布式部署。
@@ -71,12 +85,14 @@ create table t1(c1 int;
 
 如果是集群离线命令，默认异步模式下，发送命令会得到job id的返回。可使用`show job <id>`来查询job执行情况。
 
-离线job如果是异步SELECT（并不INTO保存结果），也不会将结果打印在客户端（同步SELECT将会打印结果）。可以通过`show joblog <id>`来获得结果，结果中包含stdout和stderr两部分，stdout为查询结果，stderr为job运行日志。如果发现job failed或者其他状态，不符合你的预期，请仔细查看job运行日志。
+离线job如果是异步SELECT（并不INTO保存结果），也不会将结果打印在客户端，而同步SELECT将会打印结果到控制台。可以通过`show joblog <id>`来获得结果，结果中包含stdout和stderr两部分，stdout为查询结果，stderr为job运行日志。如果发现job failed或者其他状态，不符合你的预期，请仔细查看job运行日志。
 
-```{note}
-日志地址由taskmanager.properties的`job.log.path`配置，如果你改变了此配置项，需要到配置的目的地寻找日志。stdout日志默认在`/work/openmldb/taskmanager/bin/logs/job_x.log`，job运行日志默认在`/work/openmldb/taskmanager/bin/logs/job_x_error.log`(注意有error后缀)，
+离线job日志中可能有一定的干扰日志，用户可以使用`openmldb_tool inspect job --id x`进行日志的解析提取，帮助定位错误，更多信息请参考[诊断工具job检查](../maintain/diagnose.md#job-检查)。
 
-如果taskmanager是yarn模式，而不是local模式，`job_x_error.log`中的信息会较少，不会有job错误的详细信息。需要通过`job_x_error.log`中记录的yarn app id，去yarn系统中查询job的真正错误原因。
+如果taskmanager是yarn模式，而不是local模式，`job_x_error.log`中的信息会较少，只会打印异常。如果异常不直观，需要更早时间的执行日志，执行日志不在`job_x_error.log`中，需要通过`job_x_error.log`中记录的yarn app id，去yarn系统中查询yarn app的container的日志。yarn app container里，执行日志也保存在stderr中。
+
+```{note}
+如果你无法通过show joblog获得日志，或者想要直接拿到日志文件，可以直接在TaskManager机器上获取。日志地址由taskmanager.properties的`job.log.path`配置，如果你改变了此配置项，需要到配置的目录中寻找日志。stdout查询结果默认在`/work/openmldb/taskmanager/bin/logs/job_x.log`，stderr job运行日志默认在`/work/openmldb/taskmanager/bin/logs/job_x_error.log`(注意有error后缀)。
 ```
 
 #### 在线

python/openmldb_tool/README.md

@@ -48,21 +48,27 @@ status [-h] [--helpfull] [--diff 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 `--conf_file`
+  --diff       check if all endpoints in conf are in cluster. If set, need to set `-f,--conf_file`
 ```
 
 Use `show components` to show servers(no apiserver now).
 
+--conn:
+- ping all servers, brpc /health to check ok，and
+- online servers version and cost time, we can get from brpc http://<endpoint>/version. (ns,tablet, apiserver set_version in brpc server)
+
 TODO: 
-- ping all servers, brpc /health to check ok
-- online servers version, we can get from brpc http://<endpoint>/version. (ns,tablet, apiserver set_version in brpc server)
 - brpc /flags to get all gflags(including openmldb), `--enable_flags_service=true` required
 
 ## Inspect
 
-Use `show table status like '%';` in all dbs, even the hidden db(system db).
+`inspect` for full report, no offline diag now. 
+
+inspect online: Use `show table status like '%';` in all dbs, even the hidden db(system db).
+
+inspect offline: failed jobs, no more info. TODO: check register table?
 
-If you found some online tables are not behaving properly, do inspect online.
+inspect job: full support of offline job, select jobs, parse job log
 
 ## Test