Thread Groups: Concurrent Users & Ramp-up

A Thread Group is a direct child of the Test Plan. Every sampler and logic controller must be inside one: the manual describes thread groups as the starting point of every test plan. Elements placed directly under the Test Plan, such as a listener or an HTTP Request Defaults, apply to every Thread Group; elements inside a Thread Group apply only to its threads (the scoping rules are on Test Plan Elements, Execution Order & Scoping).

Inside the Thread Group, its children are driven by an implicit Loop Controller: that is the element the Loop Count field configures, and one pass through all the children is one iteration. In the .jmx file this controller is stored as the ThreadGroup.main_controller property of the Thread Group.

The life of one thread follows a fixed sequence. JMeter applies the startup delay (if the thread lifetime is specified), then the thread’s own ramp-up offset, then runs iterations until the loop count is used up, the end time is reached, a sampler error action ends the thread, or the test is stopped:

Source: Elements of a Test Plan (User Manual)

A Thread Group saved by the GUI looks like this in the .jmx file. This is the load profile with literal values; the plan is parameterised with properties later on this page.

LoopController.loops set to -1 is how the GUI stores the Infinite check box; the official templates shipped in bin/templates use the same form.

Source: Thread Group (Component Reference)

The table lists every field of the Thread Group panel in JMeter 5.6.3, the property that stores it in the .jmx file and its behaviour. GUI labels are those of the English resource bundle; descriptions follow the component reference.

Source: Thread Group (Component Reference)

Older .jmx files also contain ThreadGroup.start_time and ThreadGroup.end_time (longProp values with epoch milliseconds). They are leftovers of the absolute Start Time and End Time fields that JMeter 4.0 removed from the scheduler (Bug 61549); 5.6.3 still loads such files and the official templates still carry the properties, but the values are not used. The numeric fields are stored as strings (stringProp), which is what lets them contain a function call such as ${__P(threads,1)}.

Source: Changes History (version 4.0, incompatible changes)

The number of threads follows from the workload, through Little’s Law as explained in Performance Testing Fundamentals:

where \(N\) is the number of threads, \(X\) the target throughput of iterations (or requests) per second, \(R_t\) the response time and \(Z\) the think time per iteration. The ramp-up follows from how fast real users arrive and how much warm-up the system needs, and the duration from how long the steady state must be observed. The books give the same advice (PTwJ ch. 2 sizes the group from expected concurrent users; Pro ch. 5 stresses a gradual ramp-up and a steady period long enough to measure); the formulas above make it quantitative.

The Bookshelf journey has five requests. Measured at light load, each takes 0.2 s on average and is followed by 3 s of think time, so one iteration takes 5 × (0.2 + 3) = 16 s.

Smoke. One thread, one iteration: five requests in about 16 s. It checks that the script, data and environment work before any load is applied. The ramp-up is irrelevant (one thread starts immediately).

Load. 50 threads with a 60 s ramp-up start one thread every 1.2 s (0.83 per second). At full load each thread sends 5 / 16 = 0.3125 requests per second, so the group sends 50 × 0.3125 ≈ 15.6 requests per second, or 3.1 journeys per second. The 660 s duration gives the 60 s ramp-up plus a 600 s hold, during which the group sends about 15.6 × 600 ≈ 9,400 requests. Analyse only the hold: exclude the first 60 s, when fewer than 50 users were active.

Soak. The goal is to keep a moderate, steady population for hours to expose memory leaks, connection pool exhaustion and growing tables. 30 threads, a gentle 300 s ramp-up (one thread every 10 s) and a 4 h hold give a duration of 300 + 14,400 = 14,700 s. The group sends 30 × 0.3125 ≈ 9.4 requests per second, about 135,000 requests over the hold, and each of the 30 threads creates a loan in every iteration, so the setUp group must seed enough books and the tearDown group must remove about 27,000 loans. A soak at a constant arrival rate rather than a constant population is built with the Open Model Thread Group on Open Model & Throughput Control.

Source: Thread Group (Component Reference)

Two consequences of the closed model are worth stating for every profile. If the server slows down, each thread sends fewer requests per second, so the load falls exactly when the system struggles; check the measured throughput against the target after every run. And a Thread Group never sends more than one request at a time per thread, so 50 threads can never produce more than 50 concurrent requests, however short the think time.

Load profiles should differ only in their numbers, not in their .jmx file. Type __P function calls in the Thread Group fields instead of literal values; each reads a JMeter property and falls back to its default. The properties and their precedence are covered on Properties, Variables & Functions.

The resulting fragment, with a Loop Count that is itself a property (-1 gives an infinite loop):

