---
name: pd-oncall-handbook
description: |
  Entry skill for PD on-call diagnosis.
  Use when triaging PD incidents involving placement rules, region health checks,
  scheduler behavior, resource control, TSO pressure, ETCD capacity, TLS,
  or Dashboard operational issues. Includes routing guidance, first-response
  checks, and links to specialized PD diagnosis skills.
---

# PD Oncall Handbook

Entry guide for PD on-call diagnosis. Use this skill first to classify the incident,
then continue with the specialized PD skill for that symptom family.

Source note: adapted from the Feishu `PD oncall handbook` <https://pingcap.feishu.cn/wiki/E5KkwI6VJiFA4nkcaVEcDhWonqu>.

## Skill Family

- `pd-placement-rules`: placement rules, isolation labels, leader imbalance after rule changes
- `pd-scheduling`: region checker behavior, balance-region, scatter-range, evict-leader, merge-related scheduling
- `pd-resource-control`: RU, token buckets, resource group throttling, runaway and queuing anomalies
- `pd-operations`: ETCD capacity, TLS, Dashboard behavior, Prometheus scraping, PD leader CPU and TSO pressure

## Routing Guide

| If you see... | Read this skill |
| --- | --- |
| placement rules reset, isolation labels fail, SQL placement policy surprises | `skills/diagnosis/pd-placement-rules/SKILL.md` |
| region health metrics drift, balance-region storms, scatter conflicts, evict-leader anomalies | `skills/diagnosis/pd-scheduling/SKILL.md` |
| RU drops to zero, `Time_queued_by_rc` is long, resource group quota errors, token bucket anomalies | `skills/diagnosis/pd-resource-control/SKILL.md` |
| ETCD full, TLS enable failure, Dashboard issues, missing PD leader metrics, PD leader CPU or TSO pressure | `skills/diagnosis/pd-operations/SKILL.md` |

## First Response Checklist

- Confirm whether the impact is control-plane only, data-plane visible, or both.
- Capture the first abnormal PD log around the incident start time.
- Record the exact PD, TiKV, TiDB, TiCDC, and TiFlash versions.
- Check whether recent operations include placement-rule changes, scale-in or scale-out, TLS changes, disk expansion, `DISTRIBUTE TABLE`, `scatter`, `evict-leader`, or resource-group configuration.
- Decide whether the immediate risk is loss of scheduling, loss of TSO service, degraded balance quality, or a dashboard-only issue.

## Common Commands

```bash
tiup cluster display <cluster-name>
tiup ctl:<version> pd -u http://<pd>:2379 health
tiup ctl:<version> pd -u http://<pd>:2379 scheduler show
tiup ctl:<version> pd -u http://<pd>:2379 config show
tiup ctl:<version> pd -u http://<pd>:2379 config placement-rule show
tiup ctl:<version> pd -u http://<pd>:2379 store
curl http://<pd>:2379/metrics
```

## Specialized Skills

- `skills/diagnosis/pd-placement-rules/SKILL.md`
- `skills/diagnosis/pd-scheduling/SKILL.md`
- `skills/diagnosis/pd-resource-control/SKILL.md`
- `skills/diagnosis/pd-operations/SKILL.md`

## Triage Hints

- If replicas end up on the same host, placement rules reset, or table-level placement behaves unexpectedly, start with `pd-placement-rules`.
- If the issue appears after `scatter`, `evict-leader`, balance-region, merge, or low-space transitions, start with `pd-scheduling`.
- If latency is explained by RU throttling, token acquisition, or resource-group behavior, start with `pd-resource-control`.
- If PD leader CPU, TSO pressure, ETCD capacity, TLS rollout, Dashboard, or Prometheus scrape health is the main concern, start with `pd-operations`.