Functions, Custom Properties, Reusable Fragments, and Modular Plans: Diagnostics, Failure Modes, and Production Practices

1. Preserve first-failure evidence

2. Diagnostic sequence

flowchart TD
E[Preserve JTL / jmeter.log / command manifest / target events] --> V[Confirm JMeter + Java + tool versions]
V --> C[Confirm exact JMX / fragments / properties / CLI + authorized target]
C --> R[Resolve cwd / user.dir / project root / include prefix / filenames]
R --> S[Validate runtime tree scope + unique module names + resolved vars/properties]
S --> P[Inspect per-thread session/data state]
P --> G[Inspect generator JVM / OS / filesystem / network]
G --> T[Inspect SUT telemetry / received event counts]
T --> X[Inspect distributed / CI / container checkout/path state if relevant]
X --> F[Least destructive correction]
F --> M[Small controlled rerun and compare]

3. Intentionally broken example: direct Include run without prefix

main-include.jmx contains:

Include Controller — INC.session.bootstrap.v1
Filename: session-bootstrap.jmx

The fragment actually lives in sibling directory fragments/, not plans/. From an unrelated working directory, deliberately bypass the launcher and omit includecontroller.prefix:

Set-Location "$env:TEMP"

& "$env:JMETER_HOME\bin\jmeter.bat" `
  -n `
  -t "F:\Labs\p20-modular-lab\plans\main-include.jmx" `
  -q "F:\Labs\p20-modular-lab\config\local.properties" `
  -Jrun.id=p20-broken-path `
  -Jvariant=include-broken `
  -l "F:\Labs\p20-modular-lab\results\broken\results.jtl" `
  -j "F:\Labs\p20-modular-lab\results\broken\jmeter.log"

Expected: JMeter cannot resolve the intended external fragment via prefix+Filename and fallback to the JMX launch directory also does not find session-bootstrap.jmx. Preserve the log. The fixture should see no valid session/work sequence for that failed run.

Repair: run through tools/run-local.ps1, which supplies the absolute -Jincludecontroller.prefix=.../fragments/. Keep JMX filename unchanged and rerun the smallest 1-thread profile first.

4. Failure mode: hidden __P default

Broken operational field:

Threads = ${__P(threads)}

If threads is absent, current JMeter returns 1. The run can look successful while generating the wrong load. Repair with an explicit safe default plus resolved-property preflight, or fail the launcher when the required key is missing.

5. Failure mode: function-heavy unreadable fields

Anti-pattern:

${__P(run.id,${__time(YMDHMS)})}-${__threadNum}-${__Random(1,9999)}-${__UUID()}

This hides fallback-to-current-time, thread identity, two kinds of randomness and replay semantics inside one field. Split named values into clear properties/variables/functions, and use deterministic data when replay matters.

6. Failure mode: duplicate fragment/controller names

Module Controller resolves fragments by controller/parent names. Two generic Simple Controller or two identical FRAG.session.bootstrap.v1 paths can make the module reference ambiguous/wrong after reload.

Repair: give each reusable controller a unique hierarchical name and reopen/reselect the Module Controller target. Also give multiple Include Controllers that include the same file distinct controller names, per current JMeter guidance.

7. Failure mode: global mutable property for per-user session

Broken:

${__setProperty(SESSION_ID,${SESSION_ID})}
...
/work?session_id=${__P(SESSION_ID)}

Properties are global to the JMeter process. Thread 2 can overwrite Thread 1's session before Thread 1 sends work. In distributed testing, each engine also has a different “global” property universe.

Repair: keep SESSION_ID in the extractor-created thread-local variable and reference ${SESSION_ID} directly.

8. Failure mode: circular/redundant module structure

An external fragment includes another fragment that eventually points back to the first, or a main plan includes the same setup at two levels. Even where parsing/loading prevents a literal infinite cycle, the design is invalid because runtime ownership and operation counts are no longer obvious.

Maintain an acyclic dependency graph with one owner for each reusable behavior. Flatten redundant wrapper fragments that add no contract.

9. Failure mode: random functions without replay strategy

A failing run used __Random for business data but did not record generated values or a seedable mechanism. The next run cannot reproduce the same input.

Repair: use seeded Random Variable where appropriate, generated/committed deterministic fixtures, or persist the generated values in result/sample variables if exact replay is required. Use random functions only when randomness itself is part of the workload model.

10. Failure mode: “works in GUI” cwd assumptions

GUI launch from the project root can hide path assumptions. A scheduler, CI runner, IDE or shell may start from another directory. Always test a clean-shell invocation from a different cwd using the project launcher before declaring the module portable.

11. Failure mode: putting top-level configuration in included JMX

Cookie Manager or User Defined Variables inside the external included file are not guaranteed to work as expected. Keep shared configuration at the top-level plan and let the fragment accept those already-resolved settings.

12. Causal symptom table

13. Security-sensitive boundaries

Property files, launchers and manifests can accidentally capture credentials/environment variables. Include files can execute arbitrary samplers/processes if sourced from an untrusted repository. Treat JMX/fragments/scripts as executable test code. Keep real secrets outside versioned files/logs, validate module provenance, and use only disposable authorized targets.

14. Troubleshooting shortcuts to reject

• Do not add blanket retries or arbitrary sleeps around include/module errors.
• Do not increase heap or threads to “push through” path/property failures.
• Do not disable listeners wholesale without evidence.
• Do not mutate process-global properties to synchronize virtual users.
• Do not disable TLS/RMI verification.
• Do not switch to a production target when a local module fails.
• Do not grow a recursive module graph to avoid naming a clear boundary.
• Do not delete failed JTL/jmeter.log/manifest evidence.

Knowledge check

Official references and version notes

• JMeter Component Reference — Module Controller — runtime substitution of an already loaded controller/fragment and unique fragment naming.
• JMeter Component Reference — Include Controller — external JMX/Test Fragment use, filename limitations, includecontroller.prefix, and path fallback behavior.
• JMeter Component Reference — Test Fragment — reusable fragment semantics with Module/Include Controllers.
• JMeter Functions — __P — simplified command-line property lookup and default behavior.
• JMeter Functions — __property — general JMeter property lookup and optional variable assignment.
• JMeter Functions — __threadNum — thread-group-local thread numbering and Configuration Element restrictions.
• JMeter Functions — __Random — pseudo-random values and optional variable assignment.
• JMeter Component Reference — Random Variable — seeded/per-thread reproducible random-number option.
• JMeter Getting Started — -q/-J, property files, and JMeter configuration loading.
• JMeter Best Practices — GUI authoring/debugging and non-GUI execution for load.
• Apache JMeter downloads — current stable release and Java requirement.