Extending JMeter

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example.bookshelf</groupId>
  <artifactId>bookshelf-jmeter-ext</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <properties>
    <jmeter.version>5.6.3</jmeter.version>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencies>
    <!-- Already in JMeter's lib/ext: compile against them, never package them -->
    <dependency>
      <groupId>org.apache.jmeter</groupId>
      <artifactId>ApacheJMeter_core</artifactId>
      <version>${jmeter.version}</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.apache.jmeter</groupId>
      <artifactId>ApacheJMeter_java</artifactId>
      <version>${jmeter.version}</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.apache.jmeter</groupId>
      <artifactId>ApacheJMeter_components</artifactId>
      <version>${jmeter.version}</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.4.2</version>
        <configuration>
          <archive>
            <manifestEntries>
              <JMeter-Skip-Class-Scanning>true</JMeter-Skip-Class-Scanning>
            </manifestEntries>
          </archive>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

bookshelf-jmeter-ext/
├── pom.xml
└── src/main/
    ├── java/com/example/bookshelf/jmeter/
    │   ├── BookSearchClient.java                       Java Request client
    │   ├── sampler/BookLookupSampler.java              TestBean sampler
    │   ├── sampler/BookLookupSamplerBeanInfo.java      its GUI description
    │   ├── functions/RandomIsbnFunction.java           ${__randomIsbn(...)}
    │   ├── backend/SlaBreachBackendListenerClient.java Backend Listener client
    │   └── report/SlowSamplesPerSecondGraphConsumer.java dashboard graph
    └── resources/
        ├── com/example/bookshelf/jmeter/sampler/BookLookupSamplerResources.properties
        └── META-INF/services/
            ├── org.apache.jmeter.protocol.java.sampler.JavaSamplerClient
            ├── org.apache.jmeter.functions.Function
            └── org.apache.jmeter.visualizers.backend.BackendListenerClient

mvn -B clean package

[INFO] Building bookshelf-jmeter-ext 1.0.0
[INFO] --- resources:3.4.0:resources (default-resources) @ bookshelf-jmeter-ext ---
[INFO] Copying 4 resources from src/main/resources to target/classes
[INFO] --- compiler:3.15.0:compile (default-compile) @ bookshelf-jmeter-ext ---
[INFO] Compiling 6 source files with javac [debug release 17] to target/classes
[INFO] --- jar:3.4.2:jar (default-jar) @ bookshelf-jmeter-ext ---
[INFO] Building jar: ./target/bookshelf-jmeter-ext-1.0.0.jar
[INFO] BUILD SUCCESS

# src/main/resources/META-INF/services/org.apache.jmeter.protocol.java.sampler.JavaSamplerClient
com.example.bookshelf.jmeter.BookSearchClient

package com.example.bookshelf.jmeter.sampler;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

import org.apache.jmeter.samplers.AbstractSampler;
import org.apache.jmeter.samplers.Entry;
import org.apache.jmeter.samplers.SampleResult;
import org.apache.jmeter.testbeans.TestBean;

/** GET /api/books/{id} as a sampler with its own GUI form. */
public class BookLookupSampler extends AbstractSampler implements TestBean {

    private static final long serialVersionUID = 1L;

    // HttpClient is thread-safe: one instance shared by every thread
    private static final HttpClient CLIENT = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .build();

    // TestBean properties: JMeter copies the element's properties into these fields
    private String baseUrl;
    private String bookId;
    private int timeoutMs;
    private String expectedStatus;

    @Override
    public SampleResult sample(Entry entry) {
        SampleResult result = new SampleResult();
        result.setSampleLabel(getName());
        String url = baseUrl + "/api/books/" + bookId;
        result.setSamplerData("GET " + url);
        HttpRequest request = HttpRequest.newBuilder(URI.create(url))
                .timeout(Duration.ofMillis(timeoutMs))
                .GET()
                .build();
        result.sampleStart();
        try {
            HttpResponse<String> response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
            result.sampleEnd();
            String code = String.valueOf(response.statusCode());
            result.setResponseCode(code);
            result.setResponseData(response.body(), StandardCharsets.UTF_8.name());
            result.setDataType(SampleResult.TEXT);
            result.setSuccessful(code.equals(expectedStatus));
            result.setResponseMessage(result.isSuccessful() ? "OK" : "Expected " + expectedStatus);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            result.sampleEnd();
            result.setSuccessful(false);
            result.setResponseMessage(e.toString());
        } catch (Exception e) {
            result.sampleEnd();
            result.setResponseCode("500");
            result.setResponseMessage(e.toString());
            result.setSuccessful(false);
        }
        return result;
    }

