What must a compiled custom JMeter function declare for JMeter to discover it?

Writing a JMeter function is the smallest possible plugin: no GUI class, no test element, one class and a jar. It is also the extension point where discovery, rather than the code, is what usually goes wrong. Everything below is as of Apache JMeter 6.0.0. ## The interface `org.apache.jmeter.functions.Function` declares four methods, and `AbstractFunction` implements the plumbing around three of them: - **`getReferenceKey()`** - the function's name. The interface's own javadoc states the convention: prepend `__`, as in `__regexFunction`. This string is the key JMeter registers the class under, so it is what a plan writes. - **`setParameters(Collection<CompoundVariable>)`** - called once with the parsed arguments, and called *even when no parameters were supplied*. This is where you validate arity. `AbstractFunction` gives you `checkParameterCount`, which throws `InvalidVariableException` naming the reference key and the expected count. - **`execute(SampleResult previousResult, Sampler currentSampler)`** - produce the replacement string. The javadoc is blunt about the constraint: this method must be thread-safe, because multiple threads will be using the same object. JMeter guarantees that `setParameters` happens-before `execute`, since parameters are set on the main thread and worker threads start afterwards; if your function touches something that is not thread-safe, such as a file, you must synchronise it yourself. - **`getArgumentDesc()`** - a list of short descriptions, one per argument, used by the Function Helper dialog. The javadoc calls this list "not optional": if you have no help to write, return a list of the right length containing blank strings. ```java @AutoService(Function.class) public class Nonce extends AbstractFunction { private static final String KEY = "__nonce"; private static final List<String> DESC = List.of("Length in characters"); private static final String ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789"; private CompoundVariable lengthParam; @Override public String getReferenceKey() { return KEY; } @Override public List<String> getArgumentDesc() { return DESC; } @Override public void setParameters(Collection<CompoundVariable> params) throws InvalidVariableException { checkParameterCount(params, 1); lengthParam = params.iterator().next(); } @Override public String execute(SampleResult previousResult, Sampler currentSampler) throws InvalidVariableException { int length = Integer.parseInt(lengthParam.execute().trim()); ThreadLocalRandom rnd = ThreadLocalRandom.current(); StringBuilder out = new StringBuilder(length); for (int i = 0; i < length; i++) { out.append(ALPHABET.charAt(rnd.nextInt(ALPHABET.length()))); } return out.toString(); } } ``` ## Two ways to be found, and one of them has rules JMeter looks for functions twice over. It loads every implementation registered through Java's `ServiceLoader`, then it scans the jars on its component search path - `lib/ext` plus anything `search_paths` adds - and adds whatever the scan turns up that the service lookup did not already provide. The service route is the one to use. `Function` carries the `@JMeterService` annotation precisely to mark it as service-loadable, and JMeter's own functions declare themselves with `@AutoService(Function.class)`, which generates the `META-INF/services/org.apache.jmeter.functions.Function` file at build time. A jar that registers everything this way can also carry the manifest attribute `JMeter-Skip-Class-Scanning: true`, telling JMeter there is nothing in it worth scanning - useful once an installation carries many plugins, because the scan has to load classes to inspect them. The scan route carries a trap, though not the one the file advertises. `bin/jmeter.properties` really does ship two properties set rather than commented out: - `classfinder.functions.contain=.functions.` - `classfinder.functions.notContain=.gui.` JMeter really does echo them at startup - "Note: Function class names must contain the string: '.functions.'". At 6.0.0 nothing acts on them. `CompoundVariable`'s static initialiser reads the two values only to write those log lines, then calls the combined service-plus-scan lookup, which runs the `ServiceLoader` and then the class finder through the overload that hard-codes both name filters to `null` - so the filter's two `contains` tests are skipped outright. `com.example.jmeter.util.Nonce` is therefore found and registered, provided its jar sits in `lib/ext` or a `search_paths` directory, exposes a public no-arg constructor, and does not carry `JMeter-Skip-Class-Scanning: true`. The properties, their comment, and the manual page describing them are stale. What bounds the scan is the directory, not the package name - and a `META-INF/services` entry lifts even that, since the service lookup finds the class anywhere on the loader's classpath, `lib` included. ## Packaging and deployment 1. Build a jar containing the class and its `META-INF/services` entry. 2. Put the jar in `JMETER_HOME/lib/ext`, or in a directory named by `search_paths`. Its own dependencies go in `lib`, or a directory named by `plugin_dependency_paths`. 3. Restart JMeter. Discovery runs at startup only. 4. Confirm it registered: the function should appear in the Function Helper dialog's list, which is built from the same registry. ## Failure modes worth recognising - **The name renders literally.** An unresolved reference is not blanked out - JMeter renders the literal text of the reference, so a field containing the raw `${__nonce(8)}` text in a request is the signature of a function that never registered. - **The wrong argument count aborts the whole plan.** `checkParameterCount` throws `InvalidVariableException`, and a bad function call is caught while the test tree is compiled: the engine logs `Error occurred compiling the tree:` and returns, so no thread ever starts and there is no results file. A malformed function call is loud, not silent. - **A thread-unsafe function corrupts under load and looks fine at one thread.** Test it with the thread count you intend to run, not with one.