Checkpoint Lab — Plugins, Custom Components, JMeter APIs, and Extension Strategy

1. Exact assumptions and ceilings

2. Predictions before modification

P1: core-only JMeter startup/smoke works before and after the custom extension because the base installation is not modified.

P2: the extension-dependent JMX run without search_paths cannot load devops.academy.p32.SafeIdSampler; this failure proves the JMX has a real external/custom dependency.

P3: after building/locking the JAR and activating its exact extension path, the plan produces20 JTL samples and10 target requests.

P4: removing the extension path restores core-only operation without deleting/changing shared JMeter JARs.

3. Freeze the pre-change inventory

& "$env:JMETER_HOME\bin\jmeter.bat" -v
java -version

python .\tools\inventory_extensions.py `
  --jmeter-home $env:JMETER_HOME `
  --project-extensions .\extensions `
  --out .\results\inventory-before.json

Review every non-Apache JAR already present. If the base JMeter home is already polluted/unknown, use a clean JMeter5.6.3 distribution before continuing.

4. Compile and unit-test the extension

Use the exact source/commands from Lesson2. Require:

• javac --release17 core/test PASS;
• adapter compiles against ApacheJMeter_core.jar + ApacheJMeter_java.jar from this JMeter5.6.3 home;
• versioned JAR p32-safeid-sampler-1.0.0.jar created in project extensions/.

5. Create and verify the compatibility lock

Run lock_extension.py then check_compatibility.py. Require exact JMeter5.6.3, Java17 and JAR SHA match. Retain compatibility JSON beside the test results.

6. Build the JMX dependency map

Save extension-demo.jmx using the Lesson2 tree and run map_jmx_dependencies.py. Require:

external_or_custom_classes:
  - devops.academy.p32.SafeIdSampler

locked_dependencies:
  - id: p32-safeid-sampler
    version: 1.0.0
    class: devops.academy.p32.SafeIdSampler

unresolved_classes: []
status: PASS

The actual JSON contains the generated JAR hash from the lock.

7. Target authorization and preflight

Start extension_target.py on 127.0.0.1:8032 with max10 and verify /health. Do not allow a target property outside loopback in this checkpoint. This is inherited directly from Chapter31's safe-load boundary.

8. Negative compatibility proof

Run the extension-dependent JMX once without the project search_paths. Preserve the failed JTL/jmeter.log. The expected problem is custom-class availability, not target behavior. The fixture should still show zero/near-zero HTTP target requests because the tree stops on the extension sampler error.

Do not “repair” this negative run by copying the JAR into shared lib/ext; the next step activates the exact locked project path.

9. Authorized compatibility run

$ExtPath = (Resolve-Path .\extensions).Path

& "$env:JMETER_HOME\bin\jmeter.bat" `
  "-Jsearch_paths=$ExtPath" `
  -n `
  -t .\plans\extension-demo.jmx `
  -q .\config\extension.properties `
  -l .\results\positive\results.jtl `
  -j .\results\positive\jmeter.log

Expected independent observations:

• 20 JTL data samples: 10 SafeIdSampler +10 LocalTarget;
• target /stats: requests10/successes10/rejections0;
• no ClassNotFound/NoSuchMethodError in jmeter.log;
• generator remains unsaturated; otherwise extension-overhead conclusions are invalid.

10. Evidence packet

11. Upgrade procedure

For a future 1.0.1 candidate:

1. create a separate source/build directory and versioned JAR;
2. review source/dependencies/API/deprecation warnings and maintainer notes if third-party;
3. run pure unit tests;
4. generate a candidate lock with new hash—do not overwrite the approved lock yet;
5. verify JMeter5.6.3/Java17 compatibility in a clean/local environment;
6. run core-only smoke, negative dependency check if useful, then the same 2×5 target-bounded plan;
7. compare configured/achieved results and generator state;
8. promote the candidate lock/JAR together only after PASS.

Never leave 1.0.0 and1.0.1 JARs containing the same class in the same active extension path.

12. Rollback procedure

Keep the prior approved lock/JAR in a separate inactive versioned directory. To roll back: stop JMeter/engines, point search_paths back to the prior directory, verify hashes/JMeter/Java on every engine/image, run core-only smoke and the bounded compatibility plan, then preserve the rollback report. Do not hot-swap JARs inside a running JMeter process.

13. Distributed/CI/container extension rule

If this plan later runs remotely, every engine must pass the same JMeter/Java/extension lock; the current remote manual already requires identical JMeter versions and recommends the same Java. In CI/container environments emit the inventory/compatibility report before load and pin the image/artifact containing the JAR. A controller-only PASS does not prove worker compatibility.

14. Cleanup

1. Stop the localhost fixture and confirm port8032 closes.
2. Keep evidence/lock/source until review.
3. Deactivate the custom extension by omitting/removing the project search_paths; do not change shared JMeter home.
4. Delete disposable build/ products only after the locked JAR/hash evidence is retained.
5. No production/shared target, credential, RMI engine, plugin repository or system-wide Java/JMeter configuration was modified.

15. Production operating-model addition and Chapter33 bridge

Chapter32 adds an extension governance contract: core/external/custom inventory, exact JMeter/Java/API compatibility, JAR/source provenance and hashes, JMX dependency mapping, isolated classpath/dependency placement, unit/concurrency tests, generator-cost validation, consistent remote/CI/container inventories, staged upgrades and tested rollback are required before extension-dependent performance results are trusted.

Chapter33 moves to Troubleshooting Out-of-Memory, Socket, SSL, DNS, and Distributed Failures. The classpath and generator-state discipline learned here becomes part of that broader troubleshooting sequence: not every JVM/network/distributed failure is the SUT, and extension drift must be ruled out before deeper runtime tuning.

Knowledge check

Official references and version notes

• Apache JMeter downloads — current stable JMeter 5.6.3 and Java 8+ requirement.
• JMeter current changes — Java 17+ recommendation for the 5.6.x line.
• JMeter Getting Started / classpath — lib/ext, lib, search_paths, user.classpath and classpath behavior.
• JMeter Properties Reference — current classpath properties and result fields.
• AbstractJavaSamplerClient Javadocs — recommended adapter base class and setup/run/teardown lifecycle.
• JavaSamplerClient Javadocs — per-thread instance behavior and lifecycle.
• AbstractFunction Javadocs — function lifecycle/thread-safety notes.
• JMeter Best Practices — JSR223/Groovy and compiled-script caching guidance.
• JMeter Remote Testing — identical JMeter/Java versions across nodes and distributed runtime behavior.
• JMeter Plugins Manager — optional third-party plugin-management tooling maintained outside Apache JMeter.