    public String getBaseUrl() { return baseUrl; }
    public void setBaseUrl(String baseUrl) { this.baseUrl = baseUrl; }
    public String getBookId() { return bookId; }
    public void setBookId(String bookId) { this.bookId = bookId; }
    public int getTimeoutMs() { return timeoutMs; }
    public void setTimeoutMs(int timeoutMs) { this.timeoutMs = timeoutMs; }
    public String getExpectedStatus() { return expectedStatus; }
    public void setExpectedStatus(String expectedStatus) { this.expectedStatus = expectedStatus; }
}

package com.example.bookshelf.jmeter.sampler;

import java.beans.PropertyDescriptor;

import org.apache.jmeter.testbeans.BeanInfoSupport;

public class BookLookupSamplerBeanInfo extends BeanInfoSupport {

    public BookLookupSamplerBeanInfo() {
        super(BookLookupSampler.class);

        createPropertyGroup("server", new String[] {"baseUrl", "timeoutMs"});
        createPropertyGroup("request", new String[] {"bookId", "expectedStatus"});

        PropertyDescriptor p = property("baseUrl");
        p.setValue(NOT_UNDEFINED, Boolean.TRUE);
        p.setValue(DEFAULT, "http://${__P(host,localhost)}:${__P(port,8080)}");

        p = property("timeoutMs");
        p.setValue(NOT_UNDEFINED, Boolean.TRUE);
        p.setValue(DEFAULT, 5000);

        p = property("bookId");
        p.setValue(NOT_UNDEFINED, Boolean.TRUE);
        p.setValue(DEFAULT, "${bookId}");

        p = property("expectedStatus");
        p.setValue(NOT_UNDEFINED, Boolean.TRUE);
        p.setValue(DEFAULT, "200");
        p.setValue(NOT_OTHER, Boolean.TRUE);
        p.setValue(NOT_EXPRESSION, Boolean.TRUE);
        p.setValue(TAGS, new String[] {"200", "404"});
    }
}

displayName=Bookshelf Book Lookup
server.displayName=Server
request.displayName=Request
baseUrl.displayName=Base URL
baseUrl.shortDescription=Scheme, host and port of the Bookshelf API, without a trailing slash
timeoutMs.displayName=Timeout (ms)
timeoutMs.shortDescription=Request timeout in milliseconds
bookId.displayName=Book id
bookId.shortDescription=Id of the book to fetch, usually ${bookId}
expectedStatus.displayName=Expected status
expectedStatus.shortDescription=HTTP status that marks the sample as successful

<com.example.bookshelf.jmeter.sampler.BookLookupSampler guiclass="TestBeanGUI" testclass="com.example.bookshelf.jmeter.sampler.BookLookupSampler" testname="GET /api/books/{id} (TestBean)">
  <stringProp name="baseUrl">http://${__P(host,localhost)}:${__P(port,8080)}</stringProp>
  <stringProp name="bookId">${bookId}</stringProp>
  <intProp name="timeoutMs">5000</intProp>
  <stringProp name="expectedStatus">200</stringProp>
</com.example.bookshelf.jmeter.sampler.BookLookupSampler>
<hashTree/>

package com.example.bookshelf.jmeter.functions;

import java.util.Collection;
import java.util.List;
import java.util.concurrent.ThreadLocalRandom;

import org.apache.jmeter.engine.util.CompoundVariable;
import org.apache.jmeter.functions.AbstractFunction;
import org.apache.jmeter.functions.InvalidVariableException;
import org.apache.jmeter.samplers.SampleResult;
import org.apache.jmeter.samplers.Sampler;

/**
 * ${__randomIsbn(prefix,varName)}: a random, valid ISBN-13 such as 9781234567897.
 */
public class RandomIsbnFunction extends AbstractFunction {

    private static final String KEY = "__randomIsbn";
    private static final List<String> DESC = List.of(
            "Prefix, 978 or 979 (optional, default 978)",
            "Name of variable in which to store the result (optional)");

    private CompoundVariable[] values;

    @Override
    public void setParameters(Collection<CompoundVariable> parameters) throws InvalidVariableException {
        checkParameterCount(parameters, 0, 2);
        values = parameters.toArray(new CompoundVariable[0]);
    }

    @Override
    public String execute(SampleResult previousResult, Sampler currentSampler) {
        String prefix = values.length > 0 ? values[0].execute().trim() : "";
        if (prefix.isEmpty()) {
            prefix = "978";
        }
        StringBuilder isbn = new StringBuilder(prefix);
        ThreadLocalRandom random = ThreadLocalRandom.current();
        while (isbn.length() < 12) {
            isbn.append(random.nextInt(10));
        }
        int sum = 0;
        for (int i = 0; i < 12; i++) {
            sum += (isbn.charAt(i) - '0') * (i % 2 == 0 ? 1 : 3);
        }
        isbn.append((10 - sum % 10) % 10);
        String result = isbn.toString();
        addVariableValue(result, values, 1);
        return result;
    }

