ClusterBench is a simple application that can be deployed in a cluster of JBoss AS 7 (EAP 6), WildFly 8 and newer. Once deployed it is easy to stress (using JMeter, curl, etc.) and monitor the performance of the cluster while at the same time it can be easily checked the correctness of replicated sessions.
| ClusterBench Version | WildFly Version | Tomcat Version | EE Version(s) | Base JDK |
|---|---|---|---|---|
16 |
39 & 39-preview |
10.1, 11.0 |
Jakarta EE 10 & 11 |
17 |
15 |
38 |
10.1, 11.0 |
Jakarta EE 10 |
17 |
14 |
37 |
10.1, 11.0 |
Jakarta EE 10 |
17 |
13 |
36 |
10.1, 11.0 |
Jakarta EE 10 |
17 |
12 |
35 |
10.1 |
Jakarta EE 10 |
17 |
11 |
34 |
10.1 |
Jakarta EE 10 |
11 |
10 |
33 |
10.1 |
Jakarta EE 10 |
11 |
9 |
32 |
10.1 |
Jakarta EE 10 |
11 |
8 |
31 |
10.1 |
Jakarta EE 10 |
11 |
7 |
30 |
10.1 |
Jakarta EE 10 |
11 |
6 |
29 |
10.1 |
Jakarta EE 10 |
11 |
5 |
28 |
10.1 |
Jakarta EE 10 |
11 |
4 |
27 |
10.1 |
Jakarta EE 10 |
11 |
3 |
26 (and previous) |
Java EE 5, EE 6, EE 7, EE 8 |
8 |
Clone the Git repository first and switch to its directory:
git clone https://github.com/clusterbench/clusterbench.gitBuild the default main branch to build the latest Jakarta EE 10 version:
./mvnw packageOutput files:
./clusterbench-ee10-ear/target/clusterbench-ee10.ear
You can also use wildfly-maven-plugin to run a container with the project already deployed.
It will also provision the server without having to download anything manually.
./mvnw wildfly:run -f clusterbench-ee10-ear/pom.xml -D provisionand navigate your browser to http://localhost:8080/clusterbench/.
You can use the deploy goal of the WildFly Maven Plugin to deploy to your running instance by running:
./mvnw wildfly:deploy --file clusterbench-ee10-ear/pom.xmlwhich will deploy the resulting EAR to the running server.
To do this manually, copy clusterbench-ee10.ear to server’s deployments directory
and start the standalone server in the HA mode:
cd ~/wildfly-34.0.0.Final
cp ~/clusterbench/clusterbench-ee10-ear/target/clusterbench-ee10.ear standalone/deployments/
./bin/standalone.sh -c standalone-ha.xmlYou can also use the CLI to do so by starting the server, connecting with CLI and using deploy command:
cd ~/wildfly-34.0.0.Final
./bin/standalone.sh -c standalone-ha.xmlThen connect with the CLI:
./bin/jboss-cli.sh -c
[standalone@localhost:9990 /] deploy ~/clusterbench/clusterbench-ee10-ear/target/clusterbench-ee10.earIf you prefer GUI, you can start the server and navigate to http://localhost:9990/ and follow the instructions.
To deploy the Tomcat variant of ClusterBench, copy the following war file into Tomcat installation webapps/ directory
renaming it accordingly to the desired context, typically to clusterbench.war to correspond with the context path on WildFly.
cp ~/git/clusterbench/clusterbench-ee10-web/target/clusterbench-ee10-web-tomcat.war webapps/clusterbench.warNote that CDI, EJB, JSF, granular, and debug servlets are unsupported on Tomcat and not bundled in the war.
That makes the session servlet the only one available for performance benchmarking.
First, make sure you have oc and helm installed. Now, log into OpenShift using the following
replacing with your token and server address:
oc login --token=sha256~<your_token> --server=https://api.sandbox-m3.1530.p1.openshiftapps.com:6443First add the WildFly helm repo:
helm repo add wildfly https://docs.wildfly.org/wildfly-charts/Now install the helm chart:
helm install clusterbench-from-chart -f charts/helm.yaml wildfly/wildflyYou can watch the build using oc:
oc get build -wOnce built, watch the deployment using:
oc get deployment clusterbench-from-chart -wOnce deployed, you can access the application for example the debug servlet using curl:
curl https://$(oc get route clusterbench-from-chart --template='{{ .spec.host }}')/clusterbench/debug
...
Serial: 0
Session ID: nPw9NzEmPaZHlj0eYoCapZfBBOnNk_5HXNpq2Qi_
Current time: Wed Mar 22 14:36:52 GMT 2023Once finished, remove everything using:
helm uninstall clusterbench-from-chartEach servlet stresses a different replication logic, but they all produce the same reply:
number of times (integer) the servlet has been previously invoked within the existing session in a text/plain response.
In other words, the first request returns 0 and each following invocation returns number incremented by 1.
Furthermore, each HTTP session carries 4 KB of dummy session data in a byte array.
The 'default' servlet. Stores serial number and data in SerialBean object (POJO) which is directly stored in jakarta.servlet.http.HttpSession.
Stores a serial number in @jakarta.enterprise.context.SessionScoped bean.
Stores serial and data in @jakarta.ejb.Stateful Jakarta Enterprise Bean (SFSB). The JEB is then invoked on every request.
Stores serial number and data separately and are both directly put to jakarta.servlet.http.HttpSession.
The byte array is never changed and thus can be used to test the efficiency of using granular session replication.
|
Caution
|
The server configuration in use must be configured with ATTRIBUTE session granularity!
|
There are also two oad generating Servlets for memory and CPU usage. These Servlets simulate load on the target system. These can be used to test the load-balancing mechanism of the reverse proxy.
Servlet simulating CPU load of the cluster node. Parameters are milliseconds (duration) and threads.
Servlet that prints out useful information such as: the request headers, URI, query string, path info, serial (does create a session), session ID, time, server and local ports, node name, parameters, and cluster address/coordinator/members/physical addresses.
Servlet which allows to customize the HTTP status response code. Requires mandatory integer code parameter.
Servlet which prints out the node name as a value of the jboss.node.name system property.
Servlet which logs the provided message in the msg parameter to the server log.
If no message is provided, a simple ping message is logged.
The log message level can be optionally provided in the level parameter.
Logs at INFO level by default.
Invoking this servlet causes server to completely stop without sending proper response and triggering shutdown hooks. This servlet can be used in orchestrating failover scenarios from a client.
The ClusterBench application offers a limited set of configurable options. It is important to specify identical value for all containers within the cluster!
The deployment at /clusterbench-passivating has preconfigured <max-active-sessions> to 10000.
This value can be overridden by a org.jboss.test.clusterbench.max-active-sessions system property.
./bin/standalone.sh -c standalone-ha.xml -Dorg.jboss.test.clusterbench.max-active-sessions=5The scripts directory at the root of the repository contains CLI scripts
for reconfiguring the application server for specific test scenarios.
These scripts can be combined to achieve a desired resulting configuration.
| Script | Description |
|---|---|
|
Reconfigures the default session manager to use |
|
Reconfigures the default session manager to use cache |
|
Adds a deployment overlay for the ClusterBench deployment which configures it for singleton deployment. |
|
Removes the previously added deployment overlay so that it will no longer operate as a singleton deployment. |
Example: singleton deployment
Following is a singleton deployment walk-through.
Start with two local servers already started and with clusterbench-ee10.ear deployed.
First run the provided scripts against both servers:
$JBOSS_HOME/bin/jboss-cli.sh --connect --file=singleton-deployment-overlay-add.cli $JBOSS_HOME/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=singleton-deployment-overlay-add.cli
The provided script adds a deployment overlay, which configures existing deployment for singleton deployment.
This is achieved by overlaying a META-INF/singleton-deployment.xml file.
Note that the script automatically redeploys the deployments affected by this overlay.
Now that these have configured both deployments for singleton deployment, observe the server log:
10:39:16,287 INFO [org.wildfly.clustering.singleton.server] (main - 1) WFLYCLSN0003: node2 elected as the singleton provider of the jboss.deployment.unit."clusterbench-ee10.ear".installer service 10:39:16,287 INFO [org.wildfly.clustering.singleton.server] (main - 1) WFLYCLSN0001: This node will now operate as the singleton provider of the jboss.deployment.unit."clusterbench-ee10.ear".installer service
We can now verify that only one of the contexts is available:
[rhusar@puglia wildfly]$ curl --head http://localhost:8080/clusterbench/ HTTP/1.1 404 Not Found Connection: keep-alive Content-Length: 74 Content-Type: text/html Date: Mon, 23 Sep 2024 08:50:28 GMT [rhusar@puglia wildfly]$ curl --head http://localhost:8180/clusterbench/ HTTP/1.1 200 OK Connection: keep-alive Last-Modified: Fri, 03 May 2024 14:27:54 GMT Content-Type: text/html Content-Length: 1335 Accept-Ranges: bytes Date: Mon, 23 Sep 2024 08:50:29 GMT
Notice that only one of the servers has returned a valid answer.
To undo the changes, run the 'remove' variant of the scripts:
[rhusar@puglia scripts]$ $JBOSS_HOME/bin/jboss-cli.sh --connect --file=singleton-deployment-overlay-remove.cli [rhusar@puglia scripts]$ $JBOSS_HOME/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=singleton-deployment-overlay-remove.cli
There are several profiles to test specific scenarios where the standard build needs to be modified.
When no custom profile is specified, the default profile is used.
This profile produces a build to test a shared sessions scenario where two WARs in the same EAR share HTTP sessions:
./mvnw install -P shared-sessions -DskipTestsUsed to shorten the names of bundled JARs and WARs within the resulting EAR file. Used in database tests to produce database tables with short names.
./mvnw clean install -P short-names -DskipTestsFile new issues using GitHub Issues:
Contributions are welcome! Submit pull requests against the upstream repository on GitHub. Please follow the existing coding standards to keep the application clean and simple. This repository uses Conventional Commits.
Project is licensed under Apache License Version 2.0.
Happy benchmarking!