Logic Controllers & Transactions

The component reference opens the family with one sentence: logic controllers determine the order in which samplers are processed. A controller is a node of the test plan tree that has children (samplers, other controllers, and the config elements, pre-processors, timers, post-processors, assertions and listeners scoped to them). When a thread reaches the controller, the controller decides which of its children to hand to the thread next, and when it is done.

Three properties follow from that model and explain most of the behaviour on this page:

All logic controllers are added from the same menu: right-click the Thread Group (or another controller) and choose Add → Logic Controller → <name>. Test Fragment is the exception: it is added under the Test Plan with Add → Test Fragment → Test Fragment.

Source: Logic Controllers (Component Reference)

The JMX fragments on this page are shortened to the properties that matter: JMeter writes more properties and the exact set depends on the version. Build controllers through the GUI and read the XML to review them; do not hand-write whole plans. Each controller in a .jmx file is followed by a <hashTree> that holds its children.

The Simple Controller has no behaviour beyond storage: JMeter processes its children exactly as if they were placed directly in the parent. It exists for two reasons: to organise a long plan into readable blocks ("Catalogue", "Loans") and to create a scope for timers, assertions, extractors and managers that should apply to a subset of samplers only.

The Bookshelf plan groups the two catalogue requests and gives them their own Response Assertion, which therefore does not apply to the loan requests:

The property name Asserion.test_strings (sic) is the spelling JMeter really uses in .jmx files.

Source: Simple Controller (Component Reference)

The Loop Controller runs its children a fixed number of times each time the thread passes through it, in addition to the Thread Group’s own loop count. It is the natural way to model "a user searches five times per visit" without repeating samplers.

Loop index. Since JMeter 4.0 the Loop Controller exposes the current iteration as a variable named __jm__<Name>__idx, starting at 0. A Loop Controller named SearchLoop exposes ${__jm__SearchLoop__idx}. The same variable exists for the ForEach Controller (4.0) and the While Controller (5.0). Give the controller a name without spaces so the variable is easy to reference.

Functions in the Loop Count are evaluated more than once. The component reference warns that a function such as __Random in the Loop Count field may be evaluated several times, once for each child sampler, which gives a different count per child. Compute a random count once, for example with a User Parameters pre-processor or a JSR223 element that stores it in a variable, and reference the variable.

The embedded Loop Controller of the Thread Group is special. Unless it is set to forever, it stops the thread after the given number of iterations; an ordinary Loop Controller simply returns control to its parent.

Bookshelf example: each visit runs three searches, each with a different term from search-terms.csv, and logs the index:

LoopController.continue_forever is true here even though the loop is finite. For a Loop Controller that is not embedded in a Thread Group, this is the value the GUI writes: it makes the controller restart its count on the next pass instead of finishing for good. The Forever checkbox is stored as a Loop Count of -1. Putting a function in the sampler name, as above, makes the three searches appear as separate rows in reports; use it for debugging only, because many distinct labels make reports harder to read.

With 50 threads, a Thread Group loop count of 10 and this Loop Controller, the plan sends 50 × 10 × 3 = 1,500 search requests.

Source: Loop Controller (Component Reference)

The Once Only Controller runs its children only once per thread and skips them on later iterations. More precisely, it runs during the first iteration of any looping parent: under a Thread Group that is once per virtual user for the whole test; under a Loop Controller set to 5 it is once every 5 passes, because the Loop Controller restarts its iteration count each time it is entered. The component reference suggests it for logins: each thread usually needs to log in only once to establish a session.

The JMeter change log carries a long-standing known problem: the Once Only Controller behaves correctly under a Thread Group or a Loop Controller, but its behaviour under other parents is "not consistent (or clearly specified)". Keep it as a direct child of the Thread Group or of a Loop Controller.

Bookshelf example, the login of the journey:

The token is extracted from the login response with a JSON Extractor and reused by later requests; the extraction itself belongs to the correlation page later in this guide. A JWT expires: in a long soak test a token obtained once per user can expire mid-test. Either make the server’s token lifetime longer than the test, or re-login on a schedule with an If Controller (next section) driven by the elapsed time.

Interaction with "Same user on each iteration". When the Thread Group’s "Same user on each iteration" option is unchecked and the Cookie Manager’s "Use Thread Group configuration to control cookie clearing" box is checked, the Cookie Manager clears cookies between iterations, so a session kept in cookies is lost after the first iteration while the Once Only Controller does not log in again. For a token sent in a header (as in Bookshelf) the variable survives, so the problem does not arise; for cookie sessions keep the option checked (the default).

Source: Once Only Controller (Component Reference) and JMeter changes (Known problems)

The If Controller runs its children only when its condition evaluates to true. By default the condition is checked once, when the thread enters the controller; optionally it is checked before every child.

