# RU Limit Inspection Collector

Use this reference to collect evidence for resource-group RU limits after selecting exactly one
datasource mode. The bundled collector is the executable source of truth for standard
`dedicated-classic-v1` query definitions.

## Contents

- [Runtime](#runtime)
- [Prometheus-Compatible Endpoint](#prometheus-compatible-endpoint)
- [Authenticated Grafana Datasource Proxy](#authenticated-grafana-datasource-proxy)
- [Clinic Data Proxy](#clinic-data-proxy)
- [Shared Scope Options](#shared-scope-options)
- [Outputs and Exit Status](#outputs-and-exit-status)

## Runtime

Use Node with global `fetch` and `WebSocket` support; Node 22+ is recommended. Run commands from
the skill directory.

## Prometheus-Compatible Endpoint

```bash
node scripts/collect-rc-report.mjs \
  --profile dedicated-classic-v1 \
  --prometheus-url "http://prometheus.example.com" \
  --from "2026-01-01T00:00:00+08:00" \
  --to "2026-01-02T00:00:00+08:00" \
  --k8s-cluster "<k8s_cluster>" \
  --tidb-cluster "<tidb_cluster>" \
  --target-groups "<target_resource_groups>" \
  --target-group-types "<target_group>=<ddl|analyze|batch|custom>" \
  --out-dir ./ru-based-rc-inspection
```

## Authenticated Grafana Datasource Proxy

Use an already logged-in Chrome session:

```bash
node scripts/collect-rc-report.mjs \
  --profile dedicated-classic-v1 \
  --grafana-url "https://grafana.example.com/d/<uid>/<slug>" \
  --datasource-id "<prometheus-datasource-id>" \
  --cdp "http://127.0.0.1:9222" \
  --from "2026-01-01T00:00:00+08:00" \
  --to "2026-01-02T00:00:00+08:00" \
  --k8s-cluster "<k8s_cluster>" \
  --tidb-cluster "<tidb_cluster>" \
  --target-groups "<target_resource_groups>" \
  --target-group-types "<target_group>=<ddl|analyze|batch|custom>" \
  --out-dir ./ru-based-rc-inspection
```

## Clinic Data Proxy

Query one Cloud cluster:

```bash
node scripts/collect-rc-report.mjs \
  --profile dedicated-classic-v1 \
  --clinic-cluster-id "<clinic_cluster_id>" \
  --env-file "/path/to/local/.env" \
  --from "2026-01-01T00:00:00+08:00" \
  --to "2026-01-02T00:00:00+08:00" \
  --matchers 'tidb_cluster_id="<clinic_cluster_id>",tidb_cluster="<tidb_cluster>"' \
  --tidb-component-matchers 'tidb_cluster_id="<clinic_cluster_id>",tidb_cluster="<tidb_cluster>",component="tidb"' \
  --tikv-matchers 'tidb_cluster_id="<clinic_cluster_id>",tidb_cluster="<tidb_cluster>",component="tikv"' \
  --target-groups "<target_resource_groups>" \
  --target-group-types "<target_group>=<ddl|analyze|batch|custom>" \
  --out-dir ./ru-based-rc-inspection
```

Clinic mode reads `CLINIC_API_KEY` from the process environment or the explicit `--env-file` and
keeps the key out of report artifacts.

## Shared Scope Options

- Use `--matchers`, `--tidb-matchers`, and `--tikv-matchers` when dashboard labels differ from the
  defaults.
- Use `--business-groups` to add known non-target groups for concurrency comparison. Conclusions
  cover those groups plus global SQL signals.
- Use `--target-group-types` for custom group names, for example
  `rg_maintenance=ddl,rg_stats_job=analyze,rg_nightly=batch`. Use `custom` when the workload type is
  outside DDL/Analyze/Batch semantics; core RU-limit judgment still runs while global progress and
  tail correlation remain outside scope.
- Override component matchers when the datasource uses labels such as `component` instead of the
  default `job` labels. Preserve cluster and applicable keyspace scope in matcher overrides.
- Use `--keyspace-name` or `--keyspace-matcher` when resource-group names are not cluster-unique.
- Supply credentials through the authenticated datasource session or Clinic environment. The
  command-line `--header` option accepts only non-sensitive request headers.

`--out-dir` accepts an absolute path or a path relative to the current working directory. When
omitted, the collector creates `ru-based-rc-inspection-<timestamp>` in the current working
directory.

## Outputs and Exit Status

On normal completion, both commands write a JSON result to stdout.

| Command | Exit | Meaning |
|---|---:|---|
| collector | `0` | Artifacts were generated and `deliveryReady=true`. |
| collector | `2` | Diagnostic artifacts were generated with `deliveryReady=false` because datasource, query, or coverage checks failed. |
| collector | `1` | Fatal validation, fetcher setup, or artifact writing failed; stderr contains a plain-text error and outputs may be absent or incomplete. |
| verifier | `0` | Required private artifacts, pinned contract metadata, and the stored data-quality result are internally consistent. |
| verifier | `1` | Lightweight verification failed; keep the report exploratory and non-final. |