master: document CPU-aware hot region scheduling

grafana-pd-dashboard.md

@@ -87,6 +87,7 @@ summary: PD 重要监控指标详解：使用 TiUP 部署 TiDB 集群时，一
 - Total read bytes on hot peer Regions：每个 TiKV 实例上所有成为读取热点的 peer 的总的读取流量大小
 - Store read rate bytes：每个 TiKV 实例总的读取的流量
 - Store read rate keys：每个 TiKV 实例总的读取 keys
+- Store read cpu：每个 TiKV 实例的读 CPU 使用量。从 v8.5.7 和 v9.0.0 开始，PD 将该指标用于基于 CPU 使用情况的读热点调度。
 - Hot cache read entry number：每个 TiKV 实例进入热点统计模块的 peer 的数量
 
 ![PD Dashboard - Hot read metrics](/media/pd-dashboard-hotread-v4.png)

pd-control.md

@@ -609,6 +609,7 @@ hot history 1629294000000 1631980800000
       "hot_region_type": "read",
       "hot_degree": 152,
       "flow_bytes": 0,
+      "flow_cpu": 32,
       "key_rate": 0,
       "query_rate": 305,
       "start_key": "7480000000000000FF5300000000000000F8",
@@ -638,6 +639,7 @@ hot history 1629294000000 1631980800000 hot_region_type read region_id 1,2,3 sto
       "hot_region_type": "read",
       "hot_degree": 152,
       "flow_bytes": 0,
+      "flow_cpu": 32,
       "key_rate": 0,
       "query_rate": 305,
       "start_key": "7480000000000000FF5300000000000000F8",
@@ -648,6 +650,8 @@ hot history 1629294000000 1631980800000 hot_region_type read region_id 1,2,3 sto
 }
 ```
 
+从 v8.5.7 和 v9.0.0 开始，`hot read` 和 `hot history` 命令的输出中会显示 `flow_cpu` 字段，`hot store` 命令的输出中会显示 `cpu-read-rate` 字段。这些字段展示了读 CPU 使用情况，用于基于 CPU 使用情况的读热点调度。
+
 ### `label [store <name> <value>]`
 
 用于显示集群标签信息。示例如下。
@@ -1242,22 +1246,24 @@ scheduler config balance-hot-region-scheduler  // 显示 balance-hot-region 调
   "min-hot-byte-rate": 100,
   "min-hot-key-rate": 10,
   "min-hot-query-rate": 10,
+  "min-hot-cpu-rate": 10,
   "max-zombie-rounds": 3,
   "max-peer-number": 1000,
   "byte-rate-rank-step-ratio": 0.05,
   "key-rate-rank-step-ratio": 0.05,
   "query-rate-rank-step-ratio": 0.05,
+  "cpu-rate-rank-step-ratio": 0.05,
   "count-rank-step-ratio": 0.01,
   "great-dec-ratio": 0.95,
   "minor-dec-ratio": 0.99,
   "src-tolerance-ratio": 1.05,
   "dst-tolerance-ratio": 1.05,
   "read-priorities": [
-    "query",
+    "cpu",
     "byte"
   ],
   "write-leader-priorities": [
-    "key",
+    "query",
     "byte"
   ],
   "write-peer-priorities": [
@@ -1288,6 +1294,12 @@ scheduler config balance-hot-region-scheduler  // 显示 balance-hot-region 调
     scheduler config balance-hot-region-scheduler set min-hot-query-rate 10
     ```
 
+- `min-hot-cpu-rate` 指要计数的读请求最小 CPU 使用量。该值的单位为单个 CPU 核的百分比，默认值通常为 `10`，即单个 CPU 核的 10%。
+
+    ```bash
+    scheduler config balance-hot-region-scheduler set min-hot-cpu-rate 10
+    ```
+
 - `max-zombie-rounds` 指一个 operator 可被纳入 pending influence 所允许的最大心跳次数。如果将它设置为更大的值，更多的 operator 可能会被纳入 pending influence。通常用户不需要修改这个值。pending influence 指的是在调度中产生的、但仍生效的影响。
 
     ```bash
@@ -1300,7 +1312,7 @@ scheduler config balance-hot-region-scheduler  // 显示 balance-hot-region 调
     scheduler config balance-hot-region-scheduler set max-peer-number 1000
     ```
 
