---
name: ru-limit-inspection
description: |
  Use for contract-driven, read-only inspection of TiDB resource-group RU
  limits on proven dedicated-classic-v1 deployments, including RU/s limit
  utilization, over-limit duration, RC wait, protected-workload progress,
  concurrency impact, and TiDB/TiKV pressure. Route other product profiles
  and controls not expressed through resource-group RU limits to their
  product-specific workflow.
---

# RU Limit Inspection

Produce a verifier-approved English HTML report for explicit target resource groups with the
bundled collector.

## Scope Gate

Identify the product profile before preparing datasource access:

| Product profile | Bundled collector | Action |
|---|---|---|
| Dedicated / legacy Classic with standard RU-limit metrics | Supported | Require `--profile dedicated-classic-v1` and confirm the required inputs and metric contract. |
| Other product profiles | Unsupported | Route to the product-specific RU-limit inspection workflow. |
| Unknown or customized dashboard | Unverified | Inspect dashboard JSON and metric identity; continue after proving compatibility with `dedicated-classic-v1`. |

Complete this gate only when the product profile and metric identity are proven compatible.

## Required Inputs and Data Access

After the scope gate, select exactly one datasource mode and establish only the access it needs:

- For a Clinic cluster ID, use `clinic-api` to resolve metadata and product profile, then select the
  collector's `--clinic-cluster-id` mode for Clinic Data Proxy metrics.
- For a Clinic or online Grafana link, use `op-clinic-grafana-access` and select the authenticated
  Grafana datasource-proxy mode.
- For an O11Y cluster, use `o11y-metrics-api` or equivalent Prometheus `query_range` access.

Resolve or ask for:

- target cluster/dashboard or Prometheus-compatible endpoint
- absolute inspection window and timezone
- only the explicit target resource groups under inspection
- explicit workload type for every target: `ddl`, `analyze`, `batch`, or `custom`
- cluster, component, and optional keyspace label matchers
- non-target business groups needed for concurrency comparison

Ask for target resource groups when dashboard variables do not identify them. Assign every target
an explicit `--target-group-types` entry; use `custom` when DDL/Analyze/Batch semantics are outside
the inspection scope.

Confirm the `dedicated-classic-v1` metric contract before collection: expected metric families,
cluster labels, result labels, target groups, workload types, inspection window, and datasource
identity must agree. Treat a successful query with the wrong metric or label scope as a semantic
mismatch rather than usable evidence.

For Grafana input, inspect dashboard JSON and panel queries before collection, then map dashboard
variables to `--matchers`, `--tidb-matchers`, and `--tikv-matchers`.

## Load References

Read only what the active branch needs:

- `references/metrics.md`: read before interpreting collector results or adapting evidence.
- `references/collector.md`: read after selecting the datasource mode; use only that mode's invocation.
- `references/reporting.md`: read before finalizing, editing, reviewing, or delivering report artifacts.
- `references/promql.md`: read only for an exploratory manual inspection when the collector cannot
  be used or PromQL requires adaptation. The standard collector path does not need this reference.

## Workflow

1. Prove that the product profile matches `dedicated-classic-v1`.
2. Select one datasource mode and establish its required authenticated access.
3. Resolve the absolute window, explicit target groups, workload types, comparison groups, and
   matchers; confirm that they satisfy the metric contract.
4. Read `references/metrics.md`, the selected branch in `references/collector.md`, and
   `references/reporting.md`.
5. Run `scripts/collect-rc-report.mjs`. Let the collector gather configuration, RU-limit behavior,
   applicable task progress, concurrency impact, and TiDB/TiKV CPU evidence.
6. Review the generated evidence in this fixed order:
   - target resource group behavior
   - impact on other concurrent requests
   - TiDB/TiKV resource pressure
7. For DDL/Analyze targets, require the collector's bounded TiKV tail-latency correlation when any
   trigger fires:
   - RU/s max utilization reaches the warning line
   - over-limit duration is greater than zero
   - non-target or global latency/QPS shows a candidate impact event
8. Run the artifact verifier:

```bash
node scripts/verify-rc-report.mjs ./ru-based-rc-inspection
```

If the collector cannot be used, read `references/promql.md`, perform a bounded manual inspection,
label the result exploratory and non-final, and state every blocking evidence gap. Complete this
branch after returning the diagnostic findings and their explicit limitations; it does not produce
a verifier-approved final report.

## Completion Criterion

Treat the inspection as final only when all conditions hold:

- the product profile is proven as `dedicated-classic-v1`
- the inspection uses absolute `--from` and `--to` timestamps
- every target resource group has an explicit workload type
- collection returns `deliveryReady=true`
- the artifact verifier exits with status `0`

Otherwise, return available artifacts as exploratory diagnostics and state the blocking evidence
gaps.

## Judgment Rules

- Base the RU-limit judgment on RU/s utilization, over-limit duration, wait time, task progress, and
  concurrency impact together.
- Keep inspection severity independent from data quality. Query errors, unsafe matchers, semantic
  mismatches, missing required baselines, configuration-history gaps, stale contracts, and verifier
  failures are evidence gaps; valid Warning/Critical results are inspection findings.