tools/lightning: update lightning docs

tools/lightning/deployment.md

@@ -34,7 +34,7 @@ category: tools
 - `tikv-importer`
 
     - 32+ 逻辑核 CPU
-    - 32 GB+ 内存
+    - 40 GB+ 内存
     - 1 TB+ SSD 硬盘，IOPS 越高越好（要求 ≥8000）
       * 硬盘必须大于最大的 N 个表的大小总和，其中 N = max(index-concurrency, table-concurrency)。
     - 使用万兆网卡，带宽需 300 MB/s 以上
@@ -44,7 +44,9 @@ category: tools
 
 > **注意：**
 >
-> `tidb-lightning` 是 CPU 密集型程序，如果和其它程序混合部署，需要通过 `region-concurrency` 限制 `tidb-lightning` 的 CPU 实际占用核数，否则会影响其他程序的正常运行。建议将混合部署机器上 75% 的 CPU 分配给 `tidb-lightning`。例如，机器为 32 核，则 `tidb-lightning` 的 `region-concurrency` 可设为 24。
+> - `tidb-lightning` 是 CPU 密集型程序，如果和其它程序混合部署，需要通过 `region-concurrency` 限制 `tidb-lightning` 的 CPU 实际占用核数，否则会影响其他程序的正常运行。建议将混合部署机器上 75% 的 CPU 分配给 `tidb-lightning`。例如，机器为 32 核，则 `tidb-lightning` 的 `region-concurrency` 可设为 24。
+>
+> - `tikv-importer` 将中间数据存储缓存到内存上以加速导入过程。占用内存大小可以通过 **(`max-open-engines` × `write-buffer-size` × 2) + (`num-import-jobs` × `region-split-size` × 2)** 计算得来。如果磁盘写入速度慢，缓存可能会带来更大的内存占用。
 
 此外，目标 TiKV 集群必须有足够空间接收新导入的数据。除了[标准硬件配置](../../op-guide/recommendation.md)以外，目标 TiKV 集群的总存储空间必须大于 **数据源大小 × [副本数量](../../FAQ.md#3-2-6-%E6%AF%8F%E4%B8%AA-region-%E7%9A%84-replica-%E6%95%B0%E9%87%8F%E5%8F%AF%E9%85%8D%E7%BD%AE%E5%90%97-%E8%B0%83%E6%95%B4%E7%9A%84%E6%96%B9%E6%B3%95%E6%98%AF) × 2**。例如集群默认使用 3 副本，那么总存储空间需为数据源大小的 6 倍以上。
 
@@ -155,7 +157,7 @@ TiDB-Lightning 可随 TiDB 集群一起用 [Ansible 部署](../../op-guide/ansib
 
 通过以下链接获取 TiDB-Lightning 安装包（需选择与集群相同的版本）：
 
-- **v2.1.6**: https://download.pingcap.org/tidb-v2.1.6-linux-amd64.tar.gz
+- **v2.1.9**: https://download.pingcap.org/tidb-v2.1.9-linux-amd64.tar.gz
 - **v2.0.9**: https://download.pingcap.org/tidb-lightning-v2.0.9-linux-amd64.tar.gz
 - 最新 unstable 版本：https://download.pingcap.org/tidb-lightning-test-xx-latest-linux-amd64.tar.gz
 
@@ -201,7 +203,11 @@ TiDB-Lightning 可随 TiDB 集群一起用 [Ansible 部署](../../op-guide/ansib
     # 第 0 层的算法用于压缩 KV 数据。
     # 第 6 层的算法用于压缩 SST 文件。
     # 第 1 至 5 层的算法目前忽略。
-    compression-per-level = ["lz4", "no", "no", "no", "no", "no", "zstd"]
+    compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"]
+
+    [rocksdb.writecf]
+    # (同上)
+    compression-per-level = ["lz4", "no", "no", "no", "no", "no", "lz4"]
 
     [import]
     # 存储引擎文档 (engine file) 的文件夹路径。
@@ -218,6 +224,11 @@ TiDB-Lightning 可随 TiDB 集群一起用 [Ansible 部署](../../op-guide/ansib
     #stream-channel-window = 128
     # 引擎文档同时打开的最大数量。
     max-open-engines = 8
+    # Importer 上传至 TiKV 的最大速度 (bytes per second)。
+    #upload-speed-limit = "512MB"
+    # 目标 store 可用空间的最小比率：store_available_space / store_capacity.
+    # 如果目标存储空间的可用比率低于下值，Importer 将会暂停上传 SST 来为 PD 提供足够时间进行 regions 负载均衡。
+    min-available-ratio = 0.05
     ```
 
 3. 运行 `tikv-importer`。
@@ -249,7 +260,7 @@ TiDB-Lightning 可随 TiDB 集群一起用 [Ansible 部署](../../op-guide/ansib
     # 这两项设置控制同时处理每种引擎的最大数量。设置会影响 tikv-importer 的内存和
     # 磁盘用量。两项数值之和不能超过 tikv-importer 的 max-open-engines 的设定。
     index-concurrency = 2
-    table-concurrency = 8
+    table-concurrency = 6
 
     # 转换数据的并发数，默认为逻辑 CPU 数量，不需要配置。
     # 混合部署的情况下可以配置为逻辑 CPU 的 75% 大小。

tools/lightning/errors.md

@@ -40,7 +40,12 @@ Lightning 的正常速度为每条线程每 2 分钟导入一个 256 MB 的数
 
 **解决办法**：
 
-1. 使用 `tidb-lightning-ctl --error-checkpoint-destroy=all` 把出错的表删除，然后重启 Lightning 重新导入那些表。
+1. 使用 `tidb-lightning-ctl` 把出错的表删除，然后重启 Lightning 重新导入那些表。
+
+    ```sh
+    tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all
+    ```
+
 2. 把断点存放在外部数据库（修改 `[checkpoint] dsn`），减轻目标集群压力。
 
 ## Checkpoint for … has invalid status: 18
@@ -49,7 +54,11 @@ Lightning 的正常速度为每条线程每 2 分钟导入一个 256 MB 的数
 
 **解决办法**:
 
-如果错误原因是非法数据源，使用 `tidb-lightning-ctl --error-checkpoint-destroy=all` 删除已导入数据，并重启 Lightning。
+如果错误原因是非法数据源，使用 `tidb-lightning-ctl` 删除已导入数据，并重启 Lightning。
+
+    ```sh
+    tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all
+    ```
 
 其他解决方法请参考[断点续传的控制](../../tools/lightning/checkpoints.md#断点续传的控制)。
 
@@ -59,13 +68,17 @@ Lightning 的正常速度为每条线程每 2 分钟导入一个 256 MB 的数
 
 **解决办法**：
 
-1. 提高 `tikv-importer.toml` 内 `max-open-engine` 的值。这个设置主要由内存决定，计算公式为：
+1. 提高 `tikv-importer.toml` 内 `max-open-engines` 的值。这个设置主要由内存决定，计算公式为：
+
+    最大内存使用量 ≈ `max-open-engines` × `write-buffer-size` × `max-write-buffer-number`
 
-    最大内存使用量 ≈ `max-open-engine` × `write-buffer-size` × `max-write-buffer-number`
+2. 降低 `table-concurrency` + `index-concurrency`，使之低于 `max-open-engines`。
 
-2. 降低 `table-concurrency` + `index-concurrency`，使之低于 `max-open-engine`。
+3. 重启 `tikv-importer` 来强制移除所有引擎文件 (默认值为 `./data.import/`)。这样也会丢弃导入了一半的表，所以启动 Lightning 前必须清除过期的断点记录：
 
-3. 重启 `tikv-importer` 来强制移除所有引擎文件。这样也会丢弃导入了一半的表，所以启动 Lightning 前必须使用 `tidb-lightning-ctl --error-checkpoint-destroy=all`。
+    ```sh
+    tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all
+    ```
 
 ## cannot guess encoding for input file, please convert to UTF-8 manually
 

tools/lightning/monitor.md

@@ -5,7 +5,7 @@ category: tools
 
 # TiDB-Lightning 监控告警
 
-TiDB-Lightning 支持给 [Prometheus](https://prometheus.io/) 采集监控指标 (metrics)。本文主要介绍 TiDB-Lightning 的监控配置与监控指标。
+`tidb-lightning` 和 `tikv-importer` 都支持使用 [Prometheus](https://prometheus.io/) 采集监控指标 (metrics)。本文主要介绍 TiDB-Lightning 的监控配置与监控指标。
 
 ## 监控配置
 
@@ -55,30 +55,70 @@ scrape_configs:
 
 ## 监控指标
 
-本节详细描述 `tikv-importer` 和 `tidb-lightning` 的监控指标。
+本节将详细描述 `tikv-importer` 和 `tidb-lightning` 的监控指标。
 
 ### `tikv-importer`
 
 `tikv-importer` 的监控指标皆以 `tikv_import_*` 为前缀。
 
 - **`tikv_import_rpc_duration`**（直方图）
 
-    导入 RPC 需时的直方图。标签：
+    完成一次 RPC 操作所需时的直方图。标签：
 
-    - **request**：RPC 名称，如 `open_engine`、`import_engine` 等
+    - **request**：`switch_mode` / `open_engine` / `write_engine` / `close_engine` / `import_engine` / `cleanup_engine` / `compact_cluster` / `upload` / `ingest` / `compact`
     - **result**：`ok` / `error`
 
 - **`tikv_import_write_chunk_bytes`**（直方图）
 
-    从 `tidb-lightning` 写入每个区块大小的直方图。
+    从 Lightning 接收的 KV 对区块大小（未压缩）的直方图。
 
 - **`tikv_import_write_chunk_duration`**（直方图）
 
-    从 `tidb-lightning` 写入每个区块需时直方图。
+    从 `tidb-lightning` 接收每个 KV 对区块需时直方图。
 
 - **`tikv_import_upload_chunk_bytes`**（直方图）
 
-    上传到 TiKV 的每个区块大小的直方图。
+     上传到 TiKV 的每个 SST 文件区块大小（压缩）的直方图。
+
+- **`tikv_import_range_delivery_duration`** (直方图)
+
+    将一个 range 的 KV 对发送至 `dispatch-job` 任务需时的直方图。
+
+- **`tikv_import_split_sst_duration`** (直方图)
+
+    将 range 从引擎文件中分离到单个 SST 文件中需时的直方图。
+
+- **`tikv_import_sst_delivery_duration`** (直方图)
+
+    将 SST 文件从 `dispatch-job` 任务发送到 `ImportSSTJob`任务需时的直方图
+
+- **`tikv_import_sst_recv_duration`** (直方图)
+
+    `ImportSSTJob`任务接收从 `dispatch-job` 任务发送过来的 SST 文件需时的直方图。
+
+- **`tikv_import_sst_upload_duration`** (直方图)
+
+    从 `ImportSSTJob` 任务上传 SST 文件到 TiKV 节点需时的直方图。
+
+- **`tikv_import_sst_chunk_bytes`** (直方图)
+
+    上传到 TiKV 节点的 SST 文件（压缩）大小的直方图。
+
+- **`tikv_import_sst_ingest_duration`** (直方图)
+
+    将 SST 文件传入至 TiKV 需时的直方图。
+
+- **`tikv_import_each_phase`** (测量仪)
+
+    表示运行阶段。值为 1 时表示在阶段内运行，值为 0 时表示在阶段内运行。标签：
+
+    - **phase**: `prepare` / `import`
+
+- **`tikv_import_wait_store_available_count`** (计数器)
+
+    计算出现 TiKV 节点没有充足空间上传 SST 文件现象的次数。标签：
+
+    - **store_id**: TiKV 存储 ID。
 
 - **`tikv_import_upload_chunk_duration`**（直方图）
 
@@ -90,15 +130,15 @@ scrape_configs:
 
 - **`lightning_importer_engine`**（计数器）
 
-    计算已开启及关闭的引擎文档数量。标签：
+    计算已开启及关闭的引擎文件数量。标签：
 
     - **type**：`open` / `closed`
 
-- **`lightning_idle_workers`**（测量仪）
+- **`lightning_idle_workers`**（计量表盘）
 
-    计算闲置的工作流程。数值应低于设置中的 `*-concurrency` 的值，且经常为 0。标签：
+    计算闲置的 worker。数值应低于设置中的 `*-concurrency` 的值，且经常为 0。标签：
 
-    - **name**：`table` / `region` / `io`
+    - **name**: `table` / `index` / `region` / `io` / `closed-engine`
 
 - **`lightning_kv_encoder`**（计数器）
 
@@ -113,6 +153,13 @@ scrape_configs:
     - **state**：`pending` / `written` / `closed` / `imported` / `altered_auto_inc` / `checksum` / `analyzed` / `completed`
     - **result**：`success` / `failure`
 
+**`lightning_engines`** (计数器)
+
+    计算处理后引擎文件的数量以及其状态。标签：
+
+    - **state**: `pending` / `written` / `closed` / `imported` / `completed`
+    - **result**: `success` / `failure`
+
 - **`lightning_chunks`**（计数器）
 
     计算处理过的 Chunks 及其状态。标签：
@@ -123,40 +170,36 @@ scrape_configs:
 
     导入每个表需时的直方图。
 
-- **`lightning_block_read_seconds`**（直方图）
-
-    读取每个 SQL 区块需时的直方图。
+- **`lightning_row_read_bytes`**（直方图）
 
-- **`lightning_block_read_bytes`**（直方图）
+    单行 SQL 数据大小的直方图。
 
-    每个 SQL 区块大小的直方图。
+- **`lightning_row_encode_seconds`**（直方图）
 
-- **`lightning_block_encode_seconds`**（直方图）
+    解码单行 SQL 数据到 KV 对需时的直方图。
 
-    每个 SQL 区块转换成 KV 对需时的直方图。
+- **`lightning_row_kv_deliver_seconds`**（直方图）
 
+    发送一组与单行 SQL 数据对应的 KV 对需时的直方图。
+
 - **`lightning_block_deliver_seconds`**（直方图）
 
-    每个 KV 对区块传送到 `tikv-importer` 需时的直方图。
+    每个 KV 对中的区块传送到 `tikv-importer` 需时的直方图。
 
 - **`lightning_block_deliver_bytes`**（直方图）
 
-    每个 KV 对区块大小的直方图。
+    发送到 Importer 的 KV 对中区块（未压缩）的大小的直方图。
 
 - **`lightning_chunk_parser_read_block_seconds`**（直方图）
 
-    解析每个 SQL 区块需时的直方图。
-
-- **`lightning_chunk_parser_read_row_seconds`**（直方图）
-
-    解析每行 SQL 需时的直方图。
+    数据文件解析每个 SQL 区块需时的直方图。
 
 - **`lightning_checksum_seconds`**（直方图）
 
-    计算校验和（Checksum）需时的直方图。
+    计算表中 Checksum 需时的直方图。
 
 - **`lightning_apply_worker_seconds`**（直方图）
 
-    获取闲置工作流程等待时间的直方图。标签：
+    获取闲置 worker 等待时间的直方图。标签：
 
-    - **name**: `table` / `region` / `io`
+    - **name**: `table` / `index` / `region` / `io` / `closed-engine`