This is an automated email from the ASF dual-hosted git repository.
laiyingchun pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-pegasus-website.git
The following commit(s) were added to refs/heads/master by this push:
new f134816f update manual compact zh (#94)
f134816f is described below
commit f134816f17001475162c2d1ee412529959dc34c5
Author: ninsmiracle <110282526+ninsmira...@users.noreply.github.com>
AuthorDate: Sat Mar 22 09:37:55 2025 +0800
update manual compact zh (#94)
Co-authored-by: guoningshen <guonings...@xiaomi.com>
---
_docs/zh/administration/manual-compact.md | 65 +++++++++++++++++++++++--------
1 file changed, 48 insertions(+), 17 deletions(-)
diff --git a/_docs/zh/administration/manual-compact.md
b/_docs/zh/administration/manual-compact.md
index dd667e37..9e1aec7b 100644
--- a/_docs/zh/administration/manual-compact.md
+++ b/_docs/zh/administration/manual-compact.md
@@ -3,9 +3,22 @@ permalink: administration/manual-compact
---
注：manual compact 功能从 v1.8.1 版本开始支持。
+
+# 功能作用
+
+Pegasus 在RocksDB提供的 [Manual
Compaction](https://github.com/facebook/rocksdb/wiki/Manual-Compaction)功能上层进行了封装，提供了表级别的
Manual Compact 功能，其作用是：
+
+1. 通过 compaction 去掉垃圾数据，减少数据量，降低文件层数，提升读操作的性能。
+
+2. 对最高层做 compaction，可以清理掉 Delete 标记数据。
+
+3. 配合 [Usage Scenario 功能](usage-scenario) 中表的 bulk_load 模式，可以在灌数据完成后执行一次
Manual Compact，去除垃圾数据，整理数据和文件夹结构，提升读性能。
+
+
+
# 原理
-RocksDB 除了根据需要自动触发 compaction 外，还能通过接口手动触发 compaction，这个功能称之为 [Manual
Compaction](https://github.com/facebook/rocksdb/wiki/Manual-Compaction)。其提供了
`CompactRange()` 接口，如下：
+RocksDB 除了根据需要自动触发 compaction 外，还能通过接口手动触发 compaction。RocksDB提供了
`CompactRange()` 接口，如下：
```C++
// CompactRangeOptions is used by CompactRange() call.
struct CompactRangeOptions {
@@ -49,25 +62,34 @@ 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，去除垃圾数据，整理数据和文件夹结构，提升读性能。
-实现方式：
+
+### 实现方式
+
* 在 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：
+
+
+
+* Pegasus的表级Manual Compect主要利用 [Table 环境变量](table-env)来配置具体的Manual
Compect的策略，Table环境变量中主要有3种关于Manual Compaction的参数。下面将具体的介绍这些参数：
+
+ * 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策略参数：
* `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策略参数：
* `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 数量接近）：
@@ -79,8 +101,8 @@ 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 又会保留最近多个版本的
checkpoint，所以需要的额外磁盘空间量大约等于执行 Manual Compact 的表的数据存储量。所以，在执行 Manual Compact 前需
** 确认集群有足够的存储空间 **，同时在执行过程中 ** 关注磁盘空间使用情况 **，避免因为磁盘空间耗尽导致集群节点宕机，影响集群可用度。
+* Manual Compact 属于 CPU 和 IO 密集型操作，处理过程中会使 CPU 使用率长期处于高位，容易对集群的读写性能造成影响，所以
**建议在流量低峰时段进行操作**。如果启动后发现读写性能下降影响了业务，可以立即通过设置该表的环境变量
`manual_compact.disabled=true` 来中止。
+* Manual Compact 过程中可能需要较多的额外磁盘空间。因为 compaction 前后文件变化较大，而 Pegasus 又会保留最近多个版本的
checkpoint，所以需要的额外磁盘空间量大约等于执行 Manual Compact 的表的数据存储量。所以，在执行 Manual Compact 前需
**确认集群有足够的存储空间**，同时在执行过程中 **关注磁盘空间使用情况**，避免因为磁盘空间耗尽导致集群节点宕机，影响集群可用度。
@@ -147,14 +169,16 @@ for example:
```
$ ./scripts/pegasus_manual_compact.sh -c 127.0.0.1:34601,127.0.0.1:34602 -a
temp
```
-## 通过 admin-cli 设置
+
+
+## 通过 admin-cli 设置（推荐）
在 **2.4.0** 之后的 Pegasus 版本还支持用 admin-cli 来设置 manual compaction
的开始并且可以方便的查看进行的进度。
### 使用命令
```bash
-# 开始单次 manual compaction
+# 开始单次 某张表manual compaction的使用案例
Pegasus-AdminCli-1.2.0 » manual-compaction start -h
start manual compaction for a specific table
@@ -167,7 +191,12 @@ Flags:
-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 start -a test
+Table test start manual compaction succeed
+
# 查看 manual compaction 进度
Pegasus-AdminCli-1.2.0 » manual-compaction query -h
@@ -181,6 +210,8 @@ Flags:
-a, --tableName string table name
```
+
+
## 补充说明
Manual compaction 可与 bulk load 功能配合使用，作为批量导入大量数据后的一种优化读写性能的方式。在需要进行 bulk load
操作的表中，可将 [Usage Scenario](/administration/usage-scenario) 参数设置为 `bulk_load`
模式，以便减小导入大量数据带来的性能损耗。
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@pegasus.apache.org
For additional commands, e-mail: commits-h...@pegasus.apache.org
