# Metric-Name Discovery via the PSC Panel Knowledge Base

Use this when the metric you need is not in the sweep evidence, the latency-breakdown reference, or the loaded metric recipes — typically components the recipe docs do not cover (TiCDC/changefeed, TiFlash, PD internals, DM, backup/restore). Never guess `--name`/`--query` values one command at a time: each miss costs a full LLM round trip, and the knowledge base almost certainly has the panel (the TiCDC dashboards alone contribute ~200 panels).

## The knowledge base

`/opt/agentkit/data/psc_knowledge_base_<tier>.json` (repo copy: `agentkit/data/`) — a JSON list of ~1700 dashboard panels:

```json
{"dashboard": "...", "title": "...", "group": "...", "component": "TIKV",
 "used_for": "...", "promql": ["..."], "variables": ["k8s_cluster", "tidb_cluster"]}
```

Pick the file by cluster tier (full rules in the `grafana-panel-finder` skill):

- `dedicated` → `psc_knowledge_base_dedicated_v8.5.x.json` (or the file matching `tidb_version`)
- `starter` / `essential` / `shared` → `psc_knowledge_base_serverless.json`
- `premium` / `nextgen-host` → `psc_knowledge_base_nextgen.json`

## Lookup

One call lists every candidate panel with ready-to-use PromQL:

```bash
python3 - <<'PY'
import json, glob
paths = sorted(glob.glob('/opt/agentkit/data/psc_knowledge_base_dedicated_*.json')
               or glob.glob('/opt/agentkit/data/psc_knowledge_base_*.json'))
panels = json.load(open(paths[-1]))  # pick the file matching the cluster tier
needle = 'ticdc'  # component / dashboard / title keyword
for p in panels:
    hay = ' '.join(str(p.get(k, '')) for k in ('component', 'dashboard', 'title', 'group')).lower()
    if needle in hay:
        exprs = p['promql'] if isinstance(p['promql'], list) else [str(p['promql'])]
        print(f"{p['dashboard']} | {p['group']} | {p['title']} | {'; '.join(exprs)[:160]}")
PY
```

`jq` works too: `jq '[.[] | select(.component == "TIKV" and .title == "CPU")]' <psc_file>`.

## Execute

Take the metric names and PromQL from the matching panels, then run a handful of `clinic-cli metrics` commands — not a guess-per-call loop. Before running, resolve the Grafana template variables in the PromQL (`$k8s_cluster`, `$tidb_cluster`, `$namespace`, `$instance`, `$changefeed`, `$__rate_interval`, ...): substitute concrete label values for the target cluster/entity, or drop a matcher entirely when it only broadens scope. Do not invent PromQL when a panel exists; do not send template variables to the API verbatim.