Explain how the broker measures rate and computes the throttle delay, including the role of quota.window.size.seconds and quota.window.num.

## The measurement model Kafka doesn't measure an instantaneous rate; it uses a **sampled sliding window**. Two broker configs define it: - **`quota.window.size.seconds`** (default **1**): the duration of one sample bucket. - **`quota.window.num`** (default **11**): how many consecutive sample buckets are retained. Together they form an observation window of about `(num − 1) × size` ≈ **10 seconds**. The broker keeps a `Rate` metric per client entity: each incoming byte/request adds to the current bucket; old buckets age out as time advances. The measured rate is total recorded value divided by the elapsed window time. ## Computing the throttle delay When a new request arrives, the broker records its bytes, then asks the sensor whether the windowed average exceeds the quota `Q`. If it does, it computes the delay needed to bring the average back to `Q`: ``` delayMs ≈ (observedRate − Q) / Q × windowDurationMs ``` Intuitively: "the client has produced X bytes too many; at rate Q those extra bytes would take this long, so pause that long." The delay is **bounded** by the window size so a single huge spike can't cause an unbounded stall. The value is returned to the client in the response field **`throttle_time_ms`**. ## How the delay is applied (cold throttling) For produce and fetch quotas, the broker **completes the operation but holds the response**: it mutes (stops reading from) the client's network channel for `throttle_time_ms`, then sends the response. This is **cold throttling** — the client is paused at the channel level, which naturally back-pressures its send/receive loop. The client also exposes throttle time via JMX (`produce-throttle-time-avg`, `fetch-throttle-time-max`), so you can detect throttling without broker access. Request-percentage quotas throttle similarly based on accumulated thread time. ## Why a window instead of an instant limit Real traffic is bursty. An instantaneous limit would reject normal micro-bursts. The window **amortizes** bursts: a client can briefly exceed `Q` as long as the windowed average stays at or below `Q`. After a burst, subsequent requests get throttled until the average recovers. ## Tuning trade-offs - **Smaller `quota.window.size.seconds` / fewer samples** → faster reaction, tighter conformance, but less tolerance for legitimate bursts and more throttle churn. - **Larger window** → smoother, more burst-tolerant, but slower to clamp a runaway client, so worst-case noisy-neighbor impact lasts longer. ## Edge cases - A single record/fetch **larger than the quota** is allowed through once (otherwise it could never be delivered), then the client is throttled hard on the next requests. - These window configs are **static broker configs** (set in `server.properties`, restart to change), whereas the **quota values** are dynamic. People often conflate the two. - Throttle delay is capped at the window duration, so the maximum single-response delay is roughly `quota.window.size.seconds × quota.window.num` is NOT the cap — the cap is the window *size* used by the rate's delay calc; in practice delays are capped to one window length.