Skip to content

tidb-cloud: add TopRU user guide in TiDB Cloud Clinic (Premium) #22760

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
zimulala wants to merge 3 commits into
base: master
Choose a base branch
from
+134 −0
Open

tidb-cloud: add TopRU user guide in TiDB Cloud Clinic (Premium) #22760

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d1c40ba
tidb-cloud: add TopRU Clinic user guide
zimulala Apr 15, 2026
06b488d
tidb-cloud: make TopRU guide user-facing
zimulala Apr 16, 2026
ed6038a
tidb-cloud: refine TopRU clinic wording and screenshots
zimulala Apr 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions TOC-tidb-cloud-premium.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,7 @@
- Monitor and Alert
- [Overview](/tidb-cloud/monitor-tidb-cluster.md)
- [Built-in Metrics](/tidb-cloud/premium/built-in-monitoring-premium.md)
- [TopRU in TiDB Cloud Clinic](/tidb-cloud/premium/top-ru-in-clinic-premium.md)
- Tune Performance
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wrong TOC location. If Top RU is a web console feature (not Clinic), it should be in TOC-tidb-cloud.md under "Monitor and Alert", not in the Premium/Clinic TOC (TOC-tidb-cloud-premium.md).

- [Overview](/tidb-cloud/tidb-cloud-tune-performance-overview.md)
- [Analyze Performance](/tidb-cloud/tune-performance.md)
Expand Down
Binary file added media/tidb-cloud/top-ru-db-user-detail.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added media/tidb-cloud/top-ru-db-user-view.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added media/tidb-cloud/top-ru-instance-detail.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added media/tidb-cloud/top-ru-instance-view.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added media/tidb-cloud/top-ru-vs-qps-trend.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added media/tidb-cloud/top-ru-vs-ru-trend.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 2 additions & 0 deletions tidb-cloud/premium/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,8 @@ summary: TiDB Cloud is a fully-managed Database-as-a-Service (DBaaS) that brings

