Update Chinese manual compaction doc (#62)

apache · Jan 24, 2024 · defe785 · defe785
1 parent 92093d2
commit defe785
Showing 1 changed file with 72 additions and 27 deletions.
diff --git a/_docs/zh/administration/manual-compact.md b/_docs/zh/administration/manual-compact.md
@@ -2,10 +2,10 @@
 permalink: administration/manual-compact
 ---
 
-注：manual compact功能从v1.8.1版本开始支持。
+注：manual compact 功能从 v1.8.1 版本开始支持。
 # 原理
 
-RocksDB除了根据需要自动触发compaction外，还能通过接口手动触发compaction，这个功能称之为[Manual Compaction](https://github.com/facebook/rocksdb/wiki/Manual-Compaction)。其提供了`CompactRange()`接口，如下：
+RocksDB 除了根据需要自动触发 compaction 外，还能通过接口手动触发 compaction，这个功能称之为 [Manual Compaction](https://github.com/facebook/rocksdb/wiki/Manual-Compaction)。其提供了 `CompactRange()` 接口，如下：
 ```C++
 // CompactRangeOptions is used by CompactRange() call.
 struct CompactRangeOptions {
@@ -49,28 +49,28 @@ virtual Status CompactRange(const CompactRangeOptions& options,
                             const Slice* begin, const Slice* end) = 0;
 ```
 
-对应地，Pegasus对该功能在上层进行了封装，提供了表级别的Manual Compact功能，其作用是：
-* 通过compaction去掉垃圾数据，减少数据量，降低文件层数，提升读操作的性能。
-* 对最高层做compaction，可以清理掉Delete标记数据。
-* 配合[Usage Scenario功能](usage-scenario)中表的bulk_load模式，可以在灌数据完成后执行一次Manual Compact，去除垃圾数据，整理数据和文件夹结构，提升读性能。
+对应地，Pegasus 对该功能在上层进行了封装，提供了表级别的 Manual Compact 功能，其作用是：
+* 通过 compaction 去掉垃圾数据，减少数据量，降低文件层数，提升读操作的性能。
+* 对最高层做 compaction，可以清理掉 Delete 标记数据。
+* 配合 [Usage Scenario 功能](usage-scenario) 中表的 bulk_load 模式，可以在灌数据完成后执行一次 Manual Compact，去除垃圾数据，整理数据和文件夹结构，提升读性能。
 
 实现方式：
-* 扩展RocksDB，在Manifest中记录上一次执行Manual Compact的时间，并提供`GetLastManualCompactFinishTime()`方法来获取该时间。
-* 利用[Table环境变量](table-env)，来设置两类Manual Compect的环境变量：
-  * 单次Manual Compact：
-    * `manual_compact.once.trigger_time`：格式为Unix时间戳的秒数，可通过shell命令`date +%s`获取当前时间戳。如果LastManualCompactFinishTime旧于该trigger_time，就触发Manual Compaction的执行。
-    * `manual_compact.once.target_level`：用于设置`CompactRangeOptions::target_level`。如果不设置，则使用默认值-1。
-    * `manual_compact.once.bottommost_level_compaction`：可设置为`skip`或者`force`。如果是`skip`，则不对最高层做compaction；如果是`force`，则强制对最高层做compaction。如果不设置，则默认为`skip`。
-  * 周期Manual Compact：
-    * `manual_compact.periodic.trigger_time`：格式为逗号分隔的时钟，譬如`3:00,21:00`，表示每一天的3:00和21:00都触发一次Manual Compaction的执行。
-    * `manual_compact.periodic.target_level`：用于设置`CompactRangeOptions::target_level`。如果不设置，则使用默认值-1。
-    * `manual_compact.periodic.bottommost_level_compaction`：可设置为`skip`或者`force`。如果是`skip`，则不对最高层做compaction；如果是`force`，则强制对最高层做compaction。如果不设置，则默认为`skip`。
-  * Manual Compact总开关：
-    * `manual_compact.disabled`(从v1.9.0版本开始支持)：如果为true，则关闭Manual Compact功能，并且取消正在执行中的Manual Compact动作。如果不设置，默认为false。
-    * `manual_compact.max_concurrent_running_count`(从v1.11.3版本开始支持)：指定最大并发数。实际上，可执行的最大并发数由`该env参数`和`服务端MANUAL_COMPACT_THRAD_POOL的线程数`共同决定，取两者的较小值。
+* 在 2.1 版本以前，Pegasus 扩展 RocksDB，并在 Manifest 中记录上一次执行 Manual Compact 的时间，并提供 `GetLastManualCompactFinishTime()` 方法来获取该时间。自 2.1 版本开始，Pegasus将该时间记录到了meta column family中，并提供了 `get_last_manual_compact_finish_time()`方法来获取。
+* 利用 [Table 环境变量](table-env)，来设置两类 Manual Compect 的环境变量：
+  * 单次 Manual Compact：
+    * `manual_compact.once.trigger_time`：格式为 Unix 时间戳的秒数，可通过 shell 命令 `date +%s` 获取当前时间戳。如果 LastManualCompactFinishTime 旧于该 trigger_time，就触发 Manual Compaction 的执行。
+    * `manual_compact.once.target_level`：用于设置 `CompactRangeOptions::target_level`。如果不设置，则使用默认值 `-1`。
+    * `manual_compact.once.bottommost_level_compaction`：可设置为 `skip` 或者 `force`。如果是 `skip`，则不对最高层做 compaction；如果是 `force`，则强制对最高层做 compaction。如果不设置，则默认为 `skip`。
+  * 周期 Manual Compact：
+    * `manual_compact.periodic.trigger_time`：格式为逗号分隔的时钟，譬如 `3:00,21:00`，表示每一天的 3:00 和 21:00 都触发一次 Manual Compaction 的执行。
+    * `manual_compact.periodic.target_level`：用于设置 `CompactRangeOptions::target_level`。如果不设置，则使用默认值 `-1`。
+    * `manual_compact.periodic.bottommost_level_compaction`：可设置为 `skip` 或者 `force`。如果是 `skip`，则不对最高层做 compaction；如果是 `force`，则强制对最高层做 compaction。如果不设置，则默认为 `skip`。
+  * Manual Compact 总开关：
+    * `manual_compact.disabled`(从 v1.9.0 版本开始支持)：如果为 true，则关闭 Manual Compact 功能，并且取消正在执行中的 Manual Compact 动作。如果不设置，默认为 false。
+    * `manual_compact.max_concurrent_running_count`(从 v1.11.3 版本开始支持)：指定最大并发数。实际上，可执行的最大并发数由该参数和服务端`MANUAL_COMPACT_THRAD_POOL`的线程数共同决定，取两者的较小值。该参数是节点级别的，如果同一时间进行 manual compaction 的表太多，则很有可能达到该最大并发数，后续该节点上的 replica 会忽略本轮 manual compaction 请求，延后执行。在日志中可以看到 `xxx ignored compact because exceed max_concurrent_running_count`
 
 注意：
-* Manual Compact功能是分派到独立的Compact线程池中执行的，每个线程同一时刻只能处理一个replica的full compaction，因为并发处理量与Compact线程池的线程数量有关，可以通过配置文件的`worker_count`进行配置，如果使用Manual Compact比较频繁，建议调大线程数量（譬如设置为cpu core数量接近）：
+* Manual Compact 功能是分派到独立的 Compact 线程池中执行的，每个线程同一时刻只能处理一个 replica 的 full compaction，因为并发处理量与 Compact 线程池的线程数量有关，可以通过配置文件的 `worker_count` 进行配置，如果使用 Manual Compact 比较频繁，建议调大线程数量（譬如设置为 cpu core 数量接近）：
   ```
   [threadpool.THREAD_POOL_COMPACT]
   name = compact
@@ -79,19 +79,22 @@ virtual Status CompactRange(const CompactRangeOptions& options,
   worker_priority = THREAD_xPRIORITY_NORMAL
   worker_count = 16
   ```
-* Manual Compact属于CPU和IO密集型操作，处理过程中会使CPU使用率长期处于高位，容易对集群的读写性能造成影响，所以**建议在流量低峰时段进行操作**。如果启动后发现读写性能下降影响了业务，可以立即通过设置该表的环境变量`manual_compact.disabled=true`来中止。
-* Manual Compact过程中可能需要较多的额外磁盘空间。因为compaction前后文件变化较大，而Pegasus一般又会保留最近3个版本的checkpoint，所以基本上额外需要的磁盘空间量大约等于执行Manual Compact的表的数据存储量。所以，在执行Manual Compact前需**确认集群有足够的存储空间**，同时在执行过程中**关注磁盘空间使用情况**，避免因为磁盘空间耗尽导致集群节点宕机，影响集群可用度。
+* Manual Compact 属于 CPU 和 IO 密集型操作，处理过程中会使 CPU 使用率长期处于高位，容易对集群的读写性能造成影响，所以 ** 建议在流量低峰时段进行操作 **。如果启动后发现读写性能下降影响了业务，可以立即通过设置该表的环境变量 `manual_compact.disabled=true` 来中止。
+* Manual Compact 过程中可能需要较多的额外磁盘空间。因为 compaction 前后文件变化较大，而 Pegasus 又会保留最近多个版本的 checkpoint，所以需要的额外磁盘空间量大约等于执行 Manual Compact 的表的数据存储量。所以，在执行 Manual Compact 前需 ** 确认集群有足够的存储空间 **，同时在执行过程中 ** 关注磁盘空间使用情况 **，避免因为磁盘空间耗尽导致集群节点宕机，影响集群可用度。
+
+
 
 # 如何设置
 
-## 通过shell设置
+## 通过 Pegasus shell 工具设置
 
-既然Manual Compact功能是利用[Table环境变量](table-env)触发的，那么可以直接通过shell功能的[set_app_envs命令](/overview/shell#set_app_envs)来设置。需要设置的环境变量参照上面的描述，环境变量设置后不会立即生效，大约需要等几十秒后才能在所有replica上生效。
+既然 Manual Compact 功能是利用 [Table 环境变量](table-env) 触发的，那么可以直接通过 shell 工具的 [set_app_envs 命令](/overview/shell#set_app_envs) 来设置，需要设置的环境变量参照上面的描述。
+> 环境变量设置后不会立即生效，大约需要等几十秒后才能在所有 replica 上生效。
 
 由于需要设置的环境变量比较多，且对数据格式有要求，所以强烈建议不要自己直接设置，而是通过我们提供的脚本工具来设置，如下所示。
 
 ## 通过脚本设置
-我们提供了一个脚本工具[scripts/pegasus_manual_compact.sh](https://github.com/apache/incubator-pegasus/blob/master/scripts/pegasus_manual_compact.sh)来方便地设置，用法：
+我们提供了一个脚本工具 [scripts/pegasus_manual_compact.sh](https://github.com/apache/incubator-pegasus/blob/master/scripts/pegasus_manual_compact.sh) 来方便地设置，用法：
 ```
 $ ./scripts/pegasus_manual_compact.sh 
 This tool is for manual compact specified table(app).
@@ -138,9 +141,51 @@ for example:
            --target_level 2 --bottommost_level_compaction force
 ```
 
-该工具不仅会调用shell命令设置Table环境变量，对于once类型还会等待所有的replica上的操作都执行完成，使用起来十分方便。
+该工具不仅会调用 shell 命令设置 Table 环境变量，对于 once 类型还会等待所有的 replica 上的操作都执行完成，使用起来十分方便。
 
-譬如，在[bulk load](usage-scenario#支持场景)完成后执行once manual compact如下：
+譬如，在 [bulk load](usage-scenario#支持场景) 完成后执行 once manual compact 如下：
 ```
 $ ./scripts/pegasus_manual_compact.sh -c 127.0.0.1:34601,127.0.0.1:34602 -a temp
 ```
+## 通过 admin-cli 设置
+
+在 **2.4.0** 之后的 Pegasus 版本还支持用 admin-cli 来设置 manual compaction 的开始并且可以方便的查看进行的进度。
+
+### 使用命令
+
+```bash
+# 开始单次 manual compaction
+Pegasus-AdminCli-1.2.0 » manual-compaction start -h
+start manual compaction for a specific table
+
+Usage:
+  start [flags]
+
+Flags:
+  -b, --bottommostLevelCompaction           bottommost level files will be compacted or not, default value is false
+  -h, --help                                display help
+  -c, --maxConcurrentRunningCount int       max concurrent running count, default value is 0, no limited (default: 0)
+  -a, --tableName                 string    table name
+  -l, --targetLevel               int       compacted files move level, default value is -1 (default: -1)
+  
+  
+# 查看 manual compaction 进度
+Pegasus-AdminCli-1.2.0 » manual-compaction query -h
+query manual compaction progress for a specific table
+
+Usage:
+  query [flags]
+
+Flags:
+  -h, --help                display help
+  -a, --tableName string    table name
+
+```
+## 补充说明
+
+Manual compaction 可与 bulk load 功能配合使用，作为批量导入大量数据后的一种优化读写性能的方式。在需要进行 bulk load 操作的表中，可将 [Usage Scenario](/administration/usage-scenario) 参数设置为 `bulk_load` 模式，以便减小导入大量数据带来的性能损耗。
+
+- 在 Bulkload 的场景下，开启manual-compaction 一般来说要比引擎层的 compaction 更灵活，因为在选择集中进行 compact 的时间可以视 Pegasus 的使用低峰来设定，并且可以通过参数主动控制并发度。
+- Bulkload 开启后会将 Usage Scenario 参数变为`bulk_load`，在这种模式下，我们会禁止引擎层的 compaction，因为`bulk_load`模式下会在 level0 层堆积大量的 sst 文件，如果不关闭引擎 compact 会消耗大量 IO 并且对读非常不友好。
+- 写延迟比较容易被磁盘 IO 瓶颈影响。compact 本质是归并排序磁盘，需要把数据先读到内存中进行排序，然后再写，涉及 2 两次 IO，是一个对磁盘 IO 负载很重的操作，因此会增加一定写延迟。但我们可以灵活的设置 manual-compaction 的并发度，逐个磁盘进行，将影响控制在可接受范围内。
+