Problem
PR #22760 attempted to add Top RU documentation but has several critical issues that make it unsuitable for merge:
1. Wrong product surface
Top RU is a feature in the TiDB Cloud web console, not in TiDB Cloud Clinic. The PR places the doc under tidb-cloud/premium/top-ru-in-clinic-premium.md (a Clinic-specific directory) and titles it "TopRU views in Top SQL in TiDB Cloud Clinic". The entire doc should be a standalone page in the main TiDB Cloud web console docs.
2. Essential tier completely missing
The product spec explicitly supports both Premium and Essential clusters with different capabilities. The PR doc only covers Dedicated/Premium and notes it is "only available for TiDB Cloud Dedicated clusters".
Capability differences per tier:
| Feature |
Premium |
Essential |
| Overview tab |
✓ |
✓ |
| Sliced by Users tab |
✓ |
✗ |
| Rank by Users panel |
✓ |
✗ |
| Top N default |
10 |
5 |
| Top N options |
20/50/100 |
10/20 |
| Data retention |
30 days |
7 days |
3. Internal engineering perspective, not user-facing
The doc describes internal implementation details (aggregation keys (user, sql_digest, plan_digest), pipeline reuse, TopN compression mechanics) that belong in internal design docs. User documentation should describe what users can see and do, not how the feature works internally.
4. Key features from spec are missing
- Rank by Users panel (added in V1.4, Jan 7 2026) — not documented at all
- Top N configuration per tier with specific values
- Data retention per tier (Premium 30d / Essential 7d)
- Time range presets and custom range with 24-hour max window constraint
- Drill-down plan scenarios (4 scenarios based on plan availability)
- Quick link from Query Template ID to Slow Query logs
5. Incorrect prerequisite
The doc lists "Resource Control enabled" as a prerequisite. This appears to be an internal implementation detail, not a user-facing requirement for a product-level monitoring feature.
Proposed fix
Create a new doc at tidb-cloud/top-ru.md with:
- Correct product surface (web console, not Clinic)
- Coverage of both Premium and Essential tiers with a comparison table
- User-focused content (what users see and can do)
- All key features from the spec documented
- TOC entry added to
TOC-tidb-cloud.md under "Monitor and Alert"
Spec reference: https://pingcap.feishu.cn/wiki/AQUdwgOFyiIELCkzGj7c0tyonLh
Problem
PR #22760 attempted to add Top RU documentation but has several critical issues that make it unsuitable for merge:
1. Wrong product surface
Top RU is a feature in the TiDB Cloud web console, not in TiDB Cloud Clinic. The PR places the doc under
tidb-cloud/premium/top-ru-in-clinic-premium.md(a Clinic-specific directory) and titles it "TopRU views in Top SQL in TiDB Cloud Clinic". The entire doc should be a standalone page in the main TiDB Cloud web console docs.2. Essential tier completely missing
The product spec explicitly supports both Premium and Essential clusters with different capabilities. The PR doc only covers Dedicated/Premium and notes it is "only available for TiDB Cloud Dedicated clusters".
Capability differences per tier:
3. Internal engineering perspective, not user-facing
The doc describes internal implementation details (aggregation keys
(user, sql_digest, plan_digest), pipeline reuse, TopN compression mechanics) that belong in internal design docs. User documentation should describe what users can see and do, not how the feature works internally.4. Key features from spec are missing
5. Incorrect prerequisite
The doc lists "Resource Control enabled" as a prerequisite. This appears to be an internal implementation detail, not a user-facing requirement for a product-level monitoring feature.
Proposed fix
Create a new doc at
tidb-cloud/top-ru.mdwith:TOC-tidb-cloud.mdunder "Monitor and Alert"Spec reference: https://pingcap.feishu.cn/wiki/AQUdwgOFyiIELCkzGj7c0tyonLh