From ae98164469269f976605735adabfa41e89709bc5 Mon Sep 17 00:00:00 2001 From: hhwyt Date: Wed, 7 Jan 2026 17:08:18 +0800 Subject: [PATCH 1/4] tikv-configuration-file: update flow-control override behavior for v8.5.5 Update documentation for storage.flow-control.l0-files-threshold and storage.flow-control.soft-pending-compaction-bytes-limit to reflect the behavior change introduced in TiKV PR #18994. - v8.5.4 and earlier: flow-control config unconditionally overrides the corresponding RocksDB config. - From v8.5.5: flow-control config only overrides when it is smaller than the RocksDB config, to avoid weakening RocksDB's compaction acceleration mechanism when increasing flow-control thresholds. Also update the corresponding RocksDB config items (level0-slowdown-writes-trigger, soft-pending-compaction-bytes-limit) with the same version-specific behavior notes. --- tikv-configuration-file.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 009c90bb4043..86cee2e8c621 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -564,12 +564,16 @@ RocksDB 多个 CF 之间共享 block cache 的配置选项。 ### `l0-files-threshold` -+ 当 KvDB 的 L0 文件个数达到该阈值时，流控机制开始工作。当 `enable` 的值为 `true` 时，会覆盖 `rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`的配置。 ++ 当 KvDB 的 L0 文件个数达到该阈值时，流控机制开始工作。 ++ v8.5.4 及之前版本：当 `enable` 的值为 `true` 时，该配置会直接覆盖 `rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`。 ++ 从 v8.5.5 起：当 `enable` 的值为 `true` 时，仅当 `storage.flow-control.l0-files-threshold` 小于 `rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger` 时才覆盖该 RocksDB 配置项，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。 + 默认值：20 ### `soft-pending-compaction-bytes-limit` -+ 当 KvDB 的 pending compaction bytes 达到该阈值时，流控机制开始拒绝部分写入请求，报错 `ServerIsBusy`。当 `enable` 的值为 `true` 时，会覆盖 `rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit` 的配置。 ++ 当 KvDB 的 pending compaction bytes 达到该阈值时，流控机制开始拒绝部分写入请求，报错 `ServerIsBusy`。 ++ v8.5.4 及之前版本：当 `enable` 的值为 `true` 时，该配置会直接覆盖 `rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit`。 ++ 从 v8.5.5 起：当 `enable` 的值为 `true` 时，仅当 `storage.flow-control.soft-pending-compaction-bytes-limit` 小于 `rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit` 时才覆盖该 RocksDB 配置项，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。 + 默认值："192GiB" ### `hard-pending-compaction-bytes-limit` @@ -1636,7 +1640,9 @@ rocksdb defaultcf、rocksdb writecf 和 rocksdb lockcf 相关的配置项。 ### `level0-slowdown-writes-trigger` -+ 触发 write stall 的 L0 文件最大个数。当 `storage.flow-control.enable` 的值为 `true` 时，`storage.flow-control.l0-files-threshold` 会覆盖此配置。 ++ 触发 write stall 的 L0 文件最大个数。 ++ v8.5.4 及之前版本：当 `storage.flow-control.enable` 的值为 `true` 时，该配置项会被 `storage.flow-control.l0-files-threshold` 直接覆盖。 ++ 从 v8.5.5 起：当 `storage.flow-control.enable` 的值为 `true` 时，如果本配置项的值大于 `storage.flow-control.l0-files-threshold`，则本配置项会被 `storage.flow-control.l0-files-threshold` 覆盖；否则保持本配置不变。 + 默认值：20 + 最小值：0 @@ -1693,7 +1699,9 @@ rocksdb defaultcf、rocksdb writecf 和 rocksdb lockcf 相关的配置项。 ### `soft-pending-compaction-bytes-limit` -+ pending compaction bytes 的软限制。当 `storage.flow-control.enable` 的值为 `true` 时，`storage.flow-control.soft-pending-compaction-bytes-limit` 会覆盖此配置。 ++ pending compaction bytes 的软限制。 ++ v8.5.4 及之前版本：当 `storage.flow-control.enable` 的值为 `true` 时，该配置项会被 `storage.flow-control.soft-pending-compaction-bytes-limit` 直接覆盖。 ++ 从 v8.5.5 起：当 `storage.flow-control.enable` 的值为 `true` 时，如果本配置项的值大于 `storage.flow-control.soft-pending-compaction-bytes-limit`，则本配置项会被 `storage.flow-control.soft-pending-compaction-bytes-limit` 覆盖；否则保持本配置不变。 + 默认值：192GiB + 单位：KiB|MiB|GiB From 8f9cb206b08ab702cce9525fe83bd2efedee7aaa Mon Sep 17 00:00:00 2001 From: hhwyt Date: Fri, 9 Jan 2026 18:28:48 +0800 Subject: [PATCH 2/4] docs: refactor flow-control config description per review comment Use reference-based approach to avoid duplication: - In flow-control config items, use brief note block to reference RocksDB config items - In RocksDB config items, keep detailed version-specific behavior with links This makes future version logic changes easier to maintain (only 2 places instead of 4). Signed-off-by: hhwyt --- tikv-configuration-file.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 86cee2e8c621..148ca4a2a0b7 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -565,15 +565,19 @@ RocksDB 多个 CF 之间共享 block cache 的配置选项。 ### `l0-files-threshold` + 当 KvDB 的 L0 文件个数达到该阈值时，流控机制开始工作。 -+ v8.5.4 及之前版本：当 `enable` 的值为 `true` 时，该配置会直接覆盖 `rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`。 -+ 从 v8.5.5 起：当 `enable` 的值为 `true` 时，仅当 `storage.flow-control.l0-files-threshold` 小于 `rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger` 时才覆盖该 RocksDB 配置项，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。 + + > **注意**： + > + > 当满足一定条件时，`rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger` 的值会被该配置项覆盖。详细参考 [`rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`](/tikv-configuration-file.md#level0-slowdown-writes-trigger)。 + 默认值：20 ### `soft-pending-compaction-bytes-limit` + 当 KvDB 的 pending compaction bytes 达到该阈值时，流控机制开始拒绝部分写入请求，报错 `ServerIsBusy`。 -+ v8.5.4 及之前版本：当 `enable` 的值为 `true` 时，该配置会直接覆盖 `rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit`。 -+ 从 v8.5.5 起：当 `enable` 的值为 `true` 时，仅当 `storage.flow-control.soft-pending-compaction-bytes-limit` 小于 `rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit` 时才覆盖该 RocksDB 配置项，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。 + + > **注意**： + > + > 当满足一定条件时，`rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit` 的值会被该配置项覆盖。详细参考 [`rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit`](/tikv-configuration-file.md#soft-pending-compaction-bytes-limit-1)。 + 默认值："192GiB" ### `hard-pending-compaction-bytes-limit` @@ -1641,8 +1645,8 @@ rocksdb defaultcf、rocksdb writecf 和 rocksdb lockcf 相关的配置项。 ### `level0-slowdown-writes-trigger` + 触发 write stall 的 L0 文件最大个数。 -+ v8.5.4 及之前版本：当 `storage.flow-control.enable` 的值为 `true` 时，该配置项会被 `storage.flow-control.l0-files-threshold` 直接覆盖。 -+ 从 v8.5.5 起：当 `storage.flow-control.enable` 的值为 `true` 时，如果本配置项的值大于 `storage.flow-control.l0-files-threshold`，则本配置项会被 `storage.flow-control.l0-files-threshold` 覆盖；否则保持本配置不变。 ++ v8.5.4 及之前版本：当开启流控机制（[`storage.flow-control.enable`](/tikv-configuration-file.md#enable) 为 `true`）时，该配置项会被 [`storage.flow-control.l0-files-threshold`](/tikv-configuration-file.md#l0-files-threshold) 直接覆盖。 ++ 从 v8.5.5 和 v9.0.0 起：当开启流控机制（[`storage.flow-control.enable`](/tikv-configuration-file.md#enable) 为 `true`）时，该配置项仅在其值大于 [`storage.flow-control.l0-files-threshold`](/tikv-configuration-file.md#l0-files-threshold) 时会被 `storage.flow-control.l0-files-threshold` 覆盖，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。 + 默认值：20 + 最小值：0 @@ -1700,8 +1704,8 @@ rocksdb defaultcf、rocksdb writecf 和 rocksdb lockcf 相关的配置项。 ### `soft-pending-compaction-bytes-limit` + pending compaction bytes 的软限制。 -+ v8.5.4 及之前版本：当 `storage.flow-control.enable` 的值为 `true` 时，该配置项会被 `storage.flow-control.soft-pending-compaction-bytes-limit` 直接覆盖。 -+ 从 v8.5.5 起：当 `storage.flow-control.enable` 的值为 `true` 时，如果本配置项的值大于 `storage.flow-control.soft-pending-compaction-bytes-limit`，则本配置项会被 `storage.flow-control.soft-pending-compaction-bytes-limit` 覆盖；否则保持本配置不变。 ++ v8.5.4 及之前版本：当开启流控机制（[`storage.flow-control.enable`](/tikv-configuration-file.md#enable) 为 `true`）时，该配置项会被 [`storage.flow-control.soft-pending-compaction-bytes-limit`](/tikv-configuration-file.md#soft-pending-compaction-bytes-limit) 直接覆盖。 ++ 从 v8.5.5 和 v9.0.0 起：当开启流控机制（[`storage.flow-control.enable`](/tikv-configuration-file.md#enable) 为 `true`）时，该配置项仅在其值大于 [`storage.flow-control.soft-pending-compaction-bytes-limit`](/tikv-configuration-file.md#soft-pending-compaction-bytes-limit) 时会被 `storage.flow-control.soft-pending-compaction-bytes-limit` 覆盖，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。 + 默认值：192GiB + 单位：KiB|MiB|GiB From 3d7eebd13a942550b9b7cf6e96cf5a625b8b0336 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 9 Jan 2026 18:46:04 +0800 Subject: [PATCH 3/4] add empty lines to meet markdown lint requirements --- tikv-configuration-file.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 148ca4a2a0b7..372664ee7e3f 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -568,7 +568,8 @@ RocksDB 多个 CF 之间共享 block cache 的配置选项。 > **注意**： > - > 当满足一定条件时，`rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger` 的值会被该配置项覆盖。详细参考 [`rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`](/tikv-configuration-file.md#level0-slowdown-writes-trigger)。 + > 当满足一定条件时，`rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger` 的值会被该配置项覆盖。详情参考 [`rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`](/tikv-configuration-file.md#level0-slowdown-writes-trigger)。 + + 默认值：20 ### `soft-pending-compaction-bytes-limit` @@ -577,7 +578,8 @@ RocksDB 多个 CF 之间共享 block cache 的配置选项。 > **注意**： > - > 当满足一定条件时，`rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit` 的值会被该配置项覆盖。详细参考 [`rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit`](/tikv-configuration-file.md#soft-pending-compaction-bytes-limit-1)。 + > 当满足一定条件时，`rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit` 的值会被该配置项覆盖。详情参考 [`rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit`](/tikv-configuration-file.md#soft-pending-compaction-bytes-limit-1)。 + + 默认值："192GiB" ### `hard-pending-compaction-bytes-limit` From 3a2ce1bb266a64126a7826b28226cd7449852528 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 12 Jan 2026 10:58:09 +0800 Subject: [PATCH 4/4] rocksdb.(defaultcf|writecf|lockcf) -> rocksdb.(defaultcf|writecf|lockcf|raftcf) --- tikv-configuration-file.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 372664ee7e3f..573bc5187e13 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -568,7 +568,7 @@ RocksDB 多个 CF 之间共享 block cache 的配置选项。 > **注意**： > - > 当满足一定条件时，`rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger` 的值会被该配置项覆盖。详情参考 [`rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`](/tikv-configuration-file.md#level0-slowdown-writes-trigger)。 + > 当满足一定条件时，`rocksdb.(defaultcf|writecf|lockcf|raftcf).level0-slowdown-writes-trigger` 的值会被该配置项覆盖。详情参考 [`rocksdb.(defaultcf|writecf|lockcf|raftcf).level0-slowdown-writes-trigger`](/tikv-configuration-file.md#level0-slowdown-writes-trigger)。 + 默认值：20 @@ -578,7 +578,7 @@ RocksDB 多个 CF 之间共享 block cache 的配置选项。 > **注意**： > - > 当满足一定条件时，`rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit` 的值会被该配置项覆盖。详情参考 [`rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit`](/tikv-configuration-file.md#soft-pending-compaction-bytes-limit-1)。 + > 当满足一定条件时，`rocksdb.(defaultcf|writecf|lockcf|raftcf).soft-pending-compaction-bytes-limit` 的值会被该配置项覆盖。详情参考 [`rocksdb.(defaultcf|writecf|lockcf|raftcf).soft-pending-compaction-bytes-limit`](/tikv-configuration-file.md#soft-pending-compaction-bytes-limit-1)。 + 默认值："192GiB"