pingcap / pingcap/docs

tidb-cloud: Top RU user guide needs rewrite — wrong product surface, missing Essential tier, non-user-facing content

Open
#22,988 0 comments 0 reactions 0 assignees View on GitHub

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.md under "Monitor and Alert"

Spec reference: https://pingcap.feishu.cn/wiki/AQUdwgOFyiIELCkzGj7c0tyonLh

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.