[Built-in Monitoring](https://docs-preview.pingcap.com/tidbcloud/built-in-monitoring-premium/?plan=premium)

[TopRU in TiDB Cloud Clinic](https://docs-preview.pingcap.com/tidbcloud/top-ru-in-clinic-premium/?plan=premium)

</LearningPath>

<LearningPath label="Tune" icon="tidb-cloud-tune">
Expand Down
124 changes: 124 additions & 0 deletions tidb-cloud/premium/top-ru-in-clinic-premium.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
---
title: TopRU views in Top SQL in TiDB Cloud Clinic
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
title: TopRU views in Top SQL in TiDB Cloud Clinic
title: Top RU on TiDB Cloud Web Console for Premium&Essential

Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wrong product surface and file location. According to the product spec, Top RU is a feature in the TiDB Cloud web console, not in TiDB Cloud Clinic. This file should not be placed under tidb-cloud/premium/ (a Clinic Premium directory) and should not reference Clinic in its title.

Suggested title: Top RU and file path: tidb-cloud/top-ru.md.

summary: Learn how to use TopRU in TiDB Cloud Clinic to identify SQL statements and database users with high RU consumption.
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
summary: Learn how to use TopRU in TiDB Cloud Clinic to identify SQL statements and database users with high RU consumption.
summary: Learn how to use Top RU on TiDB Cloud Web Console to identify SQL statements and database users with high RU consumption.

---

# TopRU views in Top SQL in TiDB Cloud Clinic
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# TopRU views in Top SQL in TiDB Cloud Clinic
# Top RU on TiDB Cloud Web Console for Premium&Essential


TopRU is an SQL observability feature in the Top SQL page of TiDB Cloud Clinic. It ranks SQL workloads by request unit (RU) consumption to help you quickly identify SQL statements with high resource usage.
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
TopRU is an SQL observability feature in the Top SQL page of TiDB Cloud Clinic. It ranks SQL workloads by request unit (RU) consumption to help you quickly identify SQL statements with high resource usage.
Top RU is an SQL observability feature on TiDB Cloud Web Console. It ranks SQL workloads by request unit (RU) consumption to help you quickly identify SQL statements with high resource usage.

Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Internal implementation detail — remove from user docs. "TopRU reuses the Top SQL collection and reporting pipeline, but extends the core metric from CPU to RU, and aggregates records by (user, sql_digest, plan_digest)" describes the internal engineering design, not what users see or do. Users don't need to know about the pipeline architecture.

Suggested replacement: Focus on what users can do — "Top RU ranks SQL statements by their cumulative RU consumption within the selected time range, including queries that are currently executing."


TopRU reuses the Top SQL collection and reporting pipeline, but extends the core metric from CPU to RU, and aggregates records by `(user, sql_digest, plan_digest)`. This helps you identify both high-cost SQL statements and the database users who continuously consume RU.
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
TopRU reuses the Top SQL collection and reporting pipeline, but extends the core metric from CPU to RU, and aggregates records by `(user, sql_digest, plan_digest)`. This helps you identify both high-cost SQL statements and the database users who continuously consume RU.
Top RU reuses the Top SQL collection and reporting pipeline, but extends the core metric from CPU to RU, and aggregates records by `(user, sql_digest, plan_digest)`. This helps you identify both high-cost SQL statements and the database users who continuously consume RU.


TopRU and Top SQL can coexist. Enabling TopRU does not change the existing CPU semantics of Top SQL.
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
TopRU and Top SQL can coexist. Enabling TopRU does not change the existing CPU semantics of Top SQL.

Comment on lines +1 to +12
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这个文档放错位置了，Top RU 是 web console 的功能，不是 Clinic 的功能。另外，intro 里暴露了内部实现细节（pipeline 复用、聚合 key），不适合用户文档。建议整个文件移到 tidb-cloud/top-ru.md，同时修改如下：

Suggested change
---
title: TopRU views in Top SQL in TiDB Cloud Clinic
summary: Learn how to use TopRU in TiDB Cloud Clinic to identify SQL statements and database users with high RU consumption.
---
# TopRU views in Top SQL in TiDB Cloud Clinic
TopRU is an SQL observability feature in the Top SQL page of TiDB Cloud Clinic. It ranks SQL workloads by request unit (RU) consumption to help you quickly identify SQL statements with high resource usage.
TopRU reuses the Top SQL collection and reporting pipeline, but extends the core metric from CPU to RU, and aggregates records by `(user, sql_digest, plan_digest)`. This helps you identify both high-cost SQL statements and the database users who continuously consume RU.
TopRU and Top SQL can coexist. Enabling TopRU does not change the existing CPU semantics of Top SQL.
---
title: Top RU
summary: Learn how to use Top RU to identify SQL statements and database users with the highest Request Unit (RU) consumption in real time.
---
# Top RU
**Top RU** ranks SQL statements by their Request Unit (RU) consumption, helping you quickly identify which queries are the primary drivers of your RU usage. When you notice an unexpected RU spike in your cluster monitoring, use Top RU to pinpoint the responsible SQL statements and take targeted action.
> **Note:**
>
> Top RU is available for TiDB Cloud Premium and TiDB Cloud Essential clusters.
Top RU coexists with Top SQL and does not affect the existing Top SQL behavior.


## Feature overview

TopRU answers the following questions:
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
TopRU answers the following questions:
Top RU answers the following questions:


- Which SQL statements continuously consume high RU?
- Is an RU spike in a time range caused by a small set of users or SQL statements?
- Why is resource consumption high even when CPU usage is not high?
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Why is resource consumption high even when CPU usage is not high?


TopRU data comes from runtime RU statistics in SQL execution, so it can reflect near-real-time resource trends. To control overhead, TopRU applies `TopN` aggregation to users and SQL statements, and merges low-priority items instead of outputting a full per-statement stream.
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
TopRU data comes from runtime RU statistics in SQL execution, so it can reflect near-real-time resource trends. To control overhead, TopRU applies `TopN` aggregation to users and SQL statements, and merges low-priority items instead of outputting a full per-statement stream.
Top RU data comes from runtime RU statistics in SQL execution, so it can reflect near-real-time resource trends. To control overhead, Top RU applies `TopN` aggregation to users and SQL statements, and merges low-priority items instead of outputting a full per-statement stream.

Comment on lines +14 to +22
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Essential tier 完全缺失。建议把 Feature overview 替换成 tier 对比表，让用户一眼看清 Premium vs Essential 的差异：

Suggested change
## Feature overview
TopRU answers the following questions:
- Which SQL statements continuously consume high RU?
- Is an RU spike in a time range caused by a small set of users or SQL statements?
- Why is resource consumption high even when CPU usage is not high?
TopRU data comes from runtime RU statistics in SQL execution, so it can reflect near-real-time resource trends. To control overhead, TopRU applies `TopN` aggregation to users and SQL statements, and merges low-priority items instead of outputting a full per-statement stream.
## Product tier comparison
Different product tiers support different Top RU capabilities:
| Feature | Premium | Essential |
|---|---|---|
| **Overview** tab | ✓ | ✓ |
| **Sliced by Users** tab | ✓ | ✗ |
| **Rank by Users** panel | ✓ | ✗ |
| **User** column in SQL list | ✓ | ✗ |
| Top N (default) | 10 | 5 |
| Top N options | 20, 50, 100 | 10, 20 |
| Data retention | 30 days | 7 days |


## Recommended scenarios

TopRU is useful in the following scenarios:
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
TopRU is useful in the following scenarios:
Top RU is useful in the following scenarios:


- You need to locate high RU-consuming SQL in clusters with [Resource Control](/tidb-resource-control-ru-groups.md) enabled.
- CPU usage is not the main bottleneck, but overall resource consumption is still high.
- You need user-level visibility to answer "who is consuming RU" instead of only "which SQL consumes CPU".
- You need to quickly identify major RU hotspots under high load and prioritize SQL optimization, resource group governance, or workload throttling.

TopRU is not for the following scenarios:
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
TopRU is not for the following scenarios:
Top RU is not for the following scenarios:


- Billing, reconciliation, or precise auditing.
- Replacing slow query logs, `statements_summary`, or daily offline statistics from resource groups.
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Replacing slow query logs, `statements_summary`, or daily offline statistics from resource groups.
- Replacing Slow Query, SQL Statement, or daily offline statistics from resource groups.


## Prerequisites

Before using TopRU, make sure that all of the following conditions are met:
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Before using TopRU, make sure that all of the following conditions are met:
Before using Top RU, make sure that all of the following conditions are met:


- You can access [TiDB Cloud Clinic](https://clinic.pingcap.com/).
- Your cluster has [Resource Control](/tidb-resource-control-ru-groups.md) enabled.
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This prerequisite is incorrect. "Your cluster has Resource Control enabled" should not be listed as a user prerequisite. Top RU is a product-level observability feature for Premium/Essential clusters — it does not require users to manually enable Resource Control. This will confuse users who don't have a resource control use case but still want to use Top RU.

Please verify with the engineering team whether this is actually required, and if so, describe it more accurately (e.g., is this a cluster-level auto-enabled feature or something users must configure?).

- Your cluster version supports TopRU in TiDB Cloud Clinic. For rollout updates, see [TiDB Cloud Release Notes](/tidb-cloud/releases/tidb-cloud-release-notes.md). If TopRU is still unavailable in your cluster, contact support.

> **Note:**
>
> TopRU is available in TiDB Cloud Clinic for [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters.
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Essential tier is missing. The product spec explicitly lists both Premium and Essential as supported product tiers. This note should be updated to reflect both:

  • Premium: Overview tab + Sliced by Users tab + Rank by Users panel; Top N default 10 (options: 20/50/100); 30-day retention
  • Essential: Overview tab only; Top N default 5 (options: 10/20); 7-day retention

A tier comparison table at the top of the doc would help users understand the differences at a glance.

Comment on lines +38 to +48
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

两个问题：

  1. Resource Control enabled 不是用户需要手动配置的前提条件，请与研发确认后删除
  2. Essential tier 被遗漏，不能写 "only for Dedicated"
Suggested change
## Prerequisites
Before using TopRU, make sure that all of the following conditions are met:
- You can access [TiDB Cloud Clinic](https://clinic.pingcap.com/).
- Your cluster has [Resource Control](/tidb-resource-control-ru-groups.md) enabled.
- Your cluster version supports TopRU in TiDB Cloud Clinic. For rollout updates, see [TiDB Cloud Release Notes](/tidb-cloud/releases/tidb-cloud-release-notes.md). If TopRU is still unavailable in your cluster, contact support.
> **Note:**
>
> TopRU is available in TiDB Cloud Clinic for [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters.
## Before you begin
Make sure you can log in to the [TiDB Cloud console](https://tidbcloud.com/).
> **Note:**
>
> If Top RU is not yet available for your cluster, check [TiDB Cloud Release Notes](/tidb-cloud/releases/tidb-cloud-release-notes.md) for rollout updates, or contact [TiDB Cloud support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support).


## Page views

TopRU in Top SQL currently includes the following views:

- **Overview (instance-level)**: inspect top RU-consuming SQL from the cluster instance perspective.
- **Sliced by Users (DB user-level)**: inspect RU consumption grouped by database user.
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing Essential-specific behavior. According to the spec (V1.4, updated Jan 7 2026):

  • Essential: only shows the Overview tab. The "Sliced by Users" tab is NOT available.
  • Premium: shows both Overview and Sliced by Users tabs, plus a Rank by Users panel in the Overview tab.

The current text lists both tabs without any tier distinction, which is misleading for Essential users.


![TopRU overview view](/media/tidb-cloud/top-ru-instance-view.png)

![TopRU overview detail](/media/tidb-cloud/top-ru-instance-detail.png)

![TopRU sliced by users view](/media/tidb-cloud/top-ru-db-user-view.png)

![TopRU sliced by users detail](/media/tidb-cloud/top-ru-db-user-detail.png)

A common diagnosis path is to locate RU hotspots in the **Overview** view first, and then switch to the **Sliced by Users** view to identify whether specific users dominate RU consumption.
Comment on lines +50 to +65
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

缺少 Essential 的行为说明（Essential 只有 Overview tab），也缺少 V1.4 新增的 Rank by Users 模块：

Suggested change
## Page views
TopRU in Top SQL currently includes the following views:
- **Overview (instance-level)**: inspect top RU-consuming SQL from the cluster instance perspective.
- **Sliced by Users (DB user-level)**: inspect RU consumption grouped by database user.
![TopRU overview view](/media/tidb-cloud/top-ru-instance-view.png)
![TopRU overview detail](/media/tidb-cloud/top-ru-instance-detail.png)
![TopRU sliced by users view](/media/tidb-cloud/top-ru-db-user-view.png)
![TopRU sliced by users detail](/media/tidb-cloud/top-ru-db-user-detail.png)
A common diagnosis path is to locate RU hotspots in the **Overview** view first, and then switch to the **Sliced by Users** view to identify whether specific users dominate RU consumption.
## Views
Top RU provides the following views depending on your product tier:
- **Overview** tab (Premium and Essential): shows the top RU-consuming SQL statements across all database users, including a **Rank by Users** panel (Premium only).
- **Sliced by Users** tab (Premium only): shows the top RU-consuming SQL statements for a specific database user.
For Essential clusters, only the **Overview** tab is available.
![Top RU overview view](/media/tidb-cloud/top-ru-instance-view.png)
![Top RU overview detail](/media/tidb-cloud/top-ru-instance-detail.png)
![Top RU sliced by users view](/media/tidb-cloud/top-ru-db-user-view.png)
![Top RU sliced by users detail](/media/tidb-cloud/top-ru-db-user-detail.png)


## Use TopRU

A common workflow for TopRU is as follows:

1. Open the **Top SQL** page in TiDB Cloud Clinic.
2. Select a time range, and use the TopRU **Overview** view to identify top RU-consuming SQL statements and hotspot periods.
3. Switch to the TopRU **Sliced by Users** view to verify whether RU is concentrated on a small set of users.
4. Open SQL details and combine `sql_digest` / `plan_digest` with execution count and execution duration to prioritize optimization.
5. Continue analysis with Top SQL, slow query data, and execution plans.
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing key feature: Rank by Users panel. The spec (V1.4) added a "Rank by Users" module to the Premium Overview tab. This panel shows a ranked list of database users by RU consumption (Sum(RU) by users where time=selected_time_range and SQL_Digest=Top_N_SQL, order by sum(RU) desc). It's a key part of the Premium experience and is completely absent from this doc.

Comment on lines +67 to +75
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

三个问题：(1) 入口写的是 Clinic，应该是 web console；(2) 缺少 filter 说明（Top N 配置值、时间范围、数据保留策略）；(3) 缺少 Rank by Users 步骤；(4) step 4 暴露了内部字段名：

Suggested change
## Use TopRU
A common workflow for TopRU is as follows:
1. Open the **Top SQL** page in TiDB Cloud Clinic.
2. Select a time range, and use the TopRU **Overview** view to identify top RU-consuming SQL statements and hotspot periods.
3. Switch to the TopRU **Sliced by Users** view to verify whether RU is concentrated on a small set of users.
4. Open SQL details and combine `sql_digest` / `plan_digest` with execution count and execution duration to prioritize optimization.
5. Continue analysis with Top SQL, slow query data, and execution plans.
## Use Top RU
A typical workflow for investigating an RU spike:
1. Log in to the [TiDB Cloud console](https://tidbcloud.com/), navigate to your cluster, and click **Monitoring** > **Top RU**.
2. Select a **time range** covering the spike. Preset options: Last 5 min / 15 min / 30 min / 1 hour / 6 hours / 12 hours / 1 day. For custom ranges, the maximum window is 24 hours, and the earliest available start date is 30 days ago (Premium) or 7 days ago (Essential).
3. Set the **Top N** value: Premium default 10 (options: 20, 50, 100); Essential default 5 (options: 10, 20).
4. In the **Overview** tab, identify the SQL statements with the highest Total RU. Hover over each to highlight its RU trend and see when the spike started.
5. **(Premium)** Check the **Rank by Users** panel to see whether a specific user is driving the spike.
6. **(Premium)** Switch to the **Sliced by Users** tab and select a user to focus on their top RU-consuming SQL.
7. Click a SQL statement to open its detail panel. Review the execution plan for optimization opportunities.
8. Use the **Query Template ID** to cross-reference slow query logs for additional context.
9. Apply optimizations and return to Top RU to verify the RU consumption has decreased.


TopRU trends usually correlate with RU and QPS trends, which you can use for cross-checking:

![TopRU vs RU trend](/media/tidb-cloud/top-ru-vs-ru-trend.png)

![TopRU vs QPS trend](/media/tidb-cloud/top-ru-vs-qps-trend.png)

## TopRU observation dimensions

TopRU uses `(user, sql_digest, plan_digest)` as the aggregation key. Each time point usually includes the following fields:
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Section title and content are too technical. "TopRU observation dimensions" reads like an internal design doc. For user documentation, this section should describe what columns users see and what each means, not expose internal aggregation keys.

Also missing from this section: Top N configuration values per tier, time range filter options (Last 5 min / 15 min / 30 min / 1 hour / 6 hours / 12 hours / 1 day), and data retention limits per tier.


- `Total RU`: total RU consumption in the interval.
- `Exec Count`: number of executions in the interval.
- `Exec Duration`: aggregated execution duration in the interval.

TopRU shows time-series data in the selected time range. The TiDB Cloud Clinic UI automatically adjusts the displayed time buckets based on the selected range.

To limit memory and network overhead, TopRU applies `TopN` aggregation to users and SQL statements. High-priority items are kept as individual records, while low-priority items are merged.
Comment on lines +83 to +93
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这一节标题和内容都是内部工程视角，暴露了聚合 key 等实现细节。替换为用户视角的 SQL list 字段说明：

Suggested change
## TopRU observation dimensions
TopRU uses `(user, sql_digest, plan_digest)` as the aggregation key. Each time point usually includes the following fields:
- `Total RU`: total RU consumption in the interval.
- `Exec Count`: number of executions in the interval.
- `Exec Duration`: aggregated execution duration in the interval.
TopRU shows time-series data in the selected time range. The TiDB Cloud Clinic UI automatically adjusts the displayed time buckets based on the selected range.
To limit memory and network overhead, TopRU applies `TopN` aggregation to users and SQL statements. High-priority items are kept as individual records, while low-priority items are merged.
## SQL list columns
The **Top N SQL list** displays the following information for each SQL statement:
| Column | Description |
|---|---|
| SQL Statement | Normalized SQL template |
| Total RU | Total RU consumed in the selected time range |
| RU Share % | Percentage of total cluster RU consumed by this SQL. The top N SQLs account for less than 100%; adding **Others** gives 100%. |
| Execution Count | Number of executions in the selected time range |
| User | Database user(s) that ran this SQL (Premium only) |
The trend chart shows RU consumption at 15-second intervals. Hover over a SQL statement to highlight its trend line.


## Limitations and considerations

- RU values in TopRU are runtime `RUDetails` observability values and are not equivalent to billing RU.
- If Resource Control is not enabled, TopRU cannot generate effective RU data.
- To control collection and reporting overhead, TopRU applies `TopN` compression and does not retain all low-RU items.

Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Incorrect limitation. "If Resource Control is not enabled, TopRU cannot generate effective RU data" — this implies users must configure Resource Control, which is not the expected user experience for a product-level monitoring feature. Please verify with the engineering team whether this is actually a user-visible requirement.

> **Note:**
>
> TopRU is for real-time hotspot diagnosis, not for billing settlement, precise reconciliation, or long-term offline auditing.
Comment on lines +95 to +103
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If Resource Control is not enabled, TopRU cannot generate effective RU data — 这条不正确，请与研发确认后删除。同时补充 Essential 的限制和具体的数字：

Suggested change
## Limitations and considerations
- RU values in TopRU are runtime `RUDetails` observability values and are not equivalent to billing RU.
- If Resource Control is not enabled, TopRU cannot generate effective RU data.
- To control collection and reporting overhead, TopRU applies `TopN` compression and does not retain all low-RU items.
> **Note:**
>
> TopRU is for real-time hotspot diagnosis, not for billing settlement, precise reconciliation, or long-term offline auditing.
## Limitations
- **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.
- **Essential limitations**: The Sliced by Users tab and Rank by Users panel are not available for Essential clusters.


## FAQ

### What is the difference between TopRU and Top SQL?

Top SQL is CPU-focused. TopRU is RU-focused and adds user-level visibility. TopRU reuses the Top SQL pipeline but changes the observed metric from CPU to RU.

### Why is there no TopRU data after enabling it?

Check the following items:

- Confirm that [Resource Control](/tidb-resource-control-ru-groups.md) is enabled.
- Confirm that your cluster supports TopRU in TiDB Cloud Clinic.
- Select a recent time range that contains actual SQL workload.
- Refresh the page after running workload for a short period.

If the issue persists, contact TiDB Cloud support.

### Is TopRU equal to billing RU?

No. TopRU uses runtime `RUDetails` observability values to help you diagnose high resource-consumption SQL. For billing and reconciliation, use billing RU and related offline statistics.
Comment on lines +105 to +124
Copy link
Copy Markdown

@huoyao1125 huoyao1125 Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FAQ 里仍然含有内部视角描述（RUDetails，reuses the Top SQL pipeline），FAQ Q2 的 checklist 要求确认 Resource Control（不正确）。建议修改为：

Suggested change
## FAQ
### What is the difference between TopRU and Top SQL?
Top SQL is CPU-focused. TopRU is RU-focused and adds user-level visibility. TopRU reuses the Top SQL pipeline but changes the observed metric from CPU to RU.
### Why is there no TopRU data after enabling it?
Check the following items:
- Confirm that [Resource Control](/tidb-resource-control-ru-groups.md) is enabled.
- Confirm that your cluster supports TopRU in TiDB Cloud Clinic.
- Select a recent time range that contains actual SQL workload.
- Refresh the page after running workload for a short period.
If the issue persists, contact TiDB Cloud support.
### Is TopRU equal to billing RU?
No. TopRU uses runtime `RUDetails` observability values to help you diagnose high resource-consumption SQL. For billing and reconciliation, use billing RU and related offline statistics.
## FAQ
### What is the difference between Top RU and Top SQL?
Top SQL ranks SQL statements by CPU time on a specific TiDB or TiKV node. Top RU ranks SQL statements by Request Unit (RU) consumption at the cluster level, and supports user-level breakdown (Premium only). Both features are independent.
### 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.
- 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).
### Is Top RU the same as billing RU?
No. Top RU shows near-real-time RU statistics for diagnosing high-consumption SQL. For billing and cost management, refer to the billing RU metrics in your TiDB Cloud billing console.

7 changes: 7 additions & 0 deletions tidb-cloud/tidb-cloud-clinic.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ To view the **Cluster** page, take the following steps:
- Advanced Metrics
- Top Slow Queries (only supported when the TiDB version of the cluster is v8.1.1 or later, v7.5.4 or later)
- Top SQL (only supported when the TiDB version of the cluster is v8.1.1 or later, v7.5.4 or later)
- TopRU (only supported in TiDB Cloud Clinic for TiDB Cloud Dedicated clusters)
- Benchmark Report

## Monitor advanced metrics
Expand Down Expand Up @@ -107,6 +108,12 @@ To view Top SQL, take the following steps:

For more information, see [Top SQL in TiDB Dashboard](https://docs.pingcap.com/tidb/stable/top-sql).

## Monitor TopRU

TopRU in TiDB Cloud Clinic helps you analyze SQL workload hotspots by request unit (RU) consumption and by database user.

For usage details, prerequisites, and limitations, see [TopRU in TiDB Cloud Clinic](/tidb-cloud/premium/top-ru-in-clinic-premium.md).

## Generate benchmark reports

The **Benchmark Report** feature helps you identify performance issues in a TiDB cluster during performance testing. After completing a stress test, you can generate a benchmark report to analyze the cluster's performance. The report highlights identified bottlenecks and provides optimization suggestions. After applying these suggestions, you can run another round of stress testing and generate a new benchmark report to compare performance improvements.
Expand Down
Loading