Skip to content

CONCEPT Cited by 1 source

Throttler metric scope

Definition

A metric scope is the unit of the system over which a throttling metric is meaningful. Two scopes show up in sharded-MySQL deployments:

  • Shard scope — the metric aggregates across all replicas in a replication topology. Canonical example: replication lag — the shard is unhealthy if any replica is lagging, so the shard-scope value is the max replica lag.
  • Host scope — the metric is local to a single machine (CPU, disk I/O, page-cache pressure, OS load average). Unhealthy on this host is not unhealthy on its peers.

"This introduces the concept of a metric's scope, which can be an entire shard or a specific host in this scenario."

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

Which scope goes with which workload

The post spells out two worked examples:

Massive shard-primary writes → shard scope.

  • A large write on the primary replicates to every replica.
  • If any one replica is already lagging, a massive write would extend that lag further.
  • The client consults the shard-scope throttler (the primary's throttler) which rolls up all replicas' lag metrics and returns the max.

Massive single-replica reads → host scope.

  • A big read on one replica pollutes its page cache and overloads its disk I/O, not the other replicas'.
  • Other replicas' replication performance is unaffected.
  • "The client can therefore suffice in checking the throttler on the specific replicas, ignoring any metrics from other servers."

Why this matters architecturally

Scope is not a throttler-side configuration — it is a client-side routing decision. A client chooses which throttler to ask based on which metric is relevant to its workload. This means:

  1. The per-host + shard-primary-rollup hierarchy directly maps to the scopes: each vttablet throttler is host-scope; the shard-primary's throttler is shard-scope.
  2. Clients need a model of which workloads need which scope — this becomes part of the API contract.
  3. Cross-scope aggregation is limited: "Different shards represent distinct architectural elements, and there is no cross-shard throttler communication."

Sources of scope confusion

  • Using a shard-scope metric to throttle a host-scope workload: overly conservative, underutilises the other replicas.
  • Using a host-scope metric to throttle a shard-scope workload: dangerously optimistic, can extend max-lag and fail the shard-scope SLO.

Seen in

Last updated · 319 distilled / 1,201 read