tidb-cloud: Top RU user guide needs rewrite — wrong product surface, missing Essential tier, non-user-facing content
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 617
- Forks
- 724
- Avg merge
- 2d 10h
- Merged PRs (30d)
- 223
Description
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.mdunder "Monitor and Alert"
Spec reference: https://pingcap.feishu.cn/wiki/AQUdwgOFyiIELCkzGj7c0tyonLh
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the existing PR #22760 content under tidb-cloud/premium/top-ru-in-clinic-premium.md, the proposed destination tidb-cloud/top-ru.md, and TOC-tidb-cloud.md. Use the linked product spec to verify Premium and Essential capabilities, then ensure the new page is user-facing, covers the listed features and limits, and is linked under Monitor and Alert.
Written by the indexing model from the issue text.
Assessment
- Domain
- cloud, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100