CONCEPT Cited by 1 source

Throttler client identity¶

Definition¶

Throttler client identity is a (usually hierarchical) identifier that a client presents — or that a throttler reconstructs — for each throttler.check() call, so the throttler can distinguish between clients for both observability (who was throttled when, and why) and operational control (prioritise this job, de-prioritise that category, exempt this essential component).

"Client identification also serves operational purposes. Is it possible to prioritize one specific job over others? Or perhaps tune one down, or put it entirely on hold for a while? How about prioritizing a category of clients? Such questions can only be answered if we can clearly distinguish between clients."

— Shlomi Noach, Source: sources/2026-04-21-planetscale-anatomy-of-a-throttler-part-3

Why identity matters¶

Without identity, the throttler has one knob: the system health metric. Every client is treated identically; the only way to differentiate load sources is to set different metric thresholds, which is a poor fit for the problem — thresholds express what's healthy for the database, not how important any given workload is.

With identity, the throttler gains two orthogonal knobs:

Per-identity rejection ratio (see patterns/probabilistic-rejection-prioritization) — spend more/less of the admission budget on specific clients.
Per-identity rule overlays — exempt, block, route differently, apply stricter thresholds to certain identities.

And one load-bearing observability shift:

Per-identity access pattern analysis — "you want to know which operations were being throttled at what time. You want to be able to tell that the daily aggregation ETL job was mostly throttled between 07:00 and 07:25." The throttler log becomes the queryable surface for "what was backing off on what metric when".

Hierarchical identity scheme¶

Flat identifiers (one opaque string per client) limit rules to the exact-match level. Hierarchical identifiers compose specific and categorical rules.

Canonical Vitess example:

d666bbfc_169e_11ef_b0b3_0a43f95f28a3:vcopier:vreplication:online-ddl

Decomposition, right-to-left reads most-specific first:

Level	Example	Purpose
`online-ddl`	job category	"de-prioritise all online-DDL jobs between 9 AM and 5 PM"
`vreplication`	subsystem	"exempt VReplication during an ongoing shard split"
`vcopier`	flow within subsystem	"throttle the copy phase harder than the catch-up phase"
`d666bbfc...`	UUID	"pause this one job while investigating a stuck shard"

"With this identity scheme, it is possible to categorically prioritize (or de-prioritize) all online-ddl jobs, or just this very specific job, or alternatively exempt all vcopier flows entirely. Observability-wise, this makes it easier to analyze throttler access patterns by categories of requests."

Identity in collaborative vs enforcement throttlers¶

In the collaborative model, identity comes for free — the client tells the throttler who it is on every check, because the client is code that knows its own purpose.

In the enforcement model, identity is an inference problem. "It's more complicated to identify the clients, and the throttler must rely on domain-specific attributes made available by the client/connection/query to be able to distinguish between clients and implement any needed prioritization." Inference surfaces include:

SQL comments (SQLCommenter-style tags)
Connection attributes / session variables
Authentication scope / service identity
Query shape (e.g. bulk writes vs point reads)
Upstream proxy tags / connection source

Failure modes without identity¶

Starvation blindness. A rogue client pushing the metric above threshold is indistinguishable from "the database is under general load" — operators can't pinpoint the offender.
No categorical rules possible. An operator who wants "de-prioritise all background ETLs during the black-Friday window" has to enumerate every ETL by some out-of-band mechanism.
Audit is qualitative. Post-incident analysis can tell that throttling happened but not whose work was affected.

Seen in¶

sources/2026-04-21-planetscale-anatomy-of-a-throttler-part-3 — canonical wiki introduction. Shlomi Noach walks through the observability + operational-control motivations and presents the Vitess 4-level hierarchical scheme as the canonical working example.