From 1e3ffcb0147208b7a598859f311ff2e9909dea7b Mon Sep 17 00:00:00 2001 From: rishabh mittal Date: Wed, 10 Jun 2026 16:13:11 -0700 Subject: [PATCH 1/6] tikv config: document new resource-control configs for v8.5.6 Add 11 new configuration parameters to the resource-control section introduced by TiKV PRs cherry-picked into the v8.5.6 release: - bg-cpu-throttle-threshold / fg-cpu-throttle-threshold (CPU throttling) - bg-compaction-pressure-threshold / bg-write-io-ceiling / bg-write-io-floor (I/O throttling) - enable-fair-scheduling / enable-read-admission-control / enable-write-admission-control - historical-usage-window-mins / baseline-burst-pct / admission-max-delayed-count --- tikv-configuration-file.md | 62 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 593d5e7d2989d..efc89d70e5fd9 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -2692,6 +2692,68 @@ Specifies the flow control strategy for low-priority tasks. TiKV ensures that hi + `conservative`: this policy prioritizes ensuring that system resources are fully utilized, allowing low-priority tasks to fully utilize system available resources as needed, and therefore has a greater performance impact on high-priority tasks. + Default value: `moderate`. +### `bg-cpu-throttle-threshold` New in v8.5.6 and v9.0.0 + ++ Specifies the CPU utilization percentage threshold at which background task throttling begins. When CPU utilization reaches this value, TiKV starts to reduce the resource budget allocated to background tasks (such as compaction and garbage collection). The background task budget scales linearly from full down to zero as CPU utilization increases from this threshold toward [`fg-cpu-throttle-threshold`](#fg-cpu-throttle-threshold). ++ Default value: `60.0` ++ Unit: percentage (%) + +### `fg-cpu-throttle-threshold` New in v8.5.6 and v9.0.0 + ++ Specifies the CPU utilization percentage threshold above which foreground traffic protection is fully activated. When CPU utilization reaches this value, background tasks are completely throttled to their minimum floor and the background utilization budget is capped at this value. This threshold must be greater than [`bg-cpu-throttle-threshold`](#bg-cpu-throttle-threshold). ++ Default value: `70.0` ++ Unit: percentage (%) + +### `bg-compaction-pressure-threshold` New in v8.5.6 and v9.0.0 + ++ Specifies the compaction pending bytes ratio threshold at which background write I/O throttling begins. Below this threshold, background write I/O ramps up toward [`bg-write-io-ceiling`](#bg-write-io-ceiling). At or above this threshold, background write I/O scales linearly down toward [`bg-write-io-floor`](#bg-write-io-floor) as compaction pressure approaches 100%. ++ Default value: `70.0` ++ Unit: percentage (%) + +### `bg-write-io-ceiling` New in v8.5.6 and v9.0.0 + ++ Specifies the maximum write I/O rate allowed for background tasks when compaction pressure is below [`bg-compaction-pressure-threshold`](#bg-compaction-pressure-threshold). ++ Default value: `"100GB"` ++ Unit: bytes per second + +### `bg-write-io-floor` New in v8.5.6 and v9.0.0 + ++ Specifies the minimum write I/O rate guaranteed to background tasks even at maximum compaction pressure. This floor prevents background tasks from being starved completely. ++ Default value: `"10MB"` ++ Unit: bytes per second + +### `enable-fair-scheduling` New in v8.5.6 and v9.0.0 + ++ Controls whether to enable two-phase RU-based fair scheduling for read requests. When enabled, resource groups whose current RU consumption rate exceeds their historical baseline are placed in a lower-priority phase in the unified read pool queue, protecting sustained workloads from traffic spikes without hard-rejecting requests. ++ Default value: `false` + +### `enable-read-admission-control` New in v8.5.6 and v9.0.0 + ++ Controls whether to enable admission control for read requests. When enabled, read requests from over-baseline resource groups are delayed or rejected with `SchedTooBusy` when CPU utilization exceeds [`fg-cpu-throttle-threshold`](#fg-cpu-throttle-threshold). This configuration takes effect only when [`enable-fair-scheduling`](#enable-fair-scheduling) is also enabled. ++ Default value: `false` + +### `enable-write-admission-control` New in v8.5.6 and v9.0.0 + ++ Controls whether to enable admission control for write requests. When enabled, write requests from over-baseline resource groups are delayed or rejected with `SchedTooBusy` when CPU utilization exceeds [`fg-cpu-throttle-threshold`](#fg-cpu-throttle-threshold). This configuration takes effect only when [`enable-fair-scheduling`](#enable-fair-scheduling) is also enabled. ++ Default value: `false` + +### `historical-usage-window-mins` New in v8.5.6 and v9.0.0 + ++ Specifies the size of the sliding time window (in minutes) used to compute per-resource-group historical RU baselines. A larger window smooths out short-term bursts, while a smaller window makes the baseline more responsive to recent usage. Valid range: `2`–`60`. **Modifying this configuration item requires a TiKV restart to take effect.** ++ Default value: `15` ++ Unit: minutes + +### `baseline-burst-pct` New in v8.5.6 and v9.0.0 + ++ Specifies the percentage of headroom above a resource group's historical RU baseline before the group is considered "over baseline." For example, a value of `20.0` means a group must exceed 1.2× its historical RU rate to be deprioritized by fair scheduling or limited by admission control. ++ Default value: `20.0` ++ Unit: percentage (%) + +### `admission-max-delayed-count` New in v8.5.6 and v9.0.0 + ++ Specifies the maximum number of requests that can be concurrently held in admission control delay (reads and writes combined). When this limit is reached, additional over-baseline requests are rejected immediately rather than delayed. Set to `0` for unlimited concurrent delays. ++ Default value: `10000` + ## split Configuration items related to [Load Base Split](/configure-load-base-split.md). From eebd83f1f451bf24dd51071fa8c727eb754b8b1f Mon Sep 17 00:00:00 2001 From: rishabh mittal Date: Wed, 10 Jun 2026 16:29:25 -0700 Subject: [PATCH 2/6] tikv config: fix bg-cpu-throttle-threshold description - Floor is 1 CPU core, not zero (per worker.rs:304-309) - Clarify 'background tasks' links to resource control background task types (import, br, ddl, stats) not internal compaction/GC --- tikv-configuration-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index efc89d70e5fd9..8d61e7d9eeabb 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -2694,7 +2694,7 @@ Specifies the flow control strategy for low-priority tasks. TiKV ensures that hi ### `bg-cpu-throttle-threshold` New in v8.5.6 and v9.0.0 -+ Specifies the CPU utilization percentage threshold at which background task throttling begins. When CPU utilization reaches this value, TiKV starts to reduce the resource budget allocated to background tasks (such as compaction and garbage collection). The background task budget scales linearly from full down to zero as CPU utilization increases from this threshold toward [`fg-cpu-throttle-threshold`](#fg-cpu-throttle-threshold). ++ Specifies the CPU utilization percentage threshold at which background task throttling begins. Background tasks are tasks marked with a background resource group, including `import`, `br`, `ddl`, and `stats` task types (see [Background task types](/tidb-resource-control-background-tasks.md#background-parameters)). When CPU utilization reaches this value, TiKV starts to reduce the resource budget allocated to background tasks. The budget scales linearly from the configured limit down to a minimum floor of 1 CPU core as CPU utilization increases from this threshold toward [`fg-cpu-throttle-threshold`](#fg-cpu-throttle-threshold). + Default value: `60.0` + Unit: percentage (%) From 5aaa8d8876997b3ad797de0724a67accf82efb42 Mon Sep 17 00:00:00 2001 From: mittalrishabh Date: Wed, 10 Jun 2026 16:40:06 -0700 Subject: [PATCH 3/6] Update tikv-configuration-file.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- tikv-configuration-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 8d61e7d9eeabb..4f34355553095 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -2751,7 +2751,7 @@ Specifies the flow control strategy for low-priority tasks. TiKV ensures that hi ### `admission-max-delayed-count` New in v8.5.6 and v9.0.0 -+ Specifies the maximum number of requests that can be concurrently held in admission control delay (reads and writes combined). When this limit is reached, additional over-baseline requests are rejected immediately rather than delayed. Set to `0` for unlimited concurrent delays. ++ Specifies the maximum number of concurrent requests (reads and writes combined) that TiKV can hold in the admission control delay. When this limit is reached, TiKV rejects additional over-baseline requests immediately instead of delaying them. Set this value to `0` for unlimited concurrent delays. + Default value: `10000` ## split From 1c2916166d40a26b87bf9318e6d75ada60a393e3 Mon Sep 17 00:00:00 2001 From: mittalrishabh Date: Wed, 10 Jun 2026 16:40:36 -0700 Subject: [PATCH 4/6] Update tikv-configuration-file.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- tikv-configuration-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 4f34355553095..04fb1bfd00f52 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -2745,7 +2745,7 @@ Specifies the flow control strategy for low-priority tasks. TiKV ensures that hi ### `baseline-burst-pct` New in v8.5.6 and v9.0.0 -+ Specifies the percentage of headroom above a resource group's historical RU baseline before the group is considered "over baseline." For example, a value of `20.0` means a group must exceed 1.2× its historical RU rate to be deprioritized by fair scheduling or limited by admission control. ++ Specifies the percentage of headroom above a resource group's historical RU baseline before TiKV considers the group "over baseline." For example, if you set this value to `20.0`, a resource group must exceed 1.2× its historical RU rate before fair scheduling deprioritizes it or admission control limits it. + Default value: `20.0` + Unit: percentage (%) From 6339c3304e241fc87a082bd409a2c65fad1a2935 Mon Sep 17 00:00:00 2001 From: mittalrishabh Date: Wed, 10 Jun 2026 16:41:11 -0700 Subject: [PATCH 5/6] Update tikv-configuration-file.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- tikv-configuration-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 04fb1bfd00f52..8bc14df4b1e08 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -2739,7 +2739,7 @@ Specifies the flow control strategy for low-priority tasks. TiKV ensures that hi ### `historical-usage-window-mins` New in v8.5.6 and v9.0.0 -+ Specifies the size of the sliding time window (in minutes) used to compute per-resource-group historical RU baselines. A larger window smooths out short-term bursts, while a smaller window makes the baseline more responsive to recent usage. Valid range: `2`–`60`. **Modifying this configuration item requires a TiKV restart to take effect.** ++ Specifies the size of the sliding time window (in minutes) that TiKV uses to compute per-resource-group historical RU baselines. A larger window smooths out short-term bursts, while a smaller window makes the baseline more responsive to recent usage. Valid range: `2-60`. **You must restart TiKV for changes to this configuration to take effect.** + Default value: `15` + Unit: minutes From 13045379941bbc3b1e680d1b105f6ab9c2de643d Mon Sep 17 00:00:00 2001 From: rishabh mittal Date: Wed, 10 Jun 2026 17:03:11 -0700 Subject: [PATCH 6/6] tikv config: clarify bg-compaction-pressure-threshold is % of soft-pending-compaction-bytes-limit --- tikv-configuration-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 8bc14df4b1e08..d50652f14fda9 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -2706,7 +2706,7 @@ Specifies the flow control strategy for low-priority tasks. TiKV ensures that hi ### `bg-compaction-pressure-threshold` New in v8.5.6 and v9.0.0 -+ Specifies the compaction pending bytes ratio threshold at which background write I/O throttling begins. Below this threshold, background write I/O ramps up toward [`bg-write-io-ceiling`](#bg-write-io-ceiling). At or above this threshold, background write I/O scales linearly down toward [`bg-write-io-floor`](#bg-write-io-floor) as compaction pressure approaches 100%. ++ Specifies the threshold, as a percentage of [`storage.flow-control.soft-pending-compaction-bytes-limit`](#soft-pending-compaction-bytes-limit), at which background write I/O throttling begins. Below this threshold, background write I/O increases toward [`bg-write-io-ceiling`](#bg-write-io-ceiling). At or above this threshold, TiKV scales background write I/O linearly down toward [`bg-write-io-floor`](#bg-write-io-floor) as compaction pressure approaches 100%. + Default value: `70.0` + Unit: percentage (%)