Scenario 07.2.2 · Quotas: throttling a producer
producer_byte_rate: how a Kafka client quota throttles
producer_byte_rate, a broker-enforced client quota, caps a producer's write throughput: a burst over the per-second byte budget is throttled - its records delayed - until the average rate falls back under quota.
Run this scenario in the playgroundA producer under a quota. t+0.000s
p1 has a producer_byte_rate quota of 2048 B/s - a budget of exactly two 1 KiB records per second. In Kafka this client quota is set on the broker per user or client-id (kafka-configs.sh); the simulator shows it on the producer. Nothing has been produced yet.
Open at this step: step 1, A producer under a quotaWithin budget - 2 records acked. t+1.400s
p1 wrote two records this window (2048 bytes = the full 1-second allotment). That is AT the quota, not over it, so the batch commits immediately - offsets 0 and 1. This is the un-throttled baseline.
Open at this step: step 2, Within budget - 2 records ackedOver budget - throttled 1000 ms. t+2.800s
A fresh window: p1 flushes FOUR records at once (4096 bytes = double the 2048-byte budget). The broker throttles p1 for (4096−2048)/2048×1000 = 1000 ms. The card reads 'throttled · 1000 ms', and the simulator holds the batch back: the log still shows only the two earlier records. (Real Kafka appends the batch, returns a throttle time and holds p1's next requests instead.)
Open at this step: step 3, Over budget - throttled 1000 msThrottle still holding. t+3.400s
Mid-throttle: the four records are buffered behind the 1000 ms delay and the partition log is unchanged. This held-back second is how the simulator drags p1's average rate back down to its quota.
Open at this step: step 4, Throttle still holdingRecovered - rate held to quota. t+3.900s
The 1000 ms throttle has elapsed, so the deferred batch appends (offsets 2-5) and p1 is acked. Six records landed across ~2.9 s - paced to roughly the 2 records/second quota. No data was rejected, only delayed; every record is present, in order.
Open at this step: step 5, Recovered - rate held to quotaWhat you start with
producer_byte_rate is a client quota: a write ceiling in bytes per second that the broker enforces per user and/or client-id, set with kafka-configs.sh rather than in the producer's config (the simulator shows it on the producer for convenience). The broker meters the bytes a producer writes inside a rolling window; once the window total exceeds the rate it THROTTLES the producer - holding back its next batch just long enough that average throughput falls back to the quota. p1 is capped at 2048 B/s (a budget of ≈2 records/s): one window stays within budget, the next bursts to four records and is throttled for a second before the deferred records land. (The simulator holds back the offending batch itself; Kafka appends it and delays the requests after it.)
Step by step
- A producer under a quota t+0.000s p1 has a producer_byte_rate quota of 2048 B/s - a budget of exactly two 1 KiB records per second. In Kafka this client quota is set on the broker per user or client-id (kafka-configs.sh); the simulator shows it on the producer. Nothing has been produced yet. Open at this step: step 1, A producer under a quota
- Within budget - 2 records acked t+1.400s p1 wrote two records this window (2048 bytes = the full 1-second allotment). That is AT the quota, not over it, so the batch commits immediately - offsets 0 and 1. This is the un-throttled baseline. Open at this step: step 2, Within budget - 2 records acked
- Over budget - throttled 1000 ms t+2.800s A fresh window: p1 flushes FOUR records at once (4096 bytes = double the 2048-byte budget). The broker throttles p1 for (4096−2048)/2048×1000 = 1000 ms. The card reads 'throttled · 1000 ms', and the simulator holds the batch back: the log still shows only the two earlier records. (Real Kafka appends the batch, returns a throttle time and holds p1's next requests instead.) Open at this step: step 3, Over budget - throttled 1000 ms
- Throttle still holding t+3.400s Mid-throttle: the four records are buffered behind the 1000 ms delay and the partition log is unchanged. This held-back second is how the simulator drags p1's average rate back down to its quota. Open at this step: step 4, Throttle still holding
- Recovered - rate held to quota t+3.900s The 1000 ms throttle has elapsed, so the deferred batch appends (offsets 2-5) and p1 is acked. Six records landed across ~2.9 s - paced to roughly the 2 records/second quota. No data was rejected, only delayed; every record is present, in order. Open at this step: step 5, Recovered - rate held to quota
The takeaway
Quotas shape the RATE, not the data - every record still lands exactly once and in produce order, just spread out so a noisy producer can’t starve the cluster.
Embed this scenario
Paste this into a blog post, a course page or your team's docs. The scenario plays inside your page, and the link under it points readers to this walkthrough.
<iframe src="https://monedula.dev/kafka-simulator/embed/?scenario=07.2.2" title="Kafka Simulator: Quotas: throttling a producer" width="100%" height="520" style="border:1px solid #d0d0d0;border-radius:8px" loading="lazy"></iframe>
<p><a href="https://monedula.dev/kafka-simulator/scenarios/quotas-throttling/">producer_byte_rate: how a Kafka client quota throttles</a></p>