From a4295f454b0412e3d4a243cf63b98cc88e47b267 Mon Sep 17 00:00:00 2001 From: Yang Zhang Date: Wed, 10 Dec 2025 14:03:40 -0800 Subject: [PATCH 1/8] Add unified.cpu-threshold config Signed-off-by: Yang Zhang --- tikv-configuration-file.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 84a578de8c166..1c786de410e15 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -320,6 +320,12 @@ Configuration items related to the single thread pool serving read requests. Thi + Controls whether to automatically adjust the thread pool size. When it is enabled, the read performance of TiKV is optimized by automatically adjusting the UnifyReadPool thread pool size based on the current CPU usage. The possible range of the thread pool is `[max-thread-count, MAX(4, CPU)]`. The maximum value is the same as the one of [`max-thread-count`](#max-thread-count). + Default value: `false` +### `cpu-threshold` New in v8.5.5 + ++ Determines the highest CPU utilization permitted for the unified read pool; setting it to 0 disables this constraint and relies solely on the busy thread scaling algorithm, while a value greater than 0 imposes CPU threshold checks on top of thread scaling, specifically by forcing a scale-down when CPU usage exceeds the threshold plus a 10% leeway, and preventing a scale-up when that action would push usage past the threshold minus a 10% leeway, thereby ensuring the read pool, for example at a setting of 0.8, does not consume more than 80% of available CPU resources. ++ Default value: `0.0` ++ Value range: `[0.0, 1.0]` + ## readpool.storage Configuration items related to storage thread pool. From 901294e9c2be1803054ef0cf3dbf75b187c016bd Mon Sep 17 00:00:00 2001 From: Yang Zhang Date: Wed, 10 Dec 2025 14:08:38 -0800 Subject: [PATCH 2/8] 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 | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 1c786de410e15..4767d468dc8b4 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -322,7 +322,14 @@ Configuration items related to the single thread pool serving read requests. Thi ### `cpu-threshold` New in v8.5.5 -+ Determines the highest CPU utilization permitted for the unified read pool; setting it to 0 disables this constraint and relies solely on the busy thread scaling algorithm, while a value greater than 0 imposes CPU threshold checks on top of thread scaling, specifically by forcing a scale-down when CPU usage exceeds the threshold plus a 10% leeway, and preventing a scale-up when that action would push usage past the threshold minus a 10% leeway, thereby ensuring the read pool, for example at a setting of 0.8, does not consume more than 80% of available CPU resources. ++ Specifies the CPU utilization threshold for the unified read pool. + + - If this parameter is set to `0` (the default), this constraint is disabled, and thread pool scaling is determined solely by the busy thread scaling algorithm. + - If this parameter is set to a value greater than `0`, CPU threshold checks are imposed on top of thread scaling: + - A scale-down is forced when CPU usage exceeds the threshold plus a 10% leeway. + - A scale-up is prevented if it would cause CPU usage to exceed the threshold minus a 10% leeway. + + For example, setting this parameter to `0.8` ensures that the unified read pool does not consume more than 80% of the available CPU resources. + Default value: `0.0` + Value range: `[0.0, 1.0]` From ba40fb7ea627b93b0b3f6a64cba2c2ef08f5af6b Mon Sep 17 00:00:00 2001 From: Yang Zhang Date: Wed, 10 Dec 2025 15:27:40 -0800 Subject: [PATCH 3/8] Resolve comment Signed-off-by: Yang Zhang --- tikv-configuration-file.md | 1 + 1 file changed, 1 insertion(+) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 4767d468dc8b4..3a8b6fe4de301 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -330,6 +330,7 @@ Configuration items related to the single thread pool serving read requests. Thi - A scale-up is prevented if it would cause CPU usage to exceed the threshold minus a 10% leeway. For example, setting this parameter to `0.8` ensures that the unified read pool does not consume more than 80% of the available CPU resources. ++ This feature is active only when [`readpool.unified.auto-adjust-pool-size`](#auto-adjust-pool-size-new-in-v630) is set to `true`. + Default value: `0.0` + Value range: `[0.0, 1.0]` From 79ca4eee170a5304aff45b4b14d994f63063bb86 Mon Sep 17 00:00:00 2001 From: Yang Zhang Date: Wed, 17 Dec 2025 00:11:02 -0800 Subject: [PATCH 4/8] Update tikv-configuration-file.md Co-authored-by: Grace Cai --- 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 3a8b6fe4de301..18c768e017b37 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -320,7 +320,7 @@ Configuration items related to the single thread pool serving read requests. Thi + Controls whether to automatically adjust the thread pool size. When it is enabled, the read performance of TiKV is optimized by automatically adjusting the UnifyReadPool thread pool size based on the current CPU usage. The possible range of the thread pool is `[max-thread-count, MAX(4, CPU)]`. The maximum value is the same as the one of [`max-thread-count`](#max-thread-count). + Default value: `false` -### `cpu-threshold` New in v8.5.5 +### `cpu-threshold` New in v8.5.5 and v9.0.0 + Specifies the CPU utilization threshold for the unified read pool. From 294995905aa8042bee72f9811ff384eb95a9a53d Mon Sep 17 00:00:00 2001 From: Yang Zhang Date: Wed, 17 Dec 2025 23:51:17 -0800 Subject: [PATCH 5/8] Update tikv-configuration-file.md Co-authored-by: Grace Cai --- 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 18c768e017b37..80d797e6712fc 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -330,7 +330,7 @@ Configuration items related to the single thread pool serving read requests. Thi - A scale-up is prevented if it would cause CPU usage to exceed the threshold minus a 10% leeway. For example, setting this parameter to `0.8` ensures that the unified read pool does not consume more than 80% of the available CPU resources. -+ This feature is active only when [`readpool.unified.auto-adjust-pool-size`](#auto-adjust-pool-size-new-in-v630) is set to `true`. ++ This feature takes effect only when [`readpool.unified.auto-adjust-pool-size`](#auto-adjust-pool-size-new-in-v630) is set to `true`. + Default value: `0.0` + Value range: `[0.0, 1.0]` From fb1049b8a9bb0f09729bea4eb86dbe74e0d5a34e Mon Sep 17 00:00:00 2001 From: Yang Zhang Date: Wed, 17 Dec 2025 23:51:26 -0800 Subject: [PATCH 6/8] Update tikv-configuration-file.md Co-authored-by: Grace Cai --- 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 80d797e6712fc..886f0bc3a3b54 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -322,7 +322,7 @@ Configuration items related to the single thread pool serving read requests. Thi ### `cpu-threshold` New in v8.5.5 and v9.0.0 -+ Specifies the CPU utilization threshold for the unified read pool. ++ Specifies the CPU utilization threshold for the unified read pool. For example, when this value is set to `0.8`, the thread pool can use up to 80% of the CPU. - If this parameter is set to `0` (the default), this constraint is disabled, and thread pool scaling is determined solely by the busy thread scaling algorithm. - If this parameter is set to a value greater than `0`, CPU threshold checks are imposed on top of thread scaling: From c2dc68a797d7a40d363268314aa764af8328139b Mon Sep 17 00:00:00 2001 From: Yang Zhang Date: Wed, 17 Dec 2025 23:51:55 -0800 Subject: [PATCH 7/8] Update tikv-configuration-file.md Co-authored-by: Grace Cai --- tikv-configuration-file.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 886f0bc3a3b54..4c2f90226aab2 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -324,10 +324,10 @@ Configuration items related to the single thread pool serving read requests. Thi + Specifies the CPU utilization threshold for the unified read pool. For example, when this value is set to `0.8`, the thread pool can use up to 80% of the CPU. - - If this parameter is set to `0` (the default), this constraint is disabled, and thread pool scaling is determined solely by the busy thread scaling algorithm. - - If this parameter is set to a value greater than `0`, CPU threshold checks are imposed on top of thread scaling: - - A scale-down is forced when CPU usage exceeds the threshold plus a 10% leeway. - - A scale-up is prevented if it would cause CPU usage to exceed the threshold minus a 10% leeway. + + By default (when it is `0.0`), there is no limit on the CPU usage of UnifyReadPool. The size of the thread pool is determined solely by the busy thread scaling algorithm, which adjusts the size dynamically based on the number of threads handling current tasks. + + If it is set to a value greater than `0.0`, TiKV introduces the following CPU usage threshold constraints on top of the existing busy-thread scaling algorithm to control CPU resource usage more strictly: + + **Forced scale-down**: when the CPU usage of the unified read pool exceeds the configured value plus a 10% buffer, TiKV forcibly reduces the size of the pool. + + **Scale-up prevention**: when expanding the unified read pool would cause CPU usage to exceed the configured threshold minus a 10% buffer, TiKV prevents the unified read pool from further expanding. For example, setting this parameter to `0.8` ensures that the unified read pool does not consume more than 80% of the available CPU resources. + This feature takes effect only when [`readpool.unified.auto-adjust-pool-size`](#auto-adjust-pool-size-new-in-v630) is set to `true`. From 2a72ea1673de123c07344e54c74a64c0b2694711 Mon Sep 17 00:00:00 2001 From: Yang Zhang Date: Wed, 17 Dec 2025 23:52:06 -0800 Subject: [PATCH 8/8] Update tikv-configuration-file.md Co-authored-by: Grace Cai --- tikv-configuration-file.md | 1 - 1 file changed, 1 deletion(-) diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 4c2f90226aab2..114f958bf6e00 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -329,7 +329,6 @@ Configuration items related to the single thread pool serving read requests. Thi + **Forced scale-down**: when the CPU usage of the unified read pool exceeds the configured value plus a 10% buffer, TiKV forcibly reduces the size of the pool. + **Scale-up prevention**: when expanding the unified read pool would cause CPU usage to exceed the configured threshold minus a 10% buffer, TiKV prevents the unified read pool from further expanding. - For example, setting this parameter to `0.8` ensures that the unified read pool does not consume more than 80% of the available CPU resources. + This feature takes effect only when [`readpool.unified.auto-adjust-pool-size`](#auto-adjust-pool-size-new-in-v630) is set to `true`. + Default value: `0.0` + Value range: `[0.0, 1.0]`