Applied Rate Ceiling

The single most common mistake with Gatling's `throttle(...)` is reading it as a load setting. It is not one. A throttle is a **valve, not a pump**: it can close down on traffic the simulation is already producing, and it has no way whatever of producing more. ## Why a 200 rps ceiling can finish at 120 Gatling's throughput comes from two places, and neither of them is the throttle: 1. **The injection profile** decides how many virtual users arrive, and when. 2. **The scenario** decides how many requests each of those users issues before it finishes. Multiply those together and you get the traffic the simulation offers. The throttler sits downstream of that: each second it computes the current ceiling from the throttle profile, lets that many requests through, and defers the rest. If the offered traffic is 120 requests per second and the ceiling is 200, the ceiling is simply never reached, and the report shows about 120. Gatling's own documentation states the limit plainly — a throttle *"can't generate a throughput that's higher than the one normally generated by your simulation once pauses are disabled"*. The fix is never to raise the throttle. It is to change the injection profile — more users per second, or a longer or steeper ramp — or to change the scenario so each user does more work. ## The one thing a throttle does raise There is exactly one way a throttle increases throughput, and it is a side effect rather than a feature: **switching a throttle on disables pauses**. When Gatling builds a population it resolves the pause policy, and if that population is throttled it forces the policy to disabled and logs *"Throttle is enabled, disabling pauses"*. Every `pause(...)` that takes that policy — which means every pause declared without an explicit pause type — then becomes a no-op, and the virtual user goes straight to its next action. Three details matter about that: * **It overrides what you declared.** A population that asks for `exponentialPauses()` still gets no pauses from that policy if it is throttled. The throttle's decision wins over the declared pause policy. * **The scope follows where the throttle was attached.** A throttle on `setUp` disables pauses in every population of the run. A `.throttle(...)` on a single injected population disables pauses only in that population; the others keep waiting normally. * **It is the pause policy, not every waiting construct.** The policy layer the throttle overrides is the one that `disablePauses`, `constantPauses` and their siblings set, and two constructs are not built from it. A `pace(...)` step is a different action driven by its own counter, so it keeps regulating its own loop. And any `pause(...)` overload given an explicit pause type — `pause(Duration.ofSeconds(5), constantPauses)` in Java or Kotlin, `pause(5.seconds, constantPauses)` in Scala — still waits, because Gatling builds each pause from `force.getOrElse(ctx.pauseType)` and the per-step force beats the throttle-resolved disabled policy. Gatling's own documentation states the unqualified version — a throttle *"disables all the pauses"* — so that exception is visible only in the source. ## Reading the report Two runs of the same simulation, one throttled and one not, are therefore **not** comparable in the way people expect. The throttled run has no think time left in it beyond whatever its pauses forced for themselves, so its virtual users cycle faster, hold fewer concurrent sessions, and hit the target in a much tighter pattern. If a suite switches a throttle on to "cap" a run, it has also silently deleted every pause the scenario declared without a pause type of its own. | you want | the construct that does it | |---|---| | more traffic | change the injection profile or the scenario | | a hard ceiling on traffic | `throttle(...)` on `setUp` or a population | | no waiting between actions | the pause policy, e.g. `disablePauses` | | a ceiling that also silently removes waiting | `throttle(...)` — this is the trap | | waiting that survives a throttle | `pace(...)`, or a `pause(...)` given an explicit pause type | ## Why the documentation pushes back Gatling's own guidance is that if each virtual user performs one request, you should express the rate in the **injection profile** instead, with an open-model step such as `constantUsersPerSec`. Its warning about multi-request scenarios is about fairness: the throttler grants the second's budget to whichever request asks first, so in a scenario with several different requests the distribution between them *"is likely to be unbalanced"*. You get 200 requests per second, but you do not get to say which 200. ## What to check when the number is short When a throttled run comes in under its ceiling, work outward in this order: 1. Confirm the offered traffic. Users per second times requests per user is the real cap. 2. Check the protocol. Throttling covers HTTP requests and JMS only, so requests issued over WebSocket or SSE never consult the throttler and never count toward the ceiling either. 3. Check the ramp. `reachRps(200).in(30)` spends the first thirty seconds below 200 by design, so a short run can average well under the plateau. 4. Check the response times. A ceiling is expressed per second of wall clock; if the system under test is slow enough that the simulation cannot issue the requests, the ceiling is irrelevant.