    @Override
    public String getReferenceKey() {
        return KEY;
    }

    @Override
    public List<String> getArgumentDesc() {
        return DESC;
    }
}

# src/main/resources/META-INF/services/org.apache.jmeter.functions.Function
com.example.bookshelf.jmeter.functions.RandomIsbnFunction

timeStamp,elapsed,label,...
1791977449081,109,isbn 9799220183907,...
1791977449327,113,isbn 9797458006036,...

package com.example.bookshelf.jmeter.backend;

import java.util.List;
import java.util.Map;
import java.util.TreeMap;

import org.apache.jmeter.config.Arguments;
import org.apache.jmeter.samplers.SampleResult;
import org.apache.jmeter.visualizers.backend.AbstractBackendListenerClient;
import org.apache.jmeter.visualizers.backend.BackendListenerContext;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/** Counts, per label, the samples slower than an SLA and logs the totals at the end of the test. */
public class SlaBreachBackendListenerClient extends AbstractBackendListenerClient {

    private static final Logger log = LoggerFactory.getLogger(SlaBreachBackendListenerClient.class);

    private long slaMs;
    private String labelPrefix;
    // only the single worker thread calls handleSampleResults, so a plain map is enough
    private final Map<String, long[]> counts = new TreeMap<>();

    @Override
    public Arguments getDefaultParameters() {
        Arguments args = new Arguments();
        args.addArgument("slaMs", "${__P(search_sla_ms,800)}");
        args.addArgument("labelPrefix", "GET /api/books");
        return args;
    }

    @Override
    public void setupTest(BackendListenerContext context) throws Exception {
        super.setupTest(context);
        slaMs = context.getLongParameter("slaMs", 800L);
        labelPrefix = context.getParameter("labelPrefix", "");
        log.info("SLA breach listener started: sla={} ms, labels starting with '{}'", slaMs, labelPrefix);
    }

    @Override
    public void handleSampleResults(List<SampleResult> sampleResults, BackendListenerContext context) {
        for (SampleResult result : sampleResults) {
            if (!result.getSampleLabel().startsWith(labelPrefix)) {
                continue;
            }
            long[] c = counts.computeIfAbsent(result.getSampleLabel(), k -> new long[2]);
            c[0]++;
            if (result.getTime() > slaMs) {
                c[1]++;
            }
        }
    }

    @Override
    public SampleResult createSampleResult(BackendListenerContext context, SampleResult result) {
        // drop what this client never looks at before it reaches the queue
        return result.getSampleLabel().startsWith(labelPrefix) ? result : null;
    }

    @Override
    public void teardownTest(BackendListenerContext context) throws Exception {
        counts.forEach((label, c) -> log.info("SLA breaches for '{}': {} of {} samples over {} ms",
                label, c[1], c[0], slaMs));
        counts.clear();
        super.teardownTest(context);
    }
}

# src/main/resources/META-INF/services/org.apache.jmeter.visualizers.backend.BackendListenerClient
com.example.bookshelf.jmeter.backend.SlaBreachBackendListenerClient

<BackendListener guiclass="BackendListenerGui" testclass="BackendListener" testname="SLA breaches">
  <elementProp name="arguments" elementType="Arguments" guiclass="ArgumentsPanel" testclass="Arguments">
    <collectionProp name="Arguments.arguments">
      <elementProp name="slaMs" elementType="Argument">
        <stringProp name="Argument.name">slaMs</stringProp>
        <stringProp name="Argument.value">${__P(search_sla_ms,800)}</stringProp>
        <stringProp name="Argument.metadata">=</stringProp>
      </elementProp>
      <elementProp name="labelPrefix" elementType="Argument">
        <stringProp name="Argument.name">labelPrefix</stringProp>
        <stringProp name="Argument.value">GET /api/books</stringProp>
        <stringProp name="Argument.metadata">=</stringProp>
      </elementProp>
    </collectionProp>
  </elementProp>
  <stringProp name="classname">com.example.bookshelf.jmeter.backend.SlaBreachBackendListenerClient</stringProp>
  <stringProp name="QUEUE_SIZE">5000</stringProp>
</BackendListener>
<hashTree/>

INFO o.a.j.v.b.BackendListener: SLA breaches: Starting worker with class: class com.example.bookshelf.jmeter.backend.SlaBreachBackendListenerClient and queue capacity: 5000
INFO c.e.b.j.b.SlaBreachBackendListenerClient: SLA breach listener started: sla=800 ms, labels starting with 'GET /api/books'
INFO c.e.b.j.b.SlaBreachBackendListenerClient: SLA breaches for 'GET /api/books/{id} (TestBean)': 17 of 40 samples over 800 ms

