README.adoc

April 16, 2025 · View on GitHub

= RabbitMQ Stream Performance Testing Tool

image:https://github.com/rabbitmq/rabbitmq-stream-perf-test/actions/workflows/test.yml/badge.svg["Build Status", link="https://github.com/rabbitmq/rabbitmq-stream-perf-test/actions/workflows/test.yml"]

This repository contains source code of the RabbitMQ Stream Performance Testing Tool. The client is maintained by the https://github.com/rabbitmq/[RabbitMQ team at Broadcom].

Stream PerfTest is based on the https://github.com/rabbitmq/rabbitmq-stream-java-client/[stream Java client] and uses the https://github.com/rabbitmq/rabbitmq-server/blob/main/deps/rabbitmq_stream/docs/PROTOCOL.adoc[stream protocol] to communicate with a RabbitMQ cluster. Use https://perftest.rabbitmq.com[PerfTest] if you want to test streams or queues with https://www.rabbitmq.com/tutorials/amqp-concepts.html[AMQP 0.9.1].

== Pre-requisites

Stream PerfTest requires Java 11 or later to run.

== Installation

This is a standalone tool that is distributed in binary form using https://github.com/rabbitmq/rabbitmq-stream-perf-test/releases[GitHub releases]. A https://hub.docker.com/r/pivotalrabbitmq/stream-perf-test/[Docker image] is available as well.

The https://github.com/rabbitmq/rabbitmq-java-tools-binaries-dev/releases/tag/v-stream-perf-test-latest[latest snapshot] is also available.

== Documentation

https://rabbitmq.github.io/rabbitmq-stream-perf-test/stable/htmlsingle/[Latest stable release]
https://rabbitmq.github.io/rabbitmq-stream-perf-test/snapshot/htmlsingle/[Latest development build]

== Support

For questions: https://groups.google.com/forum/#!forum/rabbitmq-users[RabbitMQ Users]
For bugs and feature requests: https://github.com/rabbitmq/rabbitmq-stream-perf-test/issues[GitHub Issues]

See the https://www.rabbitmq.com/client-libraries/java-versions[RabbitMQ Java libraries support page] for the support timeline of this tool.

== Usage

Download the latest snapshot:

wget https://github.com/rabbitmq/rabbitmq-java-tools-binaries-dev/releases/download/v-stream-perf-test-latest/stream-perf-test-latest.jar

Launch a performance test with 1 producer and 1 consumer:

java -jar stream-perf-test-latest.jar

Use

java -jar stream-perf-test-latest.jar --help

to see all supported options.

== Build Instructions

You need JDK 11 or later installed.

To build the JAR file:

./mvnw clean package -Dmaven.test.skip

To run the performance tool from the created binary:

java -jar target/stream-perf-test.jar

== Running Tests with Docker

Launch the broker:

docker run -it --rm --name rabbitmq -p 5552:5552 -p 5672:5672
-e RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS='-rabbitmq_stream advertised_host localhost'
rabbitmq:4.1

Enable the stream plugin:

docker exec rabbitmq rabbitmq-plugins enable rabbitmq_stream

Launch the tests:

./mvnw test -Drabbitmqctl.bin=DOCKER:rabbitmq

=== Running Tests with a Local Broker

To launch the test suite (requires a local RabbitMQ node with stream plugin enabled):

./mvnw verify -Drabbitmqctl.bin=/path/to/rabbitmqctl

== Code Format

The project uses the https://github.com/google/google-java-format[Google Java Format]. Read the documentation to support the format in your https://github.com/google/google-java-format#intellij-android-studio-and-other-jetbrains-ides[favorite] https://github.com/google/google-java-format#eclipse[IDE].

Please launch the ./mvnw spotless:apply command to format your changes before committing.

== Copyright and License

Double licensed under the MPL2.0 and ASL2. See link:LICENSE[LICENSE] for details.