Skip to content

tidb-cloud: add Top RU user guide (web console, Premium + Essential) #22989

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
huoyao1125 wants to merge 3 commits into
base: release-8.5
Choose a base branch
from
Open

tidb-cloud: add Top RU user guide (web console, Premium + Essential) #22989

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
fc5bcdb
tidb-cloud: add Top RU user guide for web console
huoyao1125 Jun 1, 2026
84cffe6
tidb-cloud: add Top RU to TOC under Monitor and Alert
huoyao1125 Jun 1, 2026
4402316
Update top-ru.md
huoyao1125 Jun 1, 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.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@
- Monitor and Alert
- [Overview](/tidb-cloud/monitor-tidb-cluster.md)
- [Built-in Metrics](/tidb-cloud/built-in-monitoring.md)
- [Top RU](/tidb-cloud/top-ru.md)
- [Built-in Alerting](/tidb-cloud/monitor-built-in-alerting.md)
- Subscribe to Alert Notifications
- [Subscribe via Email](/tidb-cloud/monitor-alert-email.md)
Expand Down
155 changes: 155 additions & 0 deletions tidb-cloud/top-ru.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
---
title: Top RU
summary: Learn how to use Top RU to identify the SQL statements and database users with the highest Request Unit (RU) consumption in minute-level.
---

# 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 instances monitoring, use Top RU to pinpoint the responsible SQL statements and take targeted action.

> **Note:**
>
> Top RU is currently available for TiDB Cloud Premium and partial TiDB Cloud Essential instances for Public Preview, in gradual rollout.

## Product tier comparison

Different product tiers support different Top RU capabilities:

| Feature | Premium | Essential |
|---|---|---|
| **Overview** tab | ✓ | ✓ |
| **Sliced by Users** tab | ✓ | ✓ |
| **Top 3 DB Users (RU)** panel | ✓ | ✓ |
| Top N options | 5, 10, 20, 100 | 5, 10, 20 |
| Data retention | 30 days | 7 days |

## Open Top RU

1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to your instance.
2. In the left navigation, click **Monitoring** > **Top RU**.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jun 1, 2026

Choose a reason for hiding this comment

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

low

Use "left navigation pane" instead of "left navigation" to maintain terminology consistency with other monitoring documents in the repository.

Suggested change
2. In the left navigation, click **Monitoring** > **Top RU**.
2. In the left navigation pane, click **Monitoring** > **Top RU**.
References
  1. Use consistent terminology across the documentation. (link)


## Analyze RU consumption by SQL

The **Overview** tab shows the top RU-consuming SQL statements across all database users for the selected time range.

### Set filters

Use the filters at the top of the page to narrow down the data:

- **Time range**: Select a preset interval or a custom range.

Preset options: **Last 15 min**, **30 min**, **1 hour**, **2 hours**, **6 hours**, **12 hours**, **1 day**.

For custom time ranges:
- The earliest available start date depends on your data retention: **30 days ago** for Premium instances, **7 days ago** for Essential instances.
- The maximum window for a single query is **24 hours**.

- **Top N**: Select how many SQL statements to display.

Check warning on line 47 in tidb-cloud/top-ru.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.Ambiguous] Consider using a clearer word than 'many' because it may cause confusion.

Raw Output:
{"message": "[PingCAP.Ambiguous] Consider using a clearer word than 'many' because it may cause confusion.", "location": {"path": "tidb-cloud/top-ru.md", "range": {"start": {"line": 47, "column": 25}}}, "severity": "INFO"}
- Premium: default **10**, options: **5**, **20**, **100**.
- Essential: default **10**, options: **5**, **20**.

### Read the SQL list

The **Top N SQL list** shows the highest RU-consuming SQL statements for the selected filters:

| Column | Description |
|---|---|
| SQL Statement | Normalized SQL template |
| Total RU | Total RU consumed by this SQL in the selected time range |
| Mean RU | Mean RU consumed by this SQL in the selected time range, total ru/excecutions |
| Share | Percentage of total instance RU consumed by this SQL. The top N SQLs together account for less than 100%; adding the **Others** row gives 100%. |
| Executions | Number of times this SQL was executed in the selected time range |
| Plans | Number of plans this SQL was executed in the selected time range |
| Total latency | Total execution time cost by this SQL in the selected time range |
| Mean latency | Mean execution time cost by this SQL in the selected time range, total latency/excecutions |

> **Note:**
>
> Top RU ranks SQL statements by their **cumulative RU consumption**, including queries that are still executing. This lets you catch ongoing expensive queries before they complete. But for queries that are still executing, the plan is not available.

### View the RU trend

Hover over any SQL statement in the list to highlight its **RU trend line** in the trend chart. The chart shows RU consumption over the selected time range at minute-level intervals, helping you identify when a spike started and whether it is still ongoing.

## Identify RU consumption by user

### Rank by Users panel

The **Overview** tab includes a **Top 3 DB Users (RU)** 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 db user.

### Sliced by Users tab

To drill into a specific db 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**.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jun 1, 2026

Choose a reason for hiding this comment

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

low

Avoid passive voice ("are shown", "are grouped") by rewriting the sentence to active voice.

Suggested change
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
  1. Avoid passive voice overuse. (link)

3. The **Top N SQL list** and trend chart now reflect only the selected user's queries.

## Drill down into a SQL statement

Click any SQL statement in the **Top N SQL list** to open its detail panel. The information displayed depends on how many execution plans the SQL has and whether plan data is available.

