Skip to content

Commit

Permalink
docs: fix boundary, add more about maintain (4paradigm#3519)
Browse files Browse the repository at this point in the history
* docs: fix boundary about deploy and diag rpc desc

* doc about beginner, boundary

* storage

* apiserver refresh desc

---------

Co-authored-by: Huang Wei <[email protected]>
  • Loading branch information
vagetablechicken and Huang Wei authored Nov 29, 2023
1 parent 5e225da commit b005cd1
Show file tree
Hide file tree
Showing 7 changed files with 76 additions and 27 deletions.
18 changes: 13 additions & 5 deletions docs/zh/faq/client_faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,13 +76,21 @@ sdk日志(glog日志):

## 离线命令Spark报错

`java.lang.OutOfMemoryError: Java heap space`

离线命令的Spark配置默认为`local[*]`,并发较高可能出现OutOfMemoryError错误,请调整`spark.driver.memory``spark.executor.memory`两个spark配置项。可以写在TaskManager运行目录的`conf/taskmanager.properties``spark.default.conf`并重启TaskManager,或者使用CLI客户端进行配置,参考[客户端Spark配置文件](../reference/client_config/client_spark_config.md)
```
spark.default.conf=spark.driver.memory=16g;spark.executor.memory=16g
java.lang.OutOfMemoryError: Java heap space
```

```
Container killed by YARN for exceeding memory limits. 5 GB of 5 GB physical memory used. Consider boosting spark.yarn.executor.memoryOverhead.
```

出现以上几种日志时,说明离线任务所需资源多于当前配置。一般是这几种情况:
- 离线命令的Spark配置`local[*]`,机器核数较多,并发度很高,资源占用过大
- memory配置较小

如果是local模式,单机资源比较有限,可以考虑降低并发度。如果不降低并发,请调整`spark.driver.memory``spark.executor.memory`两个spark配置项。可以写在TaskManager运行目录的`conf/taskmanager.properties``spark.default.conf`并重启TaskManager,或者使用CLI客户端进行配置,参考[客户端Spark配置文件](../reference/client_config/client_spark_config.md)
```
spark.default.conf=spark.driver.memory=16g;spark.executor.memory=16g
```

local时drivermemory
master为local时,不是调整executor的,而是driver的memory,如果你不确定,可以两者都调节。
4 changes: 2 additions & 2 deletions docs/zh/openmldb_sql/dml/DELETE_STATEMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ TableName ::=

**说明**

- `DELETE` 语句删除在线表满足指定条件的数据
- `DELETE` 语句删除在线表满足指定条件的数据,删除并不是所有索引中满足条件的数据都被删除,只会删除与where condition相关的索引,示例见[功能边界](../../quickstart/function_boundary.md#delete)
- `WHERE` 指定的筛选列必须是索引列。如果是key列只能用等于

## Examples
Expand All @@ -25,4 +25,4 @@ DELETE FROM t1 WHERE col1 = 'aaaa' and ts_col = 1687145994000;
DELETE FROM t1 WHERE col1 = 'aaaa' and ts_col > 1687059594000 and ts_col < 1687145994000;

DELETE FROM t1 WHERE ts_col > 1687059594000 and ts_col < 1687145994000;
```
```
6 changes: 5 additions & 1 deletion docs/zh/openmldb_sql/dml/LOAD_DATA_STATEMENT.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
# LOAD DATA INFILE
`LOAD DATA INFILE`语句能高效地将文件中的数据读取到数据库中的表中。`LOAD DATA INFILE``SELECT INTO OUTFILE`互补。要将数据从 table导出到文件,请使用[SELECT INTO OUTFILE](../dql/SELECT_INTO_STATEMENT.md)。要将文件数据导入到 table 中,请使用`LOAD DATA INFILE`

```{note}
INFILE 的 filePath,既可以是单个文件名,也可以是目录,也可以使用`*`通配符。如果目录中存在多格式的文件,只会选择 LoadDataInfileOptionsList 中指定的FORMAT格式文件。具体格式等价于`DataFrameReader.read.load(String)`,可以使用spark shell来read你想要的文件路径,确认能否读入成功。
```

## Syntax

```sql
Expand Down Expand Up @@ -70,7 +74,7 @@ FilePathPattern
## SQL语句模版

```sql
LOAD DATA INFILE 'file_name' INTO TABLE 'table_name' OPTIONS (key = value, ...);
LOAD DATA INFILE 'file_path' INTO TABLE 'table_name' OPTIONS (key = value, ...);
```

## Hive 支持
Expand Down
41 changes: 32 additions & 9 deletions docs/zh/quickstart/beginner_must_read.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,19 +32,42 @@ docker创建OpenMLDB见[快速上手](./openmldb_quickstart.md),请注意文
如果我们还需要OpenMLDB服务端的配置和日志,可以使用诊断工具获取,见[下文](#提供配置与日志获得技术支持)。
```

### 运维
### 部署工具说明

集群各组件进程启动后,在使用过程中可能遇到各种变化,比如服务进程意外退出,需要重启服务进程,或者需要扩容服务进程
请确定你使用的是什么部署方式,通常我们只考虑两种部署方式,见[安装部署](../deploy/install_deploy.md),“一键部署”也被称为sbin部署方式。配置文件如何修改,日志文件在何处,都与部署方式联系紧密,所以必须准确

如果你需要保留已有的在线表,**不要主动地kill全部Tablet再重启**,保证Tablet只有单台在上下线。`stop-all.sh``start-all.sh`脚本是给快速重建集群用的,可能会导致在线表数据恢复失败,**不保证能修复**
- sbin部署
sbin部署会经过deploy(拷贝安装包至各个节点),再启动组件。需要明确的是,部署节点就是执行sbin的节点,尽量不要在运维中更换目录。deploy到hosts中各个节点的目录中,这些节点的目录我们称为运行目录。

当你发现进程变化或者主动操作其变化后,需要使用诊断工具进行诊断,确认集群状态是否正常:
```bash
openmldb_tool inspect # 主要命令
openmldb_tool status --diff hosts # 可检查TaskManager等是否掉线,当然,你也可以手动判断
```
配置文件会在deploy阶段,从template文件生成,所以,如果你要修改某组件的配置,不要在节点上修改,需要在部署地点修改template文件。如果你不进行deploy操作,可以在节点运行目录上原地修改配置文件(非template),但deploy将覆盖修改,需要谨慎处理。

出现任何非预期的情况,以sbin部署的最终配置文件,即组件节点的运行目录中的配置文件为准。运行目录查看`conf/hosts`,例如,`localhost:10921 /tmp/openmldb/tablet-1`说明tablet1的运行目录是`/tmp/openmldb/tablet-1``localhost:7527`目录为空说明该组件就运行在`$OPENMLDB_HOME`(如未指定,就是指部署目录)。如果你无法自行解决,提供最终配置文件给我们。

sbin日志文件地址,需要先查看hosts确认组件节点的运行目录,TaskManager日志通常在`<dir>/taskmanager/bin/logs`中,其他组件日志均在`<dir>/logs`中。如有特别配置,以配置项为准。

- 手动部署
手动部署只要使用脚本`bin/start.sh``conf/`目录中的配置文件(非template结尾)。唯一需要注意的是,`spark.home`可以为空,那么会读取`SPARK_HOME`环境变量。如果你认为环境变量有问题,导致启动不了TaskManager,推荐写配置`spark.home`

手动部署的组件日志文件,以运行`bin/start.sh`的目录为准,TaskManager日志通常在`<dir>/taskmanager/bin/logs`中,其他组件日志均在`<dir>/logs`中。如有特别配置,以配置项为准。

## 运维

- 上文提到,inspect能帮我们检查集群状态,如果有问题,可使用recoverdata工具。但这是事后修复手段,通常情况下,我们应该通过正确的运维手段避免这类问题。需要上下线节点时,**不要主动地kill全部Tablet再重启**。请尽量用扩缩容的方式来操作,详情见[扩缩容](../maintain/scale.md)
- 如果你认为已有数据不重要,更需要快速地上下线,那么可以直接重启节点。`stop-all.sh``start-all.sh`脚本是给快速重建集群用的,可能会导致在线表数据恢复失败,**不保证能修复**

- 各组件在长期服务中也可能出现网络抖动、慢节点等复杂问题,请开启[监控](../maintain/monitoring.md)。如果监控中服务端表现正常,可以怀疑是你的客户端或网络问题。如果监控中服务端就出现延迟高,qps低等情况,请向我们提供相关监控图。

## 理解存储

OpenMLDB是在线离线存储计算分离的,所以,你需要明确自己导入数据或查询数据是处于在线模式还是离线模式。

离线存储在HDFS等地,如果你认为导入到离线存储的数据有缺漏,需要到存储地点进行进一步检查。

在线存储需要注意以下几点:
- 在线存储是有TTL概念的,所以,如果你导入数据后检查发现数据少了,可能是数据因为过期被淘汰了。
- 在线存储适合使用`select count(*) from t1``show table status`来检查条数,请不要使用`select * from t1`来检查,可能有数据截断,这种查询只适合预览数据。

如果诊断出server offline,或是TaskManager等掉线,需要先启动回来。如果启动失败,请查看对应日志,提供错误信息。如果诊断结果提示需要recoverdata,请参考[OpenMLDB运维工具](../maintain/openmldb_ops.md)执行recoverdata。如果recoverdata脚本提示recover失败,或recover成功后再次inpsect的结果仍然不正常,请提供日志给我们
关于如何设计你的数据流入流出,可参考[实时决策系统中 OpenMLDB 的常见架构整合方式](../tutorial/app_arch.md)

## 源数据

Expand Down
29 changes: 20 additions & 9 deletions docs/zh/quickstart/function_boundary.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

## 系统配置——TaskManager

通过配置 TaskManager 可以决定离线存储地址 `offline.data.prefix`、离线 job 计算所需 Spark 模式 `spark.master` 等。
通过配置 TaskManager 可以决定离线存储地址 `offline.data.prefix`、离线 job 计算所需 Spark 模式 `spark.master` 等。

`offline.data.prefix`:可配置为文件路径或 HDFS 路径。生产环境建议配置 HDFS 路径,测试环境(特指 onebox 型,例如在 Docker 容器内启动)可以配置本地文件路径。文件路径作为离线存储,将无法支持多 TaskManager 分布式部署(TaskManager 之间不会传输数据)。如果想在多台主机上部署 TaskManager,请使用 HDFS 等多机可同时访问到的存储介质。如果想测试多 TaskManager 工作协同,可以在一台主机上部署多个 TaskManager,此时可以使用文件路径作为离线存储。

Expand All @@ -24,11 +24,15 @@ spark.default.conf=spark.port.maxRetries=32;foo=bar

`spark.port.maxRetries`:默认为 16,参考 [Spark 配置](https://spark.apache.org/docs/3.1.2/configuration.html)。每个离线 job 都会绑定 Spark UI,对应一个 port。每次 port 都是从默认初始端口开始尝试绑定,retry 即绑定下一个端口 port+1,如果同时运行的 job 大于 `spark.port.maxRetries`,retry 次数也就大于 `spark.port.maxRetries`,job 就会启动失败。如果你需要更大的 job 并发,请配置更大的 `spark.port.maxRetries`,重启 TaskManager 生效。

### 临时Spark配置

[客户端Spark配置文件](../reference/client_config/client_spark_config.md),CLI支持临时更改Spark配置,不需要重启TaskManager。但此配置方式不可以改变spark.master等配置。

## DDL 边界——DEPLOY 语句

通过 `DEPLOY <deploy_name> <sql>` 可以部署上线 SQL 方案,这个操作也会自动解析 SQL 帮助创建索引(可以通过 `DESC <table_name>` 查看索引详情),详情可参考 [DEPLOY STATEMENT](../openmldb_sql/deployment_manage/DEPLOY_STATEMENT.md)

部署操作是否成功,跟表的在线数据有一定关系
部署上线操作成功后,可能会创建索引,索引还会后台进行数据复制。所以,如果要保证DEPLOYMENT可以开始使用,需要查看后台复制Nameserver OP的情况,或DEPLOY时添加SYNC配置,详情见语法文档

### 长窗口 SQL

Expand All @@ -37,17 +41,18 @@ spark.default.conf=spark.port.maxRetries=32;foo=bar
### 普通 SQL

- 如果部署之前已存在相关的索引,那么这一次部署操作不会创建索引。无论表中有无在线数据,`DEPLOY` 操作将成功。
- 如果部署时需要创建新的索引,而此时表中已有在线数据,那么 `DEPLOY` 操作将失败。
- 如果索引需要更新ttl,仅更新ttl value是可以成功的,但ttl更新生效需要2个gc interval,并且更新ttl前被淘汰的数据不会找回。如果ttl需要更新type,在<0.8.1的版本中将会失败,>=0.8.1的版本可以成功。
- 如果部署时需要创建新的索引,而此时表中已有在线数据,版本<0.8.1将 `DEPLOY` 失败,>=0.8.1将在后台进行数据复制到新索引,需要等待一定时间。

解决方案有两种:
对于**旧版本**解决方案有两种:

- 严格保持先 `DEPLOY` 再导入在线数据,不要在表中有在线数据后做 `DEPLOY`
- `CRATE INDEX` 语句可以在创建新索引时,自动导入已存在的在线数据(已有索引里的数据)。如果一定需要在表已有在线数据的情况下 `DEPLOY`,可以先手动 `CRATE INDEX` 创建需要的索引(新索引就有数据了),再 `DEPLOY`(这时的 `DEPLOY` 不会创建新索引,计算时直接使用手动创建的那些索引)。
- `CRATE INDEX` 语句可以在创建新索引时,自动导入已存在的在线数据(已有索引里的数据)。如果一定需要在表已有在线数据的情况下 `DEPLOY`,可以先手动 `CREATE INDEX` 创建需要的索引(新索引就有数据了),再 `DEPLOY`(这时的 `DEPLOY` 不会创建新索引,计算时直接使用手动创建的那些索引)。

```{note}
如何知道应该创建哪些索引?
如果你只能使用旧版本,如何知道应该创建哪些索引?
目前只有 Java SDK 支持,可以通过 `SqlClusterExecutor.genDDL` 获取需要创建的所有索引。(但 `genDDL` 是获得建表语句,所以需要手动转换为 `CREATE INDEX`。) 未来将支持**直接获取创建索引语句**,或支持 `DEPLOY` **自动导入数据到新索引**
目前没有太直接的方法。推荐通过[OpenMLDB SQL Emulator](https://github.com/vagetablechicken/OpenMLDBSQLEmulator) genddl获得建表语句,其中有创建的索引配置。 Java SDK 也支持,可以通过 `SqlClusterExecutor.genDDL` 获取需要创建的所有索引(静态方法,无需连接集群),但需要额外编码。而且 `genDDL` 是获得建表语句,所以需要手动转换为 `CREATE INDEX`。
```

## DML 边界
Expand All @@ -71,11 +76,17 @@ spark.default.conf=spark.port.maxRetries=32;foo=bar
- TaskManager 是 local 模式,只有将源数据放在 TaskManager 进程的主机上才能顺利导入。
- TaskManager 是 yarn (client and cluster) 模式时,由于不知道运行容器是哪台主机,不可使用文件路径作为源数据地址。

#### ONLINE LOAD DATA

在线导入还需要考虑并发问题,在线导入本质上是Spark中每个partition task启动一个Java SDK,每个SDK会创建一个与zk之间的session,如果并发过高,同时活跃的task过多,zk的session数量就会很大,可能超过其限制`maxClientCnxns`,具体问题现象见[issue 3219](https://github.com/4paradigm/OpenMLDB/issues/3219)。简单来说,请注意你的导入任务并发数和单个导入任务的并发数,如果你同时会进行多个导入任务,建议降低单个导入任务的并发数。

单个任务最大的并发数限制为`spark.executor.instances`*`spark.executor.cores`,请调整这两个配置。当spark.master=local时,调整driver的,而不是executor的。

### DELETE

在线存储的表有多索引,`DELETE` 可能无法删除所有索引中的对应数据,所以,可能出现删除了数据,却能查出已删除数据的情况。

举例说明
举例

```SQL
create database db;
Expand Down Expand Up @@ -126,7 +137,7 @@ select * from t1 where c2=2;

说明:

`t1` 有多个索引(`DEPLOY` 也可能自动创建出多索引),`delete from t1 where c2=2` 实际只删除了第二个 index 的数据,第一个 index 数据没有被影响。所以 `select * from t1` 使用第一个索引,结果会有两条数据,并没有删除,`select * from t1 where c2=2` 使用第二个索引,结果为空,数据已被删除
`t1` 有多个索引(`DEPLOY` 也可能自动创建出多索引),`delete from t1 where c2=2` 实际只删除了第二个 index 的数据,第一个 index 数据没有被影响。这是因为delete的where condition只与第二个index相关,第一个index中没有任何该condition相关的key或ts。而 `select * from t1` 使用第一个索引,并非第二个,结果就会有两条数据,直观感受为delete失败了;`select * from t1 where c2=2` 使用第二个索引,结果为空,证明数据在该索引下已被删除

## DQL 边界

Expand Down
2 changes: 2 additions & 0 deletions docs/zh/quickstart/sdk/rest_api.md
Original file line number Diff line number Diff line change
Expand Up @@ -320,6 +320,8 @@ curl http://127.0.0.1:8080/dbs/demo_db/deployments/demo_data_service -X POST -d'

## 刷新 APIServer 元数据缓存

创建删除表、Deploymennt等操作后,元数据同步有一定的滞后性。如果你发现APIServer找不到新建的表或Deployment,请先尝试刷新缓存。

请求地址:http://ip:port/refresh

请求方式:POST
Expand Down
3 changes: 2 additions & 1 deletion docs/zh/use_case/JD_recommendation.md
Original file line number Diff line number Diff line change
Expand Up @@ -306,7 +306,8 @@ python preprocess.py $demodir/out/1

`$demodir/out/1` 即上一步 OpenMLDB 计算得到的特征数据目录。

脚本将在 `$demodir/feature_preprocess/out` 对应生成 train、test、valid 三个 Parquet 数据集,并将三者的行数和 `table_size_array` 保存在文件 `data_info.txt` 中(下一步可以直接使用 info 文件,不需要手动填写参数)。运行结果打印类似:
具体来讲,脚本将对列重命名,将 命名为Label,也就是选择此列为标签列。然后,进行切分,
`$demodir/feature_preprocess/out` 对应生成 train、test、valid 三个 Parquet 数据集,并将三者的行数和 `table_size_array` 保存在文件 `data_info.txt` 中(下一步可以直接使用 info 文件,不需要手动填写参数)。运行结果打印类似:

```
feature total count: 13916
Expand Down

0 comments on commit b005cd1

Please sign in to comment.