Source: Functions and Variables (User Manual, __P)

With the scheduler selected, the smoke profile ends after its single loop or after 60 s, whichever comes first. Each profile is then one command line. The smoke run uses the defaults:

The load run overrides four properties:

and the soak run reads its values from a file, soak.properties:

Source: Getting Started (CLI mode and -J/-q options)

In CLI mode the summariser prints a line every 30 s by default. The + lines cover the last interval and end with the thread counts, which make the ramp-up visible; the = lines are running totals. Representative output of the load run (numbers depend on the machine and the target):

The Active count climbs by about 25 every 30 s (0.83 threads per second) and stays at 50 during the hold; the rate settles at the 15.6 requests per second predicted above (the final running total averages less, about 14.8 per second, because it includes the ramp-up). A rate that keeps falling while Active stays at 50 means response times are growing: the closed model is throttling itself.

Source: Properties Reference (summariser)

In a distributed run, define these properties with -G instead of -J, so that every load generator receives them. Each generator runs the whole plan, so -Gthreads=50 on four generators means 200 users in total.

A plan can hold several Thread Groups. By default they all start at the same time and run in parallel, which is how a workload with different kinds of users is modelled: for Bookshelf, a Browsers group of 40 threads that only searches and views books, and a Borrowers group of 10 threads that logs in and creates loans. Each group has its own threads, ramp-up and duration; giving each its own startup delay staggers them.

Selecting Run Thread Groups consecutively (i.e. one at a time) on the Test Plan (TestPlan.serialize_threadgroups) runs the groups in tree order, each finishing before the next starts. That turns groups into phases (warm-up, then measured load), at the cost of a total run time that is the sum of all groups. The option and its trade-offs are covered on Test Plan Elements, Execution Order & Scoping.

Source: Test Plan (Component Reference)

Any group can also be run on its own from the GUI: select one or more Thread Groups, right-click, and choose Start, Start no pauses (timers ignored) or Validate. Validation runs the selection with one thread, one iteration, no timers and no startup delay, and can be tuned in user.properties with testplan_validation.nb_threads_per_thread_group, testplan_validation.ignore_timers, testplan_validation.number_iterations and testplan_validation.tpc_force_100_pct. Running a selection and Validate were both added in JMeter 3.0.

Source: Thread Group (Component Reference)

A setUp Thread Group (Add → Threads (Users) → setUp Thread Group) is a Thread Group with exactly the same fields that runs before the regular Thread Groups; a tearDown Thread Group runs after them. Use them for preparation and clean-up that must not be measured as part of the load:

The engine starts all setUp groups, waits until every setUp thread has ended, then starts the regular groups, waits for all of them to end, and then starts the tearDown groups. With Run Thread Groups consecutively selected, the groups inside each of the three phases also run one at a time.

When the tearDown groups run is the subtle part. By default a tearDown group does not run if the test is gracefully shut down (Shutdown in the GUI, the shutdown port or bin/shutdown.sh in CLI mode). Selecting Run tearDown Thread Groups after shutdown of main threads on the Test Plan (TestPlan.tearDown_on_shutdown) makes it run in that case. If the test is stopped (Stop, Stop Test Now, bin/stoptest.sh), tearDown does not run even with the option selected. A test that ends normally always runs its tearDown groups.

Source: tearDown Thread Group (Component Reference)

A complete minimal plan with the three kinds of group follows. The samplers are left out (each hashTree would hold the HTTP Requests); everything else is as saved by JMeter 5.6.3.

The setUp group uses Stop Test: if the seed data cannot be created there is no point in starting the load. The element names SetupThreadGroup and PostThreadGroup are the aliases that JMeter’s saveservice.properties maps to the setUp and tearDown Thread Group classes.

Source: setUp Thread Group (Component Reference)

The official documentation gives no number, and none would be right for long: the answer depends on the hardware, the plan and the server. Best-practices names the factors: the generator’s hardware, the test plan design, and the speed of the server, since a faster server returns responses sooner and so makes JMeter do more work. It warns that a wrongly sized number of threads leads to coordinated omission: when the generator cannot keep up, requests are sent late, the delay is not recorded, and response times look better than they are.

Source: Best Practices, Limit the Number of Threads

What a thread costs:

A practical way to find the limit of one machine:

Source: Getting Started (JVM settings and CLI mode)

When one machine is not enough, run several generators, either in JMeter’s distributed mode or as independent CLI instances whose result files are merged afterwards; both are described in the distributed testing page of this section. Delay Thread creation until needed helps only when many threads are short-lived; it does not raise the number of threads that can be active at once.

Source: Changes History