package com.example.bookshelf.jmeter.report;

import java.util.Collections;
import java.util.Map;

import org.apache.jmeter.report.processor.MapResultData;
import org.apache.jmeter.report.processor.TimeRateAggregatorFactory;
import org.apache.jmeter.report.processor.ValueResultData;
import org.apache.jmeter.report.processor.graph.AbstractGraphConsumer;
import org.apache.jmeter.report.processor.graph.AbstractOverTimeGraphConsumer;
import org.apache.jmeter.report.processor.graph.GroupInfo;
import org.apache.jmeter.report.processor.graph.NameSeriesSelector;
import org.apache.jmeter.report.processor.graph.TimeStampKeysSelector;

/** Dashboard graph: samples per second slower than a threshold, one series per label. */
public class SlowSamplesPerSecondGraphConsumer extends AbstractOverTimeGraphConsumer {

    private long thresholdMs = 800;

    // property.set_threshold_ms=800 in user.properties calls this setter
    public void setThresholdMs(long thresholdMs) {
        this.thresholdMs = thresholdMs;
    }

    @Override
    protected TimeStampKeysSelector createTimeStampKeysSelector() {
        TimeStampKeysSelector keysSelector = new TimeStampKeysSelector();
        keysSelector.setSelectBeginTime(true);
        return keysSelector;
    }

    @Override
    protected Map<String, GroupInfo> createGroupInfos() {
        return Collections.singletonMap(
                AbstractGraphConsumer.DEFAULT_GROUP,
                new GroupInfo(
                        new TimeRateAggregatorFactory(),
                        new NameSeriesSelector(),
                        // 1 for a slow sample, null (ignored) otherwise
                        (series, sample) -> !sample.isController() && sample.getElapsedTime() > thresholdMs ? 1.0 : null,
                        false, false));
    }

    @Override
    protected void initializeExtraResults(MapResultData parentResult) {
        parentResult.setResult(RESULT_CTX_GRANULARITY, new ValueResultData(getGranularity()));
    }

    @Override
    public void initialize() {
        super.initialize();
        ((TimeRateAggregatorFactory) getGroupInfos().get(AbstractGraphConsumer.DEFAULT_GROUP)
                .getAggregatorFactory()).setGranularity(getGranularity());
    }
}

jmeter.reportgenerator.graph.custom_slowSamples.classname=com.example.bookshelf.jmeter.report.SlowSamplesPerSecondGraphConsumer
jmeter.reportgenerator.graph.custom_slowSamples.title=Bookshelf: samples slower than 800 ms per second
jmeter.reportgenerator.graph.custom_slowSamples.property.set_threshold_ms=800
jmeter.reportgenerator.graph.custom_slowSamples.property.set_granularity=1000
jmeter.reportgenerator.graph.custom_slowSamples.property.set_X_Axis=Over Time
jmeter.reportgenerator.graph.custom_slowSamples.property.set_Y_Axis=Slow samples/s

WARN o.a.j.r.d.ReportGenerator: 'set_Y_Axis' is not a valid property for class 'com.example.bookshelf.jmeter.report.SlowSamplesPerSecondGraphConsumer', skip it
WARN o.a.j.r.d.ReportGenerator: 'set_X_Axis' is not a valid property for class 'com.example.bookshelf.jmeter.report.SlowSamplesPerSecondGraphConsumer', skip it

{
  "id": "bookshelf-jmeter-ext",
  "name": "Bookshelf JMeter Extensions",
  "description": "Book Lookup sampler, __randomIsbn function, SLA breach Backend Listener client and a slow-samples dashboard graph",
  "screenshotUrl": "https://github.com/example/bookshelf-jmeter-ext/raw/main/docs/book-lookup.png",
  "helpUrl": "https://github.com/example/bookshelf-jmeter-ext",
  "vendor": "Bookshelf QA",
  "markerClass": "com.example.bookshelf.jmeter.sampler.BookLookupSampler",
  "componentClasses": [
    "com.example.bookshelf.jmeter.sampler.BookLookupSampler",
    "com.example.bookshelf.jmeter.functions.RandomIsbnFunction",
    "com.example.bookshelf.jmeter.backend.SlaBreachBackendListenerClient"
  ],
  "versions": {
    "1.0.0": {
      "changes": "First release",
      "downloadUrl": "https://repo1.maven.org/maven2/com/example/bookshelf/bookshelf-jmeter-ext/1.0.0/bookshelf-jmeter-ext-1.0.0.jar",
      "depends": ["jmeter-core", "jmeter-java", "jmeter-components"],
      "libs": {}
    }
  }
}