QPID-4656: added perftests documentation

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1457805 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 105 insertions, 0 deletions

diff --git a/qpid/java/perftests/README-java-perftests.txt b/qpid/java/perftests/README-java-perftests.txt
new file mode 100644
index 0000000000..9af77ebb21
--- /dev/null
+++ b/qpid/java/perftests/README-java-perftests.txt
@@ -0,0 +1,105 @@
+The qpid-perftests distributed JMS test framework
+=================================================
+
+This folder contains the distributed test (aka Perf Test) framework written for
+testing the performance of a JMS provider. Although it was written for the
+purpose of testing Qpid, it can be used to test the performance of any JMS
+provider with minimal configuration changes.
+
+This document explains how to use the framework.
+
+
+How it works
+------------
+
+First, you need to run a message broker. This can be Qpid, ActiveMQ etc. All
+messages are sent using the JMS API.
+
+Then run a Perf Test Controller, providing the details of the test in either or
+a JSON or Javascript file. This specifies details about the messages to send,
+how many connections and sessions to use etc. There are a lot of options
+available - see the .js and .json files under this folder for examples.
+
+Now run one or more Perf Test Client processes. These will be responsible for
+sending/receiving the messages once the test starts. For convenience, you can
+instead configure the Controller to start clients in-process. The clients and
+the controller communicate using queues on the message broker.
+
+The test results are written to CSV files.
+
+You can use the qpid-perftests-visualisation tool to create charts from the CSV files.
+
+Example usage
+-------------
+
+The etc/ folder contains shell scripts that can be used to run the performance
+tests and visualise the results.  It also contains sub-folders for test config
+and chart definitions.
+
+Instructions
+------------
+
+1. Extract the archive
+
+2. cd into the etc/ folder
+
+3. Start your JMS broker
+
+4. To run the Controller and clients in a single process, run the following
+command:
+
+java -cp ".:../lib/*:/path/to/your-jms-client-jars/*" \
+  -Dqpid.dest_syntax=BURL \
+  org.apache.qpid.disttest.ControllerRunner \
+  jndi-config=perftests-jndi.properties \
+  test-config=/path/to/test-config.json \
+  distributed=false
+
+Note that the test-config parameter can point at either a JSON or Javascript
+file, or at a directory (in which case all the .json and .js files in the
+directory are used.
+
+When the test is complete, the CSV files containing the results are written to
+the current directory.
+
+
+Running the clients in a separate process
+-----------------------------------------
+
+When using a large number of clients, you may get more representative
+performance results if the clients are distributed among multiple processes,
+potentially on multiple machines. To do this:
+
+1. Run the Controller, providing distributed=true.
+
+2. Run your clients (assuming you want to launch 10 logical clients in this
+process):
+
+java -cp ".:../lib/*:/path/to/your-jms-client-jars/*" \
+  -Dqpid.dest_syntax=BURL \
+  org.apache.qpid.disttest.ClientRunner \
+  jndi-config=perftests-jndi.properties \
+  number-of-clients=10
+
+
+Caveats for non-Qpid JMS providers
+----------------------------------
+
+If you are not using the Qpid broker, you must create one or more queues before
+running the test.  This is necessary because you can't use Qpid's API to create
+queues on the broker. The queues are:
+
+– The controller queue. You can specify the physical name of this in
+etc/perftests-jndi.properties. This queue is used by the clients to register
+with the Controller and to send results to it.
+– the queue(s) used by your JSON test configuration (unless you have configured
+a vendor-specific queue creator).
+
+You must also override the Controller's default queue creator using the system
+property qpid.disttest.queue.creator.class. Provide the class name of an
+implementation of org.apache.qpid.disttest.jms.QueueCreator, or
+org.apache.qpid.disttest.jms.NoOpQueueCreator if you are going to create and
+delete the queues manually.
+
+You can also omit the qpid.dest_syntax system property if your JMS provider is
+not Qpid.