br: acceleration of snapshot restore speed (#16740)

br/br-snapshot-guide.md

@@ -62,6 +62,12 @@ tiup br validate decode --field="end-version" \
 
 ## 恢复快照备份数据
 
+> **注意：**
+>
+> - 在 BR v7.5.0 及之前版本中，每个 TiKV 节点的快照恢复速度约为 100 MiB/s。
+> - 从 BR v7.6.0 开始，为了解决大规模 Region 场景下可能出现的恢复瓶颈问题，BR 支持通过粗粒度打散 Region 的算法加速恢复（实验特性）。可以通过指定命令行参数 `--granularity="coarse-grained"` 来启用此功能。
+> - 从 BR v8.0.0 版本开始，通过粗粒度打散 Region 算法进行快照恢复的功能正式 GA，并默认启用。通过采用粗粒度打散 Region 算法、批量创建库表、降低 SST 文件下载和 Ingest 操作之间的相互影响、加速表统计信息恢复等改进措施，快照恢复的速度有大幅提升。在实际案例中，快照恢复的 SST 文件下载速度最高提升约 10 倍，单个 TiKV 节点的数据恢复速度稳定在 1.2 GiB/s，端到端的恢复速度大约提升 1.5 到 3 倍，并且能够在 1 小时内完成对 100 TiB 数据的恢复。
+
 如果你需要恢复备份的快照数据，则可以使用 `br restore full`。该命令的详细使用帮助可以通过执行 `br restore full --help` 查看。
 
 将[上文备份的快照数据](#对集群进行快照备份)恢复到目标集群：
@@ -71,12 +77,6 @@ tiup br restore full --pd "${PD_IP}:2379" \
 --storage "s3://backup-101/snapshot-202209081330?access-key=${access-key}&secret-access-key=${secret-access-key}"
 ```
 
-> **警告：**
->
-> 通过设置 `--granularity="coarse-grained"` 参数启用粗粒度打散 Region 算法加速恢复为实验特性，建议在表数量不超过 1,000 的集群中使用此功能加速数据恢复。请注意，该功能暂不支持断点恢复。
-
-为进一步提升大集群的恢复速度，BR 从 v7.6.0 开始支持通过设置 `--granularity="coarse-grained"` 参数启用粗粒度打散 Region 算法（实验特性）进行更快的并行恢复。启用后，BR 可以迅速将恢复任务拆分为大量小任务，并批量分散到所有 TiKV 节点上，从而充分利用每个 TiKV 节点的所有资源，实现并行快速恢复。
-
 在恢复快照备份数据过程中，终端会显示恢复进度条。在完成恢复后，会输出恢复耗时、速度、恢复数据大小等信息。
 
 ```shell
@@ -205,7 +205,7 @@ TiDB 备份功能对集群性能（事务延迟和 QPS）有一定的影响，
 
 - TiDB 恢复的时候会尽可能打满 TiKV CPU、磁盘 IO、网络带宽等资源，所以推荐在空的集群上执行备份数据的恢复，避免对正在运行的业务产生影响。
 - 备份数据的恢复速度与集群配置、部署、运行的业务都有比较大的关系。在内部多场景仿真测试中，单 TiKV 存储节点上备份数据恢复速度能够达到 100 MiB/s。在不同用户场景下，快照恢复的性能和影响应以实际测试结论为准。
-- 从 v7.6.0 开始，BR 提供了一个实验性特性，允许通过指定命令行参数 `--granularity="coarse-grained"` 启用粗粒度的 Region 打散算法，加快大规模 Region 场景下的 Region 恢复速度。在这个方式下每个 TiKV 节点会得到均匀稳定的下载任务，从而充分利用每个 TiKV 节点的所有资源实现并行快速恢复。在实际案例中，大规模 Region 场景下，集群快照恢复速度最高提升约 10 倍。使用示例如下：
+- BR 提供了粗粒度的 Region 打散算法，用于提升大规模 Region 场景下的 Region 恢复速度。该算法通过命令行参数 `--granularity="coarse-grained"` 控制，并默认启用。在这个方式下每个 TiKV 节点会得到均匀稳定的下载任务，从而充分利用每个 TiKV 节点的所有资源实现并行快速恢复。在实际案例中，大规模 Region 场景下，集群快照恢复速度最高提升约 3 倍。使用示例如下：
 
     ```bash
     br restore full \
@@ -217,6 +217,13 @@ TiDB 备份功能对集群性能（事务延迟和 QPS）有一定的影响，
     --log-file restorefull.log
     ```
 
+- 从 v8.0.0 起，`br` 命令行工具新增 `--tikv-max-restore-concurrency` 参数，用于控制每个 TiKV 节点的最大 download 和 ingest 文件数量。此外，通过调整此参数，可以控制作业队列的最大长度（作业队列的最大长度 = 32 \* TiKV 节点数量 \* `--tikv-max-restore-concurrency`），进而控制 BR 节点的内存消耗。
+
+    通常情况下，`--tikv-max-restore-concurrency` 会根据集群配置自动调整，无需手动设置。如果通过 Grafana 中的 **TiKV-Details** > **Backup & Import** > **Import RPC count** 监控指标发现 download 文件数量长时间接近于 0，而 ingest 文件数量一直处于上限时，说明 ingest 文件任务存在堆积，并且作业队列已达到最大长度。此时，可以采取以下措施来缓解任务堆积问题：
+
+    - 设置 `--ratelimit` 参数来限制下载速度，以确保 ingest 文件任务有足够的资源。例如，当任意 TiKV 节点的硬盘吞吐量为 `x MiB/s` 且下载备份文件的网络带宽大于 `x/2 MiB/s`，可以设置参数 `--ratelimit x/2`。如果任意 TiKV 节点的硬盘吞吐量为 `x MiB/s` 且下载备份文件的网络带宽小于或等于 `x/2 MiB/s`，可以不设置参数 `--ratelimit`。
+    - 调高 `--tikv-max-restore-concurrency` 来增加作业队列的最大长度。
+
 ## 探索更多
 
 * [TiDB 集群备份与恢复实践示例](/br/backup-and-restore-use-cases.md)

system-variables.md

@@ -1790,7 +1790,7 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1;
 - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
 - 类型：布尔型
 - 默认值：`ON`
-- 这个变量用来控制 TiDB 是否支持并发 HashAgg 进行落盘。当该变量设置为 `ON` 时，并发 HashAgg 将支持落盘。该变量将在功能正式发布时废弃。
+- 这个变量用来控制 TiDB 是否支持并发 HashAgg 进行落盘。当该变量设置为 `ON` 时，并发 HashAgg 将支持落盘。该变量将在功能正式发布后废弃。
 
 ### `tidb_enable_ddl` <span class="version-mark">从 v6.3.0 版本开始引入</span>