Open Model & Throughput Control

The JMeter best-practices page warns that a load test with incorrectly sized threads faces the "Coordinated Omission" problem, which can give wrong or inaccurate results. The page does not explain the mechanism; the explanation below is a worked illustration of the closed versus open behaviour, with numbers chosen for this page.

Take a Bookshelf search endpoint with a response time of 0.2 s, driven for 60 s at 20 requests per second, and a server stall of 10 s between t = 20 s and t = 30 s (a long garbage collection pause or a lock held by a batch job).

Same server, same stall, same average rate: the closed run reports a healthy p99 of 0.2 s and the open run a p99 of more than 9 s. The open result is what 20 independent users per second would have experienced. The figure shows the two runs side by side.

The closed model is not wrong; it is the right model when the population really is fixed (an internal tool with 50 operators, a pool of 8 batch workers). It is the wrong model for traffic whose arrivals do not wait for the previous response, which is most public HTTP traffic. If a closed model must be used for open traffic, give it enough threads that the population never runs out during a slow period, and read the percentiles with this bias in mind.

Source: Best Practices (Apache JMeter User Manual)

The component reference describes the schedule; the runtime behaviour below is what the 5.6.3 source code of the element does (the class documentation of OpenModelThreadGroup and OpenModelThreadGroupController), since the manual does not describe it:

Because every arrival is a new user, a journey under the Open Model Thread Group usually starts with its own log-in, and a CSV Data Set Config with the default sharing mode hands each arrival the next line of the file. This is exactly how independent visitors behave, but it differs from a Thread Group where one thread logs in once and loops.

The component reference lists three parameters. The 5.6.3 GUI also shows the panel common to all thread groups, Action to be taken after a Sampler error, which comes from the shared thread group GUI class.

There is no field for the maximum number of threads, and no ramp-up or duration field: the schedule defines both the ramp and the duration. In 5.6.3 the GUI editor offers four template buttons above the schedule text area that insert rate(1/min), random_arrivals(10 min), pause(1 min) and /* comment */, and below it a summary line of the form Total duration: …​, max rate: …​ and a small chart of the target rate over time. The summary and the chart are recomputed as you type, which is the quickest way to check a schedule before running it.

Source: Open Model Thread Group (Component Reference)

A schedule is a sequence of commands separated by spaces or new lines. The load profile is a sequence of constant, increasing or decreasing load segments.

The rules about the implicit start and finish rates are the part most often misread. The manual gives these equivalences:

Two details matter when writing schedules by hand. First, a bare number in rate without a unit is only documented for 0; always write the unit, for example rate(10/sec), so the intent is clear (the manual’s own example rate(10) random_arrivals(1 min) ... is described as 10 requests per second, but relying on that is not necessary). Second, "random arrivals" means the gaps between arrivals are random, as they are for independent visitors; the average rate follows the schedule, but individual seconds contain more or fewer arrivals than the target.

Source: Open Model Thread Group (Component Reference)

The section’s arrival-rate profile ramps from 5 to 20 arrivals per second over five minutes. Written out with comments:

Worked numbers: the ramp segment averages \((5 + 20) / 2 = 12.5\) arrivals per second for 300 s, about 3750 arrivals; the hold segment is \(20 \times 600 = 12000\) arrivals; the pause adds none. The run lasts 16 minutes and sends about 15750 requests. With a search response time of 0.2 s, Little’s Law gives an average of \(20 \times 0.2 = 4\) requests in flight at full rate, so roughly 4 threads alive at any moment even though 15750 threads are created in total.

Source: Open Model Thread Group (Component Reference)

The schedule field accepts JMeter functions, which are evaluated once when the test starts. The manual shows two uses.

Parameterise from properties. Read the rates and the duration from -J properties so that one plan serves the smoke, load and soak runs:

The manual’s own form is rate(${__P(beginRate,40)}) random_arrivals(${__P(testDuration, 10)} sec) rate(${__P(endRate,40)}); the variant above writes the units explicitly.

Generate steps with Groovy. The schedule language has no loop, but __groovy can build the string. The manual’s example generates ten 10-second steps of 10, 20, …​, 100 arrivals per second:

For a Bookshelf stress test that climbs in eight two-minute steps from 5 to 40 arrivals per second:

This expands to rate(5/sec) random_arrivals(2 min) pause(1 sec) rate(10/sec) random_arrivals(2 min) pause(1 sec) .... Each step is a constant segment (no finishing rate follows random_arrivals directly), followed by a one-second pause with no new arrivals, which is how the manual’s example builds its steps. The whole schedule lasts \(8 \times 121 = 968\) s. Function arguments that contain a comma must escape it as \,; neither script above contains one. Because the profile is evaluated once, a function such as __time or __Random in the schedule yields a single value for the whole run, not a changing rate.

Source: Open Model Thread Group (Component Reference)