Check warning on line 90 in tidb-cloud/top-ru.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.Ambiguous] Consider using a clearer word than 'many' because it may cause confusion.

Raw Output:
{"message": "[PingCAP.Ambiguous] Consider using a clearer word than 'many' because it may cause confusion.", "location": {"path": "tidb-cloud/top-ru.md", "range": {"start": {"line": 90, "column": 118}}}, "severity": "INFO"}
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jun 1, 2026

Choose a reason for hiding this comment

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

low

Avoid passive voice ("The information displayed depends on...") by rewriting the sentence to active voice.

Suggested change
Click any SQL statement in the **Top N SQL list** to open its detail panel. The information displayed depends on how many execution plans the SQL has and whether plan data is available.
Click any SQL statement in the **Top N SQL list** to open its detail panel. The panel displays different information depending on the number of execution plans and whether plan data is available.
References
  1. Avoid passive voice overuse. (link)


### Execution Summary

| Section | Content |
|---|---|
| SQL Digest | Normalized SQL template id |
| Total RU | Total RU consumed by this SQL in the selected time range |
| Mean RU | Mean RU consumed by this SQL in the selected time range, total ru/excecutions |
| Share | Percentage of total instance RU consumed by this SQL |
| Executions | Number of times this SQL was executed in the selected time range |
| Plans | Number of plans this SQL was executed in the selected time range |
| Total latency | Total execution time cost by this SQL in the selected time range |
| Mean latency | Mean execution time cost by this SQL in the selected time range, total latency/excecutions |

### Execution Plans

#### Plans not available

When plan data is not available, the following are not shown: Plan digest, SQL RU Trend by Plan, and Execution Plan. The other fields remain visible.

#### Multiple plans

When the SQL has multiple execution plans, a plan list is shown first:
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jun 1, 2026

Choose a reason for hiding this comment

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

low

Avoid passive voice ("a plan list is shown first") by rewriting the sentence to active voice.

Suggested change
When the SQL has multiple execution plans, a plan list is shown first:
When the SQL has multiple execution plans, the panel displays a plan list first:
References
  1. Avoid passive voice overuse. (link)


- Click an **available plan** to expand its full details (same as the single available plan case).
- Clicking an **unavailable plan** does not expand further.

## Typical workflow

The following is a typical workflow for investigating an RU spike:

1. Notice an RU spike in your instance metrics or a triggered alert.
2. Open **Monitoring** > **Top RU** > **Overview** tab and select a time range covering the spike.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jun 1, 2026

Choose a reason for hiding this comment

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

low

Clarify the step by using precise actions and referencing the Overview tab as a UI element.

Suggested change
2. Open **Monitoring** > **Top RU** > **Overview** tab and select a time range covering the spike.
2. Go to **Monitoring** > **Top RU**, click the **Overview** tab, and select a time range covering the spike.

3. Identify the SQL statements with the highest Total RU. Hover over each to see its RU trend and identify when the spike started.
4. Check the **Rank by Users** panel to see whether a specific user is driving the spike.
5. If needed, go to the **Sliced by Users** tab, select the user, and focus on their top RU-consuming SQL statements.
6. Click a SQL statement to open its detail panel. Review the execution plan to find optimization opportunities such as missing indexes.
7. Use the **Query Template ID** to cross-reference Slow Query/SQL Statement for additional execution context.
8. Apply optimizations: add indexes, rewrite the SQL, or adjust business logic.
9. Return to Top RU and select a recent time range to confirm that RU consumption has decreased after the optimization.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jun 1, 2026

Choose a reason for hiding this comment

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

low

Clarify the destination page and make the step more concise.

Suggested change
9. Return to Top RU and select a recent time range to confirm that RU consumption has decreased after the optimization.
9. Return to the **Top RU** page and select a recent time range to confirm that RU consumption has decreased.


## 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.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jun 1, 2026

Choose a reason for hiding this comment

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

low

Avoid passive voice ("may be grouped... rather than shown") by rewriting the sentence to active voice.

Suggested change
- **TopN grouping**: SQL statements with lower RU may be grouped into **Others** rather than shown individually.
- **TopN grouping**: TiDB Cloud groups SQL statements with lower RU into **Others** instead of showing them individually.
References
  1. Avoid passive voice overuse. (link)

- **Data freshness**: minute-level.
- **Maximum query window**: 24 hours per time range selection.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jun 1, 2026

Choose a reason for hiding this comment

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

low

Clarify the maximum query window description by using a complete sentence.

Suggested change
- **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.


## FAQ

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

[Top SQL](/tidb-cloud/tidb-cloud-clinic.md#monitor-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 instance level, and supports user-level breakdown.

### Why is there no data in Top RU?

- Make sure the selected time range contains actual SQL workload.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jun 1, 2026

Choose a reason for hiding this comment

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

low

Use "active SQL queries" instead of "actual SQL workload" for better clarity.

Suggested change
- Make sure the selected time range contains actual SQL workload.
- Make sure the selected time range contains active SQL queries.

- Refresh the page after running workload for at least 1 min.
- Check [TiDB Cloud Release Notes](/tidb-cloud/releases/tidb-cloud-release-notes.md) to confirm Top RU is available for your instance version/region.

If the issue persists, contact [TiDB Cloud support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support).
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jun 1, 2026

Choose a reason for hiding this comment

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

low

Use a relative path to the support page instead of an absolute URL to maintain consistency with other documents in the repository.

Suggested change
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).


### 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 in your TiDB Cloud billing console.
Loading