Controllers: Simple, Loop, Transaction, If, While, Switch, and Throughput: Diagnostics, Failure Modes, and Production Practices

1. Preserve first-failure evidence

2. Diagnostic sequence

flowchart TD
E[Preserve JMX + variables/data + JTL + jmeter.log + target evidence] --> V[Confirm JMeter/Java/tool versions]
V --> W[Recompute Thread Group × controller opportunities]
W --> C[Inspect If/While/Switch/Throughput state]
C --> S[Inspect Timer/Assertion/Processor scope]
S --> J[Compare JTL child/transaction labels]
J --> T[Compare independent target request counts]
T --> G[Inspect generator CPU/GC/listener cost]
G --> U[Inspect SUT telemetry/latency/errors]
U --> X[Remote/CI/container state if relevant]
X --> F[Least destructive controller correction]
F --> R[Small bounded rerun]

3. Failure mode: While condition never becomes false

Broken configuration: POLL_MORE=true is initialized but the extractor is attached to the wrong sampler, so Poll responses never update it. The While loop keeps generating Poll requests.

Bounded reproduction only: Thread Group duration 4 seconds, one thread, and a 200 ms Constant Timer under Poll. Stop if request count exceeds the predicted safety ceiling.

Evidence: repeated Poll labels, target /poll count rising, POLL_MORE unchanged. Repair the extractor scope/default and keep a hard external duration guard.

4. Failure mode: non-idempotent function in While condition

A condition such as a counter function appears to mean “loop three times,” but While evaluates its condition before and after child sampling. The counter can advance twice per cycle and behave unexpectedly.

Use Loop Controller for fixed repetition. Use While for state-driven repetition where a separate state producer sets a stable true/false value.

5. Failure mode: expensive If condition

A large JavaScript expression is evaluated for every user/iteration or every child. Target latency stays stable, but generator CPU rises and achieved RPS falls.

Repair: Interpret Condition as Variable Expression + precomputed boolean/JEXL3/Groovy when appropriate. Measure the same tiny workload before/after; do not increase heap first.

6. Failure mode: Throughput Controller used as “100 RPS”

An engineer sets Throughput=100 in percent mode and expects 100 requests/s. That simply means execute the branch on 100% of controller opportunities. Request rate still depends on threads, response time, timers, loops, and arrival model.

Repair the requirement mapping: Throughput Controller for population/branch frequency; Chapter 7 timer/workload mechanisms for request/arrival rate.

7. Failure mode: transaction and children double-counted

Additional transaction mode produces five HTTP child rows plus one Transaction row. A report sums all six as “requests.” Throughput/volume is overstated by 20% in that example.

Repair the analytics: filter transaction labels for protocol-request counts or use independent target counts. Alternatively use parent mode if the reporting pipeline is transaction-centric and accepts losing separate child CSV rows.

8. Failure mode: parent mode hides child CSV detail unexpectedly

A baseline previously saved child labels; someone enables Generate Parent Sample and the CI parser suddenly sees only transaction rows. The target behavior did not change, but result schema did.

Repair by restoring the intended Transaction mode or updating the reporting contract explicitly. Do not call missing child CSV rows a server regression.

9. Failure mode: timer inherited through controller scope

A 500 ms Constant Timer is placed under a Checkout Simple Controller above both standard and express samplers. Both branches inherit it. If only the final Submit action should include think time, the timer scope is too broad.

Walk ancestors for each sampler and list every in-scope Timer before changing latency interpretation.

10. Failure mode: assertion attached to parent transaction

In Transaction parent mode, assertions attached at the Transaction Controller can apply to both children and parent by default. A response-body assertion intended for one HTTP sampler can therefore fail unrelated samples/transaction result.

Repair with narrow sampler scope or place child samplers inside a Simple Controller and scope the assertion to that intended group.

11. Failure mode: deep nesting obscures the business transaction

A tree with Simple → If → Throughput → Loop → Switch → Transaction → Simple around one request forces reviewers to reverse-engineer five control layers. Complexity increases scope mistakes and makes sample-count math harder.

Flatten layers that do not encode business behavior. Keep one controller per real concern: repetition, branch, transaction, or intentional scope boundary.

12. Causal performance separation

13. Troubleshooting shortcuts to reject

• Do not increase thread count to compensate for a branch/loop configuration error.
• Do not add retries or long sleeps to an infinite polling loop.
• Do not increase JVM heap before measuring condition/listener/controller overhead.
• Do not disable assertions/timers globally to make controller counts easier.
• Do not disable TLS/RMI verification or move the experiment to production.
• Do not delete the failed JTL/jmeter.log/target evidence after repair.

Knowledge check

Official references and version notes

• Component Reference — Logic Controllers — Simple, Loop, Throughput, If, While, Switch, and Transaction Controller semantics.
• Elements of a Test Plan — scope and execution-order rules for samplers, controllers, timers, processors, and assertions.
• Functions and Variables — current JEXL3/Groovy/function/variable behavior used in conditions.
• Best Practices — GUI authoring versus CLI load execution and generator-validity guidance.
• Apache JMeter downloads — current production release and Java requirement.