-- `byte-rate-rank-step-ratio`、`key-rate-rank-step-ratio`、`query-rate-rank-step-ratio` 和 `count-rank-step-ratio` 分别控制 byte、key、query 和 count 的 step ranks。rank-step-ratio 决定了计算 rank 时的 step 值。`great-dec-ratio` 和 `minor-dec-ratio` 控制 `dec` 的 rank。通常用户不需要修改这些配置项。
+- `byte-rate-rank-step-ratio`、`key-rate-rank-step-ratio`、`query-rate-rank-step-ratio`、`cpu-rate-rank-step-ratio` 和 `count-rank-step-ratio` 分别表示 byte、key、query、CPU 和 count 的 step ranks。rank-step-ratio 决定了计算 rank 时的 step 值。PD 使用 `great-dec-ratio` 和 `minor-dec-ratio` 来确定 `dec` 的 rank。通常用户不需要修改这些配置项。
 
     ```bash
     scheduler config balance-hot-region-scheduler set byte-rate-rank-step-ratio 0.05
@@ -1314,15 +1326,18 @@ scheduler config balance-hot-region-scheduler  // 显示 balance-hot-region 调
 
 - `read-priorities`、`write-leader-priorities` 和 `write-peer-priorities` 用于控制调度器优先从哪些维度进行热点均衡，支持配置两个维度。
 
-    - `read-priorities` 和 `write-leader-priorities` 用于控制调度器在处理 read 和 write-leader 类型的热点时优先均衡的维度，可选的维度有 `query`、`byte` 和 `key`。
+    - `read-priorities` 用于控制调度器在处理 read 类型的热点时优先均衡的维度，可选的维度有 `cpu`、`query`、`byte` 和 `key`。
+    - `write-leader-priorities` 用于控制调度器在处理 write-leader 类型的热点时优先均衡的维度，可选的维度有 `query`、`byte` 和 `key`。
     - `write-peer-priorities` 用于控制调度器在处理 write-peer 类型的热点时优先均衡的维度，支持配置 `byte` 和 `key` 维度。
 
     > **注意：**
     >
-    > 若集群的所有组件未全部升级到 v5.2 及以上版本，`query` 维度的配置不生效，部分组件升级完成后调度器仍默认优先从 `byte` 和 `key` 维度进行热点均衡，集群的所有组件全部升级完成后，也会继续保持这样的兼容配置，可通过 `pd-ctl` 查看实时配置。通常用户不需要修改这些配置项。
+    > 若集群中存在版本低于 v5.2 的组件，`query` 维度的配置不生效。当将部分组件升级到 v5.2 或更高版本后，调度器仍默认优先从 `byte` 和 `key` 维度进行热点均衡。当将集群中的所有组件全部升级到 v5.2 或更高版本后，调度器也会继续保持这样的兼容配置。
+    >
+    > 从 v8.5.7 和 v9.0.0 开始，TiKV 会上报用于热点 Region 调度的读 CPU 使用量。对于支持读 CPU 上报的集群，默认的 `read-priorities` 值为 `cpu,byte`。对于不支持读 CPU 上报的集群，PD 会自动回退到 `query,byte`；如果集群也不支持 `query` 维度，则回退到 `byte,key`。可通过 `pd-ctl` 查看实时配置。通常用户不需要修改这些配置项。
 
     ```bash
-    scheduler config balance-hot-region-scheduler set read-priorities query,byte
+    scheduler config balance-hot-region-scheduler set read-priorities cpu,byte
     ```
 
 - `strict-picking-store` 是控制热点调度搜索空间的开关，通常为打开。该配置项仅影响 `rank-formula-version` 为 `v1` 时的行为。当打开时，热点调度的目标是保证所配置的两个维度的热点均衡。当关闭后，热点调度只保证处于第一优先级的维度的热点均衡表现更好，但可能会导致其他维度的热点不再那么均衡。通常用户不需要修改这个配置项。

troubleshoot-hot-spot-issues.md

@@ -175,7 +175,16 @@ TiDB 的 Coprocessor Cache 功能支持下推计算结果缓存。开启该功
 
 ## 打散读热点
 
-在读热点场景中，热点 TiKV 无法及时处理读请求，导致读请求排队。但是，此时并非所有 TiKV 资源都已耗尽。为了降低延迟，TiDB v7.1.0 引入了负载自适应副本读取功能，允许从其他 TiKV 节点读取副本，而无需在热点 TiKV 节点排队等待。你可以通过 [`tidb_load_based_replica_read_threshold`](/system-variables.md#tidb_load_based_replica_read_threshold-从-v700-版本开始引入) 系统变量控制读请求的排队长度。当 leader 节点的预估排队时间超过该阈值时，TiDB 会优先从 follower 节点读取数据。在读热点的情况下，与不打散读热点相比，该功能可提高读取吞吐量 70%～200%。
+在读热点场景中，热点 TiKV 无法及时处理读请求，导致读请求排队。但是，此时并非所有 TiKV 资源都已耗尽。为了降低延时，TiDB v7.1.0 引入了负载自适应副本读取功能，允许从其他 TiKV 节点读取副本，而无需在热点 TiKV 节点排队等待。你可以通过 [`tidb_load_based_replica_read_threshold`](/system-variables.md#tidb_load_based_replica_read_threshold-从-v700-版本开始引入) 系统变量控制读请求的排队长度。当 leader 节点的预估排队时间超过该阈值时，TiDB 会优先从 follower 节点读取数据。在读热点的情况下，与不打散读热点相比，该功能可提高读取吞吐量 70%～200%。
+
+###  基于 TiKV CPU 使用情况的热点 Region 调度
+
+从 v8.5.7 和 v9.0.0 开始，针对读热点，PD 支持基于 TiKV CPU 使用情况的热点 Region 调度。TiKV 在 Store 心跳中上报热点 Region 的读 CPU 使用情况，PD 可将 CPU 使用情况作为调度维度之一。该机制有助于 PD 识别出那些 QPS 或字节吞吐量看似均衡、但 TiKV CPU 使用量仍不均衡的读热点，例如包含不同 CPU 开销的负载，或不同 TiKV 节点处理不同负载模式的集群。
+
+- 对于支持上报读 CPU 使用情况的集群，`balance-hot-region-scheduler` 的默认 `read-priorities` 值为 `cpu,byte`。
+- 对于不支持上报读 CPU 使用情况的集群，PD 会自动回退到 `query,byte`；如果集群也不支持 `query` 维度，则回退到 `byte,key`。
+
+如需查看或调整调度维度，请使用 [`pd-ctl scheduler config balance-hot-region-scheduler`](/pd-control.md#scheduler-config-balance-hot-region-scheduler)。
 
 ## 使用 TiKV MVCC 内存引擎缓解因多版本导致的读热点