pd: document CPU-aware hot region scheduling#23140
Open
lhy1024 wants to merge 2 commits into
Open
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
ti-chi-bot
Bot
added
the
missing-translation-status
lhy1024
added
the
needs-cherry-pick-release-8.5
ti-chi-bot
Bot
added
the
size/M
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request updates the documentation across grafana-pd-dashboard.md, pd-control.md, and troubleshoot-hot-spot-issues.md to introduce CPU-aware Hot Region scheduling for read hotspots starting from v8.5.7. The changes document new metrics, fields, configuration parameters, and scheduling priorities. The reviewer's feedback focuses on improving readability, simplifying sentence structures, and adhering to the style guide by replacing passive voice with active voice.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| - Total read bytes on hot peer Regions: The total read bytes of peers that have become read hotspots on each TiKV instance | ||
| - Store read rate bytes: The total read bytes of each TiKV instance | ||
| - Store read rate keys: The total read keys of each TiKV instance | ||
| - Store read cpu: The read CPU usage of each TiKV instance, which PD uses for CPU-aware read hotspot scheduling starting from v8.5.7 |
Contributor
There was a problem hiding this comment.
To improve readability and flow, split this into two sentences and avoid the relative clause.
Suggested change
| - Store read cpu: The read CPU usage of each TiKV instance, which PD uses for CPU-aware read hotspot scheduling starting from v8.5.7 | |
| - Store read cpu: The read CPU usage of each TiKV instance. PD uses this metric for CPU-aware read hotspot scheduling starting from v8.5.7. |
| } | ||
| ``` | ||
|
|
||
| Starting from v8.5.7, `hot read` and `hot history` include `flow_cpu`, and `hot store` includes `cpu-read-rate`. These fields show read CPU usage for CPU-aware read hotspot scheduling. |
Contributor
There was a problem hiding this comment.
Clarify that these are commands to make the instructions more precise for users.
Suggested change
| Starting from v8.5.7, `hot read` and `hot history` include `flow_cpu`, and `hot store` includes `cpu-read-rate`. These fields show read CPU usage for CPU-aware read hotspot scheduling. | |
| Starting from v8.5.7, the `hot read` and `hot history` commands include `flow_cpu`, and the `hot store` command includes `cpu-read-rate`. These fields show the read CPU usage for CPU-aware read hotspot scheduling. |
| scheduler config balance-hot-region-scheduler set min-hot-query-rate 10 | ||
| ``` | ||
|
|
||
| - `min-hot-cpu-rate` means the smallest CPU usage of read requests to be counted, which is usually 10. |
Contributor
There was a problem hiding this comment.
Avoid passive voice ('to be counted') by using active voice ('to count') per the style guide.
Suggested change
| - `min-hot-cpu-rate` means the smallest CPU usage of read requests to be counted, which is usually 10. | |
| - `min-hot-cpu-rate` specifies the minimum CPU usage of read requests to count, which is usually 10. |
References
- Avoid passive voice overuse. For example, rewrite 'to be counted' to 'to count'. (link)
| ``` | ||
|
|
||
| - `byte-rate-rank-step-ratio`, `key-rate-rank-step-ratio`, `query-rate-rank-step-ratio`, and `count-rank-step-ratio` respectively mean the step ranks of byte, key, query, and count. The rank-step-ratio decides the step when the rank is calculated. `great-dec-ratio` and `minor-dec-ratio` are used to determine the `dec` rank. Usually, you do not need to modify these items. | ||
| - `byte-rate-rank-step-ratio`, `key-rate-rank-step-ratio`, `query-rate-rank-step-ratio`, `cpu-rate-rank-step-ratio`, and `count-rank-step-ratio` respectively mean the step ranks of byte, key, query, CPU, and count. The rank-step-ratio decides the step when the rank is calculated. `great-dec-ratio` and `minor-dec-ratio` are used to determine the `dec` rank. Usually, you do not need to modify these items. |
Contributor
There was a problem hiding this comment.
Avoid passive voice ('is calculated', 'are used') and improve sentence structure to make it more active and concise.
Suggested change
| - `byte-rate-rank-step-ratio`, `key-rate-rank-step-ratio`, `query-rate-rank-step-ratio`, `cpu-rate-rank-step-ratio`, and `count-rank-step-ratio` respectively mean the step ranks of byte, key, query, CPU, and count. The rank-step-ratio decides the step when the rank is calculated. `great-dec-ratio` and `minor-dec-ratio` are used to determine the `dec` rank. Usually, you do not need to modify these items. | |
| - `byte-rate-rank-step-ratio`, `key-rate-rank-step-ratio`, `query-rate-rank-step-ratio`, `cpu-rate-rank-step-ratio`, and `count-rank-step-ratio` represent the step ranks of byte, key, query, CPU, and count, respectively. The rank-step-ratio decides the step when calculating the rank. PD uses `great-dec-ratio` and `minor-dec-ratio` to determine the `dec` rank. Usually, you do not need to modify these items. |
References
- Avoid passive voice overuse. For example, rewrite 'when the rank is calculated' to 'when calculating the rank'. (link)
| > If a cluster component is earlier than v5.2, the configuration of `query` dimension does not take effect. If some components are upgraded to v5.2 or later, the `byte` and `key` dimensions still by default have the priority for hot Region scheduling. After all components of the cluster are upgraded to v5.2 or later, such a configuration still takes effect for compatibility. You can view the real-time configuration using the `pd-ctl` command. Usually, you do not need to modify these configurations. | ||
| > If a cluster component is earlier than v5.2, the configuration of the `query` dimension does not take effect. If some components are upgraded to v5.2 or later, the `byte` and `key` dimensions still by default have the priority for hot Region scheduling. After all components of the cluster are upgraded to v5.2 or later, such a configuration still takes effect for compatibility. | ||
| > | ||
| > Starting from v8.5.7, TiKV reports read CPU usage for hot Region scheduling. For clusters that support read CPU reporting, the default `read-priorities` value is `cpu,byte`. For clusters that do not support read CPU reporting, PD automatically falls back to `query,byte`, or to `byte,key` if the `query` dimension is also unsupported. You can view the real-time configuration using the `pd-ctl` command. Usually, you do not need to modify these configurations. |
Contributor
There was a problem hiding this comment.
Avoid passive voice ('is also unsupported') by using active voice ('does not support... either') per the style guide.
Suggested change
| > Starting from v8.5.7, TiKV reports read CPU usage for hot Region scheduling. For clusters that support read CPU reporting, the default `read-priorities` value is `cpu,byte`. For clusters that do not support read CPU reporting, PD automatically falls back to `query,byte`, or to `byte,key` if the `query` dimension is also unsupported. You can view the real-time configuration using the `pd-ctl` command. Usually, you do not need to modify these configurations. | |
| > Starting from v8.5.7, TiKV reports read CPU usage for hot Region scheduling. For clusters that support read CPU reporting, the default `read-priorities` value is `cpu,byte`. For clusters that do not support read CPU reporting, PD automatically falls back to `query,byte`, or to `byte,key` if the cluster does not support the `query` dimension either. You can view the real-time configuration using the `pd-ctl` command. Usually, you do not need to modify these configurations. |
References
- Avoid passive voice overuse. For example, rewrite 'is also unsupported' to 'does not support... either'. (link)
Comment on lines
+188
to
+190
| Starting from v8.5.7, PD supports CPU-aware Hot Region scheduling for read hotspots. TiKV reports per-Region read CPU usage in store heartbeats, and PD can use CPU usage as a scheduling dimension. This helps PD identify read hotspots whose QPS or byte throughput looks balanced but whose TiKV CPU usage is still uneven, such as workloads that contain queries with different CPU costs or clusters that contain TiKV nodes with different performance profiles. | ||
|
|
||
| For clusters whose TiKV version supports read CPU reporting, the default `read-priorities` value of `balance-hot-region-scheduler` is `cpu,byte`. For clusters that do not support read CPU reporting, PD automatically falls back to `query,byte`, or to `byte,key` if the `query` dimension is also unsupported. To view or adjust the scheduling dimensions, use [`pd-ctl scheduler config balance-hot-region-scheduler`](/pd-control.md#scheduler-config-balance-hot-region-scheduler). |
Contributor
There was a problem hiding this comment.
Simplify the wording to avoid unnecessary relative clauses and rewrite passive voice ('is also unsupported') to active voice per the style guide.
Suggested change
| Starting from v8.5.7, PD supports CPU-aware Hot Region scheduling for read hotspots. TiKV reports per-Region read CPU usage in store heartbeats, and PD can use CPU usage as a scheduling dimension. This helps PD identify read hotspots whose QPS or byte throughput looks balanced but whose TiKV CPU usage is still uneven, such as workloads that contain queries with different CPU costs or clusters that contain TiKV nodes with different performance profiles. | |
| For clusters whose TiKV version supports read CPU reporting, the default `read-priorities` value of `balance-hot-region-scheduler` is `cpu,byte`. For clusters that do not support read CPU reporting, PD automatically falls back to `query,byte`, or to `byte,key` if the `query` dimension is also unsupported. To view or adjust the scheduling dimensions, use [`pd-ctl scheduler config balance-hot-region-scheduler`](/pd-control.md#scheduler-config-balance-hot-region-scheduler). | |
| Starting from v8.5.7, PD supports CPU-aware Hot Region scheduling for read hotspots. TiKV reports per-Region read CPU usage in store heartbeats, and PD can use CPU usage as a scheduling dimension. This helps PD identify read hotspots whose QPS or byte throughput looks balanced but whose TiKV CPU usage is still uneven, such as workloads with different CPU-cost queries or clusters with different TiKV performance profiles. | |
| For clusters that support read CPU reporting, the default `read-priorities` value of `balance-hot-region-scheduler` is `cpu,byte`. For clusters that do not support read CPU reporting, PD automatically falls back to `query,byte`, or to `byte,key` if the cluster does not support the `query` dimension either. To view or adjust the scheduling dimensions, use [`pd-ctl scheduler config balance-hot-region-scheduler`](/pd-control.md#scheduler-config-balance-hot-region-scheduler). |
qiancai
added
v9.0-beta.3
ti-chi-bot
Bot
removed
the
missing-translation-status
github-actions Bot
pushed a commit
to doc-claw-bot/pingcap-docsite-preview
that referenced
this pull request
Jun 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What is changed, added or deleted? (Required)
Document CPU-aware Hot Region scheduling for read hotspots introduced in v8.5.7:
flow_cpuandcpu-read-rateoutput descriptions forpd-ctl hot.min-hot-cpu-rate,cpu-rate-rank-step-ratio, and CPU-awareread-prioritiesbehavior forbalance-hot-region-scheduler.Store read cpupanel description in the PD Grafana dashboard doc.Which TiDB version(s) do your changes apply to? (Required)
Need cherry-pick to
release-8.5because the feature is requested for v8.5.7.What is the related PR or file link(s)?
Do your changes match any of the following descriptions?
Which TiDB components does this PR affect?
How do you ensure that your changes are correct? (Required)
/home/lhy1024/pdand/home/lhy1024/tikvimplementation for fields, defaults, and version fallback behavior../scripts/markdownlint pd-control.md troubleshoot-hot-spot-issues.md grafana-pd-dashboard.md.git diff --check.