tidb-cloud: add Top RU user guide (web console, Premium + Essential)#22989
tidb-cloud: add Top RU user guide (web console, Premium + Essential)#22989huoyao1125 wants to merge 3 commits into
Conversation
ti-chi-bot
Bot
added
the
first-time-contributor
|
[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
missing-translation-status
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new documentation page for the "Top RU" feature in TiDB Cloud, which ranks SQL statements by their Request Unit (RU) consumption, and updates the table of contents to include this new page. The review feedback focuses on improving the documentation's clarity, style, and consistency by suggesting active voice rewrites to replace passive constructions, refining terminology (such as using "left navigation pane" and "SQL statement"), correcting link targets, and clarifying specific steps in the workflow and limitations sections.
| ## Open Top RU | ||
|
|
||
| 1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to your cluster. | ||
| 2. In the left navigation, click **Monitoring** > **Top RU**. |
There was a problem hiding this comment.
Use "left navigation pane" instead of "left navigation" to maintain terminology consistency with other monitoring documents in the repository.
| 2. In the left navigation, click **Monitoring** > **Top RU**. | |
| 2. In the left navigation pane, click **Monitoring** > **Top RU**. |
References
- Use consistent terminology across the documentation. (link)
| |---|---| | ||
| | SQL Statement | Normalized SQL template | | ||
| | Total RU | Total RU consumed by this SQL in the selected time range | | ||
| | RU Share % | Percentage of total cluster RU consumed by this SQL. The top N SQLs together account for less than 100%; adding the **Others** row gives 100%. | |
There was a problem hiding this comment.
Use "SQL statement" and "SQL statements" instead of "SQL" and "SQLs" to be more precise and professional.
| | RU Share % | Percentage of total cluster RU consumed by this SQL. The top N SQLs together account for less than 100%; adding the **Others** row gives 100%. | | |
| | RU Share % | Percentage of total cluster RU consumed by this SQL statement. The top N SQL statements together account for less than 100%; adding the **Others** row gives 100%. | |
References
- Use consistent terminology and avoid unnecessary words. (link)
| | Total RU | Total RU consumed by this SQL in the selected time range | | ||
| | RU Share % | Percentage of total cluster RU consumed by this SQL. The top N SQLs together account for less than 100%; adding the **Others** row gives 100%. | | ||
| | Execution Count | Number of times this SQL was executed in the selected time range | | ||
| | User | Database user(s) that ran this SQL (Premium only). A single SQL digest may be executed by multiple users. | |
There was a problem hiding this comment.
Rewrite the passive sentence "A single SQL digest may be executed by multiple users" to active voice to improve readability and adhere to the style guide.
| | User | Database user(s) that ran this SQL (Premium only). A single SQL digest may be executed by multiple users. | | |
| | User | Database user(s) that ran this SQL (Premium only). Multiple users can execute a single SQL digest. | |
References
- Avoid passive voice overuse. (link)
|
|
||
| ### Rank by Users panel | ||
|
|
||
| The **Overview** tab includes a **Rank by Users** panel that shows a ranked list of database users by their total RU consumption for the selected time range. Use this to quickly determine whether the RU spike is driven by a specific user or application. |
There was a problem hiding this comment.
Avoid passive voice ("is driven by") by rewriting the sentence to active voice.
| The **Overview** tab includes a **Rank by Users** panel that shows a ranked list of database users by their total RU consumption for the selected time range. Use this to quickly determine whether the RU spike is driven by a specific user or application. | |
| The **Overview** tab includes a **Rank by Users** panel that shows a ranked list of database users by their total RU consumption for the selected time range. Use this to quickly determine whether a specific user or application drives the RU spike. |
References
- Avoid passive voice overuse. (link)
| To drill into a specific user's SQL statements: | ||
|
|
||
| 1. Click the **Sliced by Users** tab. | ||
| 2. In the **User** filter, select the user you want to investigate. Up to 100 users are shown; users beyond 100 are grouped as **Other users**. |
There was a problem hiding this comment.
Avoid passive voice ("are shown", "are grouped") by rewriting the sentence to active voice.
| 2. In the **User** filter, select the user you want to investigate. Up to 100 users are shown; users beyond 100 are grouped as **Other users**. | |
| 2. In the **User** filter, select the user you want to investigate. The filter displays up to 100 users and groups any additional users as **Other users**. |
References
- Avoid passive voice overuse. (link)
| - **Not equivalent to billing RU**: Top RU values are near-real-time observability data and do not match the billing RU in your TiDB Cloud invoice. Do not use Top RU for billing reconciliation or auditing. | ||
| - **TopN grouping**: SQL statements with lower RU may be grouped into **Others** rather than shown individually. | ||
| - **Data freshness**: 15 seconds. | ||
| - **Maximum query window**: 24 hours per time range selection. |
There was a problem hiding this comment.
Clarify the maximum query window description by using a complete sentence.
| - **Maximum query window**: 24 hours per time range selection. | |
| - **Maximum query window**: The maximum time range you can select for a single query is 24 hours. |
| - **TopN grouping**: SQL statements with lower RU may be grouped into **Others** rather than shown individually. | ||
| - **Data freshness**: 15 seconds. | ||
| - **Maximum query window**: 24 hours per time range selection. | ||
| - **Essential limitations**: The Sliced by Users tab and Rank by Users panel are not available for Essential clusters. |
There was a problem hiding this comment.
Bold the UI elements (Sliced by Users tab and Rank by Users panel) and use active voice.
| - **Essential limitations**: The Sliced by Users tab and Rank by Users panel are not available for Essential clusters. | |
| - **Essential limitations**: Essential clusters do not support the **Sliced by Users** tab and the **Rank by Users** panel. |
|
|
||
| ### Why is there no data in Top RU? | ||
|
|
||
| - Make sure the selected time range contains actual SQL workload. |
There was a problem hiding this comment.
Use "active SQL queries" instead of "actual SQL workload" for better clarity.
| - Make sure the selected time range contains actual SQL workload. | |
| - Make sure the selected time range contains active SQL queries. |
| ### Why is there no data in Top RU? | ||
|
|
||
| - Make sure the selected time range contains actual SQL workload. | ||
| - Refresh the page after running workload for at least 15 seconds. |
There was a problem hiding this comment.
Add "your" before "workload" to make the instruction more natural.
| - Refresh the page after running workload for at least 15 seconds. | |
| - Refresh the page after running your workload for at least 15 seconds. |
| - Refresh the page after running workload for at least 15 seconds. | ||
| - Check [TiDB Cloud Release Notes](/tidb-cloud/releases/tidb-cloud-release-notes.md) to confirm Top RU is available for your cluster version. | ||
|
|
||
| If the issue persists, contact [TiDB Cloud support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support). |
There was a problem hiding this comment.
Use a relative path to the support page instead of an absolute URL to maintain consistency with other documents in the repository.
| If the issue persists, contact [TiDB Cloud support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support). | |
| If the issue persists, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). |
|
Warning Gemini encountered an error creating the review. You can try again by commenting |
|
@huoyao1125: The following test failed, say
Full PR test history. Your PR dashboard. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here. |
1 participant
What is changed, added or deleted?
This PR adds a complete user guide for the Top RU feature in the TiDB Cloud web console, targeting both Premium and Essential product tiers.
Changes:
tidb-cloud/top-ru.md: full user-facing documentation for Top RUTOC-tidb-cloud.md: add Top RU entry under Monitor and AlertWhy this PR
PR #22760 attempted to document Top RU but has several critical issues:
This PR addresses all of the above. See issue #22988 for full details.
What this doc covers
Which TiDB version(s) do your changes apply to?
What is the related PR or file link(s)?
Do your changes match any of the following descriptions?