Plugins, Custom Components, JMeter APIs, and Extension Strategy: Core Concepts and Mental Model

1. The practical problem: “install this JAR” is not a design

A team receives a JMX that references a custom sampler. It works on one laptop, fails in CI with ClassNotFoundException, and produces different behavior on one remote engine. Another engineer “fixes” the issue by copying several unpinned JARs into lib/ext. Now the plan's behavior depends on undocumented classpath order. This is a software supply-chain problem inside a load generator.

2. Mental model: extension code joins the execution path

flowchart TD
J[Apache JMeter core 5.6.3] --> C[Classpath/plugin discovery]
P[Verified third-party plugin or custom JAR] --> C
D[Utility/dependency JARs] --> C
C --> L[Component lifecycle]
L --> S[Sampler / function / listener behavior]
X[JMX class references + parameters] --> S
S --> T[Protocol/target or local generator work]
S --> R[JTL + jmeter.log + telemetry]
V[Compatibility/provenance lock] --> C
V --> X

JMeter core provides the engine and public extension APIs. Component/plugin JARs are discovered from the appropriate extension path; utility dependencies come from the dependency path. JMX stores class references/parameters. At execution, lifecycle methods run inside JMeter threads and may touch variables, properties, files, network, credentials or results. The lock records the exact code/version/hash needed to make that JMX reproducible.

3. Core, plugin, custom JAR and dependency

4. Current classpath rules

JMeter automatically discovers component/plugin JARs in JMETER_HOME/lib/ext. Utility/dependency JARs belong in JMETER_HOME/lib. Current properties also support search_paths for additional component/plugin classes and user.classpath/plugin_dependency_paths for dependencies. Normal JMeter startup uses java -jar, so the shell CLASSPATH variable is not the extension mechanism.

The course uses a project-local extensions/ directory through search_paths so rollback is “stop passing the path,” not “hunt for JARs copied into a shared installation.”

5. Java sampler lifecycle

The official Javadocs encourage subclassing AbstractJavaSamplerClient. JMeter creates a JavaSamplerClient instance for each virtual user/thread (and may create extra internal instances). setupTest() initializes that instance, runTest() executes each iteration, and teardownTest() cleans up. Per-instance fields are therefore naturally per-thread for that sampler instance; static mutable fields are still process-wide.

6. Functions have a different concurrency boundary

A JMeter Function occurrence is prepared once and can be executed by multiple threads. Current Javadocs explicitly warn that function execution must synchronize when it touches non-thread-safe objects. If per-thread function state is needed, use thread-local/JMeter-variable state deliberately. Do not copy Java-sampler lifecycle assumptions into Function code.

7. Extension state inventory

8. Read-only inspection first

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

Get-ChildItem "$env:JMETER_HOME\lib\ext\*.jar" |
  Sort-Object Name |
  Select-Object Name,Length

Get-ChildItem "$env:JMETER_HOME\lib\*.jar" |
  Sort-Object Name |
  Select-Object Name,Length

Get-FileHash "$env:JMETER_HOME\lib\ext\*.jar" -Algorithm SHA256
Get-Content .\locks\extensions.lock.json -ErrorAction SilentlyContinue

Read jmeter.log before adding anything: startup/class-loading warnings are part of the baseline. In a distributed/CI/container environment inventory every engine/image, not just the controller.

9. Plugins Manager is optional third-party tooling

The current JMeter-Plugins.org Plugins Manager can install/update/uninstall plugins and can be automated. It is not Apache JMeter core. Its current documentation also describes anonymous usage statistics sent by default and a property to disable them. This course does not install it because the custom lab needs no third-party plugin. If your team adopts it, treat its own JAR/repository metadata and every selected plugin as supply-chain inputs: exact version, source, SHA-256, license/review and rollback.

10. DevOps connection

An extension turns a JMX from “configuration only” into a software dependency graph. The same practices used for application dependencies—version locks, hashes, source provenance, tests, compatibility matrices, staged upgrades and rollback—belong in performance-test operations.

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.