Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add diagnostic tool docs #2326

Merged
merged 7 commits into from
Aug 10, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 82 additions & 0 deletions docs/en/maintain/diagnose.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Diagnostic Tool

## Overview

OpenMLDB provides a diagnostic tool to diagnose problems conveniently for users. It can check items as below:

- Version
- Configuration
- Log
- Run test SQL

## Usage

1. Download diagnostic tool
```bash
pip install openmldb-tool
```

2. Config cluster distribution

standalone yaml conf
```yaml
mode: standalone
nameserver:
-
endpoint: 127.0.0.1:6527
path: /work/openmldb
tablet:
-
endpoint: 127.0.0.1:9527
path: /work/openmldb
```

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

3. Setup SSH Passwordless Login

As diagnostic tool will pull conf and log files from remote nodes when checking cluster, SSH passwordless shoud be setup. If you do not konw how to set, you can refer [here]((https://www.itzgeek.com/how-tos/linux/centos-how-tos/ssh-passwordless-login-centos-7-rhel-7.html))

4. Run diagnostic tool

```bash
openmldb_tool --dist_conf=/tmp/standalone_dist.yml
```

There are some advanced options can be specified as below:

- --dist_conf: To config the distribution of cluster
- --data_dir: The data dir to store the conf and log files pulled from remote. The default value is `/tmp/diagnose_tool_data`
- --check: The item to check. The default value is `ALL`. It can be specified as `CONF/LOG/SQL/VERSION`
- --exclude: The item do not check. Only work if `check` option is `ALL`. It can be specified as `CONF/LOG/SQL/VERSION`
- --log_level: The default value is `info`. It can be specified as `debug/warn/info`
- --log_dir: Specific the output dir. It will print to stdout if not set
- --env: If the cluster is started with `start-all.sh` script, `onbox` should be setted.

For instance, we can check `conf` only and print the ouput to local dir as below:
```
openmldb_tool --dist_conf=/tmp/cluster_dist.yml --check=conf --log_dir=./
```

**Note**: If you want to diagnostie standalone mode OpenMLDB, you need to run diagnostic tool on the OpenMLDB node.
3 changes: 2 additions & 1 deletion docs/en/maintain/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,5 @@ Maintenance
monitoring
cli
faq
scale
scale
diagnose
79 changes: 79 additions & 0 deletions docs/zh/maintain/diagnose.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# 诊断工具

## 概述

为了方便排查用户环境中的常见问题,OpenMLDB提供了诊断工具。主要有以下功能:
- 版本校验
- 配置文件检查
- 日志提取
- 执行测试SQL

## 使用

1. 下载诊断工具包
```bash
pip install openmldb-tool
```

2. 准备环境yaml配置文件

单机版yaml
```yaml
mode: standalone
nameserver:
-
endpoint: 127.0.0.1:6527
path: /work/openmldb
tablet:
-
endpoint: 127.0.0.1:9527
path: /work/openmldb
```

集群版yaml
```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
```

3. 添加机器互信

由于诊断工具需要到部署节点上拉取文件,所以需要添加机器互信免密。设置方法参考[这里](https://www.itzgeek.com/how-tos/linux/centos-how-tos/ssh-passwordless-login-centos-7-rhel-7.html)

4. 执行诊断工具命令
```bash
openmldb_tool --dist_conf=/tmp/standalone_dist.yml
```
诊断工具所有参数如下:

- --dist_conf OpenMLDB节点分布的配置文件
- --data_dir 数据存放路径。会把远端的配置文件和日志等放在这个目录里,默认为/tmp/diagnose_tool_data
- --check 检查项,默认为ALL即检查所有。还可以单独配置为CONF/LOG/SQL/VERSION,分别检查配置文件、日志、执行SQL、版本
- --exclude 不检查其中某一项。只有check设置为ALL才会生效。可以配置为CONF/LOG/SQL/VERSION
- --log_level 设置日志级别,默认为info。可以设置为debug/warn/info
- --log_dir 设置结果输出路径,默认为标准输出
- --env 如果用start-all.sh启动的集群,需要指定为onbox, 其他情况不需要指定

例如指定只检查配置文件,并且结果输出到当前目录下
```
openmldb_tool --dist_conf=/tmp/cluster_dist.yml --check=conf --log_dir=./
```

**注**: 如果是单机版,诊断工具必须在单机版部署节点上执行
1 change: 1 addition & 0 deletions docs/zh/maintain/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,4 @@
monitoring
cli
faq
diagnose
2 changes: 0 additions & 2 deletions docs/zh/reference/sql/dml/DELETE_STATEMENT.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
# DELETE

OpenMLDB supports single-row and multi-row insert statements

## 语法

```sql
Expand Down