# RU Limit Inspection Reporting

Use this reference when generating or reviewing an RU limit inspection report.

## Contents

- [Output Separation](#output-separation)
- [Report Structure](#report-structure)
- [Conclusion Wording](#conclusion-wording)
- [Alert Rows](#alert-rows)
- [Over-Limit Detail](#over-limit-detail)
- [Internal Validation Checklist](#internal-validation-checklist)

## Output Separation

The bundled Dedicated/Classic collector uses English HTML as its external report format and also writes
internal notes, a manifest, raw facts, and a collection evaluation. It does not export PNG. Do not
add image artifacts unless the user explicitly asks for them.

External report includes only:
- inspection window and target groups
- findings, measurements, tables, and conclusions
- alert summary and evidence values
- clearly stated data gaps that affect conclusion strength
- an inline SVG chart for every executed time-series analysis query, grouped under target behavior,
  protected-task progress, concurrency impact, resource usage, and triggered TiKV correlation;
  configuration snapshots and history are summarized separately because their settings use different units

Internal notes include:
- login and access path details
- endpoint status, retries, fallback, and raw paths
- PromQL text and temporary query variants
- SQL text, SQL parameters, digests, or statement samples only when they are needed for internal
  follow-up and have row limits
- high-cardinality instance identities unless user-facing node evidence is explicitly required
- unresolved collection issues

## Report Structure

When using `scripts/collect-rc-report.mjs`, the standard artifacts are:
- `report.html`
- `internal-notes.md`
- `manifest.json`
- `raw/prometheus-results.json`
- `raw/inspection-summary.json`
- `raw/collection-evaluation.json`

Use this order:

1. Basic information
   - cluster or dashboard target
   - inspection window
   - target resource groups
   - datasource summary
2. Conclusion summary
   - one row for target resource group behavior
   - one row for protected-task progress
   - one row for concurrency impact
   - one row for TiDB/TiKV resource pressure
   - one triggered TiKV tail-latency row only when the collector ran that check
3. Optional alert summary
   - include only Warning/Critical rows
   - keep Info-only activity or spike observations out of the top alert summary
4. Resource group configuration
   - target groups only unless another group is explicitly under inspection
   - show whether configuration history was complete and unchanged, changed, or unavailable
   - for changed settings, show the observed minimum and maximum; do not combine settings with different
     units on one chart axis
5. Target group RU and queueing
   - RU/s Max, utilization, over-limit duration, headroom, KV wait, target QPS, target query p99
6. Task progress
   - bundled collector fields: DDL running/waiting, Auto Analyze QPM/duration, AnalyzeTable p95
   - Batch-like work: use target-group QPS/query duration/RU/RC wait
   - do not describe unrelated global DDL/Analyze progress as target progress for Batch/custom groups
   - lead with one conclusion, then present measurements in a compact labeled metric grid rather
     than a two-column table with one value per row
   - render contract-approved empty results as `No activity` or `No backlog`; reserve
     `Unavailable` for evidence that could not be collected or validated, and keep numeric zero as `0`
7. Concurrency impact
   - non-target group latency/QPS/RU and global SQL latency/QPS
   - state the queried non-target group scope; do not imply every resource group was checked
   - lead with one conclusion and group comparison ratios in a compact metric grid
8. Resource usage
   - bundled collector: TiDB/TiKV CPU summary
   - lead with one conclusion and place the TiDB/TiKV measurements side by side
9. Triggered TiKV tail-latency correlation
   - include only when triggered for in-scope DDL/Analyze targets
10. Observations and auxiliary information
   - state conclusion-impacting data gaps in the affected section, not as a separate evidence
     boundary section
11. Detailed metric charts
   - render every executed time-series analysis query, including an explicit empty-state panel when a query
     returns no series; exclude the configuration snapshot and history summarized in section 4
   - pin every chart's horizontal domain to the full inspection window so sparse samples are not
     visually stretched across the whole period
   - restrict the target-behavior charts to selected target groups; keep `default` and other
     comparison groups in the concurrency-impact charts
   - keep fixed colors for `default`, `rg_ddl`, `rg_analyze`, and `rg_batch`
   - show unit, series/point count, legend, and a concise peak observation without exposing PromQL
   - use readable sub-second units and describe expected-empty panels in user-facing metric terms;
     do not mention metric contracts or peer-evidence mechanics in the external report

## Conclusion Wording

Write direct conclusions. Avoid describing the chart instead of the result.

Examples:
- "No target group exceeded its RU/s limit; no sustained RC wait was observed."
- "The target group exceeded its RU/s limit for 8m20s; DDL waiting also increased during the same window."
- "Default group latency rose, but TiKV same-instance tail latency did not move with target DDL/Analyze activity; keep as observation, not concurrency-impact alert."
- "The target group was configured but had no observed activity in this window."

## Alert Rows

Each alert row should contain:
- level: `Warning` or `Critical`
- metric
- current value or active dimension
- fixed threshold or active/inactive baseline
- concise explanation

Do not include rows that only explain implementation details.

## Over-Limit Detail

When over-limit duration is greater than zero, include a detail block per continuous interval:
- target resource group
- interval start/end
- duration
- peak RU/s
- peak utilization
- peak time
- configured RU/s limit

Use the nearby task progress, concurrency, and TiKV correlation sections for follow-up conclusions;
do not duplicate the full conclusion in every interval row.

## Internal Validation Checklist

Before delivering:
- Confirm `deliveryReady=true` and the lightweight verifier passes.
- Confirm the target groups, workload types, and inspection window are correct.
- Confirm missing or invalid evidence is not rendered as zero or inactivity.
- External report does not contain credentials, cookies, token values, raw paths, endpoint status,
  PromQL, SQL text, or SQL parameters.