# PD, TSO, And Control Plane

## Question

Is latency or instability in the TiDB client path, PD TSO handling, PD process,
or the underlying etcd leadership/storage path?

## Enter When

Use for StartTS/TSO wait, PD request latency, PD leader change, etcd election,
control-plane availability, or scheduling service symptoms.

## Anchor And Window

Start from the direct alert or user-visible result. Record its exact entity,
timestamp or interval, timezone, and sample period. Use a 2-5 minute first
window around that anchor. Use a wider window only to discover the incident;
re-query load-bearing evidence in the narrow window before causal synthesis.

When compact evidence exposes only a maximum over the window and omits the
maximum's timestamp, call it `window-aligned`. Do not claim exact simultaneity,
ordering, or a point-aligned causal chain.

## Required Causal Chain

1. Establish the direct result on its affected entity: TSO/StartTS latency,
   exact TiDB backoff type, request latency, error, or user-visible Duration.
2. Establish one control-plane counterpart on the same narrow window:
   - align TiDB TSO client/request latency with PD TSO handler/server latency;
     or
   - align exact TiDB `pdRPC` backoff with PD handler/server behavior.
3. Check PD leader/term evidence and process continuity. Distinguish a leader
   change, process restart, scrape loss, and a continuously running process.
   Process uptime and `up` do not satisfy the leader/term check. When the
   provider supports Prometheus reads, test a leader, term, campaign, or
   equivalent leadership-continuity metric before finalizing.
4. Check the strongest same-window deeper alternative:
   - etcd WAL fsync/backend commit/disk latency on the affected PD; or
   - one direct host/network signal on the affected hop or host.

Write every provider command to a distinct child path, for example:

```text
evidence/scenarios/pd-tso-control-plane/direct-result/
evidence/scenarios/pd-tso-control-plane/server-counterpart/
evidence/scenarios/pd-tso-control-plane/leadership-continuity/
evidence/scenarios/pd-tso-control-plane/strongest-alternative/
```

## Decision

- Client rises while PD server handling stays stable: keep the boundary at the
  client/network path.
- Both rise on aligned samples: investigate PD handling/load before deeper
  attribution.
- Distinguish PD leader stepdown from etcd leader reelection using direct logs
  or term/campaign evidence.
- PD/etcd peer RTT plus generic TiKV-client backoff or Duration establishes
  only service-path correlation. It does not confirm a PD/TSO/control-plane
  mechanism without the required client/server or exact `pdRPC` counterpart.
- Peer RTT alone does not prove network. PD/etcd server stalls, WAL/backend
  latency, disk latency, and host pauses remain alternatives until one direct
  same-window signal distinguishes them.
- Current `up=1` or recovered latency proves recovery only. It does not answer
  the historical trigger.

Logical TSO exhaustion, PD CPU load, etcd latency, excessive region/control
work, and network are hypotheses until their direct signals align.

## Strongest Alternative And Stop

Compare one normal peer/sample, the required client/server counterpart, and
the strongest same-window WAL/backend/disk or direct host/network alternative.
Exclude cross-cluster or historical-ticket matches from `directEvidence` and
final **Key Evidence**.

Stop with a bounded root cause and one exact missing signal when the chain is
not complete. If that signal is available through the current read-only
provider and can change the leading cause, severity, safety decision, or
recommendation, return it as a load-bearing `diagnosticFollowup` with an
observable stop condition. Do not label an available metric as an unavailable
provider gap. In particular, do not finalize with only process continuity when
leader/term availability has not been tested: query it in the current evidence
turn, or return the exact leadership query as `diagnosticFollowup`.

Before final output, classify each client/server relationship as point-aligned
or `window-aligned`. If `pdRPC`, TSO, or another load-bearing compact result
contains only a window maximum without its timestamp, use the literal
`window-aligned` label in both the internal finding and customer draft. A
point-aligned etcd storage stall plus window-aligned `pdRPC` backoff is a
bounded likely service-path mechanism; it is not proof that the storage sample
caused that client maximum.