Use the expression mode. With the option unticked the If Controller evaluates JavaScript, which the documentation describes as having a performance penalty that "can be very big". It also depends on the JavaScript engine: Nashorn was removed from Java 15, and JMeter then falls back to its bundled Rhino engine (the javascript.use_rhino property forces Rhino). JMeter 4.0 changed the default for newly added If Controllers to the expression mode and shows a warning when the JavaScript mode is chosen.

Typical expressions from the documentation, adapted to Bookshelf:

Do not put ${...} inside a __groovy condition. The documentation warns that variable references inside the Groovy script change the script text on every call, so the compiled script cannot be cached. Read variables with vars.get("name") instead, as in the table above.

Bookshelf example: create a loan only when the viewed book has copies available.

The && and > are only the XML escaping of && and >; in the GUI the condition is typed as plain Groovy. A skipped If Controller under a Transaction Controller produces an empty transaction; the HTML report ignores empty Transaction Controller samples since JMeter 3.1.

Source: If Controller (Component Reference) and __groovy (Functions)

The While Controller repeats its children until its condition becomes the string false. Like the Loop Controller it exposes its index as ${__jm__<Name>__idx} (since 5.0), starting at 0.

The condition is evaluated twice per pass: once before the children run and once after. Functions with side effects (__counter, for instance) therefore advance twice per loop and should not be used in it.

Always bound the loop. A While Controller whose condition never becomes false keeps the thread in it forever, and the generator then hammers one endpoint with no think time if the loop has no timer. Combine the business condition with a maximum count based on the index.

Bookshelf example: the loan is created, then polled until its status is ACTIVE, at most five times. A JSON Extractor on POST /api/loans and on GET /api/loans/{id} writes loanStatus; a 500 ms Constant Timer under the controller spaces the polls.

Source: While Controller (Component Reference)

The ForEach Controller loops over a set of numbered variables such as bookId_1, bookId_2, bookId_3, and on each pass copies the current value into an output variable. It is designed to work with extractors whose Match No. is -1: the Regular Expression Extractor, the JSON Extractor and others then store every match as name_1 to name_N. It exposes its index as ${__jm__<Name>__idx} (since 4.0).

If prefix_1 is not defined (the extractor found nothing), the ForEach Controller runs nothing.

Bookshelf example: the search response returns a list of books; a JSON Extractor with the path $.items[*].id, variable name bookId and Match No. -1 produces bookId_1 to bookId_N. The user then opens the first three results:

With a start index of 0 and an end index of 3 the loop uses bookId_1, bookId_2 and bookId_3. If the search returns 20 results and the end index is left empty, every user opens 20 books per search: the number of requests then depends on the data, which makes the workload hard to reason about. Bound it.

Source: ForEach Controller (Component Reference) and JSON Extractor (Component Reference)

The Switch Controller runs exactly one of its children on each pass, the one selected by its switch value. It is the most precise tool for a transaction mix because the choice is explicit and mutually exclusive.

The selection rules are:

The value can be a variable or a function. In the 5.6.3 source code the selection is computed once each time the controller is entered, so a random function in the Switch Value draws once per pass, not once per child. The weighted selector used in the Bookshelf model below relies on this.

Source: Switch Controller (Component Reference)

The Interleave Controller runs one child per pass and moves to the next child on the following pass, wrapping around at the end. Under a Thread Group that is one child per iteration, in turn.

In the JMX file the first checkbox is stored as InterleaveControl.style (0 when ticked, 1, the default, when not) and the second as InterleaveControl.accrossThreads (sic).

Bookshelf example: alternate the search style per iteration, by title one time and by author the next.

Source: Interleave Controller (Component Reference)

The Random Controller is an Interleave Controller that picks a child at random instead of in turn. Each child has the same probability: with three children each is chosen about a third of the time. It has the same ignore sub-controller blocks field (stored as InterleaveControl.style) and no "across threads" option.

The documentation adds a caution that applies to every combination on this page: interactions between controllers, and between the Random Controller and others in particular, can give complex behaviour, so experiment before assuming a result. The Thread Group’s Validate action and a short smoke run with a View Results Tree are the way to check.

Unequal weights need either duplicated children (six references to one journey, three to another, one to the last, typically as Module Controllers so the journeys exist once) or a Switch Controller with a weighted selector, both shown below.

Source: Random Controller (Component Reference)

The Random Order Controller runs every child exactly once per pass, like a Simple Controller, but in a random order. It models steps a user performs in no fixed order, for example opening a book page and checking a current loan.

Source: Random Order Controller (Component Reference)

Despite its name, the Throughput Controller does not control throughput (the documentation itself calls it "badly named"; requests per second are set with the timers and thread groups covered in Open Model & Throughput Control). It controls how often its children run, in one of two modes.

As with the Once Only Controller, the counters restart when a parent Loop Controller restarts.

Percent mode is deterministic, not random. In the 5.6.3 source code a Throughput Controller in percent mode runs on an iteration when (100 × executions so far + 50) / iterations so far is below the configured percentage. The controller therefore spreads its executions evenly; it does not toss a coin. That makes long-run proportions exact, but it also means that sibling Throughput Controllers decide independently of each other. Three siblings at 60 %, 30 % and 10 % with Per User unticked give, over the first ten iterations of the group:

Over 100 iterations the totals are exactly 60, 30 and 10, but 20 iterations run no journey at all and 10 run all three. The proportions of requests are right; the shape of each session is not. When each iteration must be exactly one journey, put the Throughput Controllers under a Random or Interleave parent, as the documentation hints, or use a Switch Controller with a weighted selector.

Validation. The Thread Group’s Validate action runs one thread for one iteration; the property testplan_validation.tpc_force_100_pct=true (default false) forces percent-mode Throughput Controllers to 100 % in that run, so every branch is exercised.

Source: Throughput Controller (Component Reference) and Properties Reference (testplan_validation)

The Runtime Controller repeats its children until a time budget is exceeded. It is useful to model "a user browses for about a minute" or to give one phase of a setUp Thread Group a fixed duration.

The budget is checked between children, so a slow last request can overrun it.

With a 2 s think time and 250 ms of response time per request, one pass of a two-request browse block takes about 4.5 s, so a 60 s budget gives about 13 passes, or 26 requests, per user per visit.

Source: Runtime Controller (Component Reference)

Individual HTTP samples answer "how fast is GET /api/books/{id}?". Stakeholders ask "how long does it take to borrow a book?", which is several requests. The Transaction Controller answers that question: it runs its children like a Simple Controller and generates an additional sample that measures the overall time of the nested samplers. That sample appears in listeners, JTL files and the HTML report under the controller’s name, next to (or instead of) the individual samples.

These three elements are about reuse and are described in detail in Test Plan Elements, Execution Order & Scoping. In short:

For the transaction mix, Module Controllers let each journey exist once (in a Test Fragment) while being referenced from a Random Controller several times, which is how unequal weights are obtained without a script.

Source: Module Controller and Include Controller (Component Reference)

The Critical Section Controller lets only one thread at a time run its children: it takes a named lock before running them and releases it afterwards. It was added in JMeter 2.12.

The lock exists only inside one JVM. In distributed testing each load generator has its own lock, so a test must not rely on all threads of all generators blocking each other.

It serialises load, so it caps throughput. If the protected block takes 100 ms, no more than 10 passes per second can go through it whatever the number of threads; 50 threads queue behind each other. Use it to protect test-side resources, never to model server behaviour.

Bookshelf example: a JSR223 PostProcessor appends every created loan id to a shared file, which the tearDown Thread Group later uses to cancel the loans. Appending from many threads at once can interleave lines, so the append runs in a critical section:

The Flow Control Action sampler is used here only as a carrier: it is the one sampler that does not generate a sample result, so it does not add rows to the report.

Source: Critical Section Controller (Component Reference) and Flow Control Action (Component Reference)

The Recording Controller is a placeholder that marks where the HTTP(S) Test Script Recorder stores the samplers it records. During a test run it behaves exactly like a Simple Controller. The Recording template (File → Templates → Recording) creates one under the Thread Group. After recording, rename it or replace it with Transaction Controllers per page; the recorder can also group requests into new Transaction Controllers itself. The recording workflow is covered on the recording and cURL import page later in this guide.

Source: Recording Controller (Component Reference)

A workload model states what users do and in which proportions. The model for Bookshelf, derived the way the performance testing fundamentals page describes (access logs and business expectations), is:

Every virtual user logs in once at the start (Once Only Controller), then repeats: pick one journey, run it as a Transaction Controller, think, repeat.

Three ways to implement the 60/30/10 split are common. They differ in whether each iteration runs exactly one journey.

The Bookshelf plan uses the Switch Controller. Its children are the three Transaction Controllers, and the switch value returns their names. The selection is drawn once per pass, and the names match case-sensitively:

Two details in the selector are deliberate. The percentages come from properties through __P, with the commas inside the nested function escaped as \, because they sit inside the __groovy argument, so a run can change the mix with -JsearchPct=70 -JborrowPct=20. And the ${__P(...)} references are resolved before Groovy sees the script; they are constant for the whole run, so the script text does not change and its compiled form can still be cached. Variables that change per iteration must be read with vars.get instead, as explained in the If Controller section.

The same selector can be checked from the command line before a long run with a short smoke test and the summariser output:

The numbers above are illustrative. The summary lines count only real requests, because the summariser ignores transaction samples by default. Count the labels of the transaction samples in the JTL file (for example with the Aggregate Report or the HTML dashboard) to check that the shares come out near 60/30/10 over a few hundred iterations.

Source: Switch Controller (Component Reference), __groovy and __P (Functions)

Logic controllers run in the virtual user’s thread between samples, so their cost is added to every iteration of every thread. Most of them are negligible; a few are not.

Source: If Controller (Component Reference) and Best Practices

No other change to the logic controllers is listed in the planned 6.0 change log at the time of writing.

Source: JMeter changes, JMeter changes history and changes.xml on master (planned 6.0)