With the default seed 0 the arrival times differ on every run. Set a constant non-zero seed (any number, for example 42) when two runs must be compared second by second, for instance before and after a code change, so that the same burst of close arrivals happens at the same moment both times. Give each Open Model Thread Group in a plan a different seed; the manual recommends different seeds per thread group, and identical seeds with identical schedules would fire arrivals at the same instants.

There is no upper bound on the number of threads in 5.6.3. The number alive at any moment is the arrival rate multiplied by the time each arrival spends in the plan (its journey time, including timers). This is the open model working as intended, but it has consequences for the load generator:

The heap and the HEAP setting are covered in Installation & Configuration.

The thread group interrupts its threads when the schedule ends. A schedule that ends with random_arrivals(10 min) stops the arrivals at 10 minutes and interrupts any request still in flight at that instant, which shows up as errors in the last second of the results. The manual’s advice is to add a pause at the end, for example pause(5 min), to give the threads time to complete. Size the pause to the longest journey: a one-minute pause is plenty for a 5 s Bookshelf journey. The pause is always honoured, so the run lasts the full pause even if every thread finishes earlier; with a long pause the run simply ends later.

Menu path: right-click Test Plan, Add → Threads (Users) → Open Model Thread Group. Set the schedule and the seed, then add an HTTP Request sampler under it (Add → Sampler → HTTP Request). The resulting fragment, with the HTTP Request Defaults omitted, is:

The property names come from the 5.6.3 schema classes (OpenModelThreadGroup.schedule, OpenModelThreadGroup.random_seed, ThreadGroup.on_sample_error). Save the plan from the GUI to get the exact form your JMeter version writes.

Source: Open Model Thread Group (Component Reference)

In 5.6.3 the arrival times are offsets from the start of the test. An Open Model Thread Group that starts late, for example after a setUp Thread Group that seeds data for 30 s, or when Run Thread Groups consecutively is ticked on the Test Plan, is already behind its schedule when it begins. The 5.6.3 source starts overdue arrivals immediately, so the first 30 s of the schedule are released as a burst. Until 6.0, avoid placing an Open Model Thread Group after other thread groups in a consecutive run, or start the schedule with a pause(...) that covers the setUp phase.

Planned for 6.0 (per xdocs/changes.xml on the master branch, issue 6352): delays in the Open Model Thread Group and the Precise Throughput Timer are calculated relative to the start of the Thread Group instead of the start of the test. Once released, a late-starting Open Model Thread Group runs its schedule from its own start.

The calcMode index is the position of the mode in the timer’s enumeration as written by the 5.6.3 GUI; older plans may store the mode as its English label instead (for example this thread only), and JMeter loads both. The manual compares the two families: both aim at the target and give similar results; the shared algorithm gives a more accurate overall rate, the non-shared one a more even spread of samples across threads.

Source: Constant Throughput Timer (Component Reference)

The target counts samples from all affected samplers, that is, from every sampler in the timer’s scope. Placed directly under a Thread Group whose journey has five HTTP Requests, a target of 1200 per minute means 1200 HTTP samples per minute in total, about 4 journeys per second. Placed as the child of a single sampler, it counts only that sampler’s samples. Like every timer it runs before each sampler in scope, so the delay is spread over the journey’s steps.

The manual lists ways to vary the target: a counter variable, a __jexl3 or __groovy function that returns a changing value, or changing a JMeter property through the remote BeanShell server. The best-practices page gives a worked BeanShell-server example for a Constant Throughput Timer defined as ${__P(throughput)}. That server only starts when its port is configured, and the best-practices page warns that it has no security (anyone who can reach the port gets unrestricted access to JMeter and the host), so prefer a schedule known in advance (Open Model Thread Group) when you can. The manual also warns that the value should not be changed too often, because it takes a while for a new value to take effect.

Source: Best Practices (Apache JMeter User Manual)

Menu path: select the Bookshelf Thread Group, Add → Timer → Constant Throughput Timer. Set Target throughput to ${__P(samplesPerMinute,1200)} and Calculate Throughput based on to all active threads in current thread group (shared).

A literal target is written by the GUI as a doubleProp named throughput; an expression is stored as a stringProp, as above.

Source: Constant Throughput Timer (Component Reference)

The timer also has two hidden properties, not shown in the GUI or in the component reference but present in the 5.6.3 bean description: exactLimit ("Use approximate throughput when sequence length exceeds (samples)", default 10000) and allowedThroughputSurplus ("Allowed throughput surplus (percents)", default 1.0). Leave them at their defaults.

Source: Precise Throughput Timer (Component Reference)

The three numbers express a business requirement, not just a rate. The manual’s example: 60 iterations per hour is Target throughput 60, Throughput period 3600, Test duration 3600. The pairs 60/3600, 30/1800 and 120/7200 are the same rate; pick the one that matches how the requirement is phrased. Test duration makes the timer generate exactly throughput x duration / period samples in that window instead of "about" that many: a plain Poisson process at 1 per second can produce 50 samples in a 60 s test, which is hard to explain to the business. For a 5-minute run of a 60-per-hour requirement, set Test duration to 300.

Timers apply to every sampler in their scope. Under a Thread Group with a five-request journey, a Precise Throughput Timer would pace every one of the five requests, and its count would be the total of all five. The manual’s recommended location is under the first element in the test loop, for example a dummy sampler at the beginning with the timer as its child. Then the timer releases each thread once per iteration, and the target counts journeys.

Core JMeter’s natural dummy sampler is the Flow Control Action (formerly Test Action): its component reference says it does not generate a sample, and suggests setting the pause to zero and adding a timer as a child for variable delays. A Debug Sampler or a JSR223 Sampler also work but write an extra line per iteration into the results. The jmeter-plugins.org Dummy Sampler (jpgc-dummy) is another option if plugins are allowed.

Because the timer schedules executions at random times, the manual recommends setting the Thread Group’s Ramp-up Period and Startup delay to 0: the timer itself spreads the threads out, and a long ramp-up only leaves too few threads at the start. For the same reason, several thread groups with Precise Throughput Timers do not need extra random start delays. Different timers should have different seeds; with the same rate and the same non-zero seed, several thread groups fire at the same moments.

For low rates, the manual distinguishes two needs: samples at even intervals (use the Constant Throughput Timer) and a randomised schedule that models real users, such as people running reports (use the Precise Throughput Timer).

Batched departures issue requests in pairs or triples while keeping the average rate, for example a page that always fires two API calls together. Set Number of threads in the batch to 2 and Delay between threads in the batch to the gap between them. The Synchronizing Timer, covered in Timers & Think Time, solves some of the same cases.

Memory. The schedule is generated and kept in memory. The manual’s figures: about 200 ms and 8 MB of heap for 1,000,000 samples, 1 to 2 s and 80 MB for 10 million; it suggests keeping the schedule under 1,000,000 samples. For a two-week soak at 5000 per hour, set Test duration to 3600 so the timer generates one hour (5000 samples) at a time. Setting it to the full two weeks gives 2 x 7 x 24 x 5000 = 1,680,000 samples (the manual’s example prints 168,000, having multiplied by 500), which is above the suggested limit and, by the manual’s figures, about 0.3 s and 13 MB, so the one-hour window is the better choice.

Monitoring. Each time the timer generates a schedule it logs an INFO line from ConstantPoissonProcessGenerator to jmeter.log, with the number of timings generated, the generation time and the first event times. Search the log for that class name to confirm the timer is producing what you expect.

ActionProcessor.action 1 is Pause and ActionProcessor.target 0 is Current Thread, the constants in the 5.6.3 source of the Flow Control Action. Again, saving from the GUI gives the authoritative form for your version.

Source: Precise Throughput Timer (Component Reference)

Put the five-request journey (with its think-time timers) under an Open Model Thread Group with this schedule:

Threads: on average 20 alive (4 arrivals per second x 5 s), varying with the random arrivals; about 120 journeys during the ramp plus 2400 during the hold, so about 2520 threads created over the run. Set a response timeout on the HTTP requests (for example 5 s) so that a stall cannot grow the thread count without bound: with five 5 s timeouts and 4 s of think time, the worst journey takes 29 s, which caps the backlog near \(4 \times 29 = 116\) threads.

The Constant Throughput Timer paces samples, and think-time timers add to its delay, so in this variant the throughput timer replaces the think time as the pacing (disable the 1 s think-time timers). Without think time one thread produces \(1 / 0.2 = 5\) requests per second, so 4 threads would be enough in theory. Use 10 threads to leave room for the response time to rise to 0.5 s.

The timer counts all five samplers, so 1200 per minute is 20 requests per second in total, and the shared mode spaces the group’s samples about 60 / 1200 = 0.05 s apart. The trade-off is realism: the requests arrive evenly and there is no user think time.

Keep the think time and pace the journeys: a Flow Control Action with a 0 ms pause as the first element of the journey, with a Precise Throughput Timer as its child (the tree and fragment in the Precise Throughput Timer section).

The 40 threads are twice the 20 journeys in progress predicted by Little’s Law, so the schedule is not starved when responses slow down. 4 journeys per second is 14400 per hour, inside the manual’s "best under 36000 per hour" guidance; pacing the 20 individual requests per second instead would be 72000 per hour.

The three variants can live in one plan as three disabled-or-enabled thread groups, or as three plans. In CLI mode:

The summariser prints a line every 30 s by default; once the load has settled, each variant should report about 20 requests per second. A representative line (numbers depend on the machine and the server):

In the Open Model variant Active stays near 20 while Started keeps growing, because every arrival is a new thread; in the two timer variants Active stays at the thread count. If the reported rate stays below 20, the timer variants are short of threads (or the server is saturated), while the open variant shows growing Active counts and response times instead. That difference is the point of the open model. The HTML dashboard generated by -e -o, described in the dashboard page of this section, plots throughput and active threads over time.

Source: Getting Started (Apache JMeter User Manual)