Configure the JMeter Throughput Controller logic controllers: properties, defaults, and practical usage notes for building reliable load tests.
Part of the Logic Controllers category. Also documented in context in the full Component Reference.
TL;DR: the Throughput Controller runs its children only a percentage of the time (or an exact total count), letting you model realistic traffic mixes — e.g. 70% browse, 20% search, 10% checkout — inside one Thread Group.
The Throughput Controller allows the user to control how often it is executed. There are two modes:
- percent execution
- total executions
Percent executions
: causes the controller to execute a certain percentage of the iterations through the test plan.
Total executions
: causes the controller to stop executing after a certain number of executions have occurred.
Like the Once Only Controller, this setting is reset when a parent Loop Controller restarts.
| Name | Required | Description |
|---|---|---|
| Name | No | Descriptive name for this controller that is shown in the tree. |
| Execution Style | Yes | Whether the controller will run in percent executions or total executions mode. |
| Throughput | Yes | A number. For percent execution mode, a number from 0-100 that indicates the percentage of times the controller will execute. “50” means the controller will execute during half the iterations through the test plan. For total execution mode, the number indicates the total number of times the controller will execute. |
| Per User | No | If checked, per user will cause the controller to calculate whether it should execute on a per user (per thread) basis. If unchecked, then the calculation will be global for all users. For example, if using total execution mode, and uncheck “per user”, then the number given for throughput will be the total number of executions made. If “per user” is checked, then the total number of executions would be the number of users times the number given for throughput. |
Common gotchas
Section titled “Common gotchas”- “Percent Execution” is evaluated per-thread, per-loop — it’s a probability each time the controller is reached, not a hard global ratio across the whole test. Over a long run the actual percentage converges close to the target, but short tests can drift.
- “Total Executions” runs the children an exact number of times total across all threads, then goes idle — different semantics from percent mode, useful for “run this exactly N times regardless of load.”
- If overall throughput looks stuck regardless of this controller’s settings, the bottleneck is usually elsewhere (threads, pacing, or the target service) — see Throughput stuck.
- Combine with a Constant Throughput Timer when you need an absolute requests/minute cap rather than a relative execution ratio.