Automates running Apache JMeter on Amazon EC2
Shell Perl
Switch branches/tags
Nothing to show
Pull request Compare This branch is 1 commit ahead, 183 commits behind oliverlloyd:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


JMeter ec2 Script

This shell script will allow you to run your local JMeter jmx files either using Amazon's EC2 service or you can provide it with a simple, comma-delimeted list of hosts to use. It does not use Distributed mode to run the test so it is effectively infinitely scalable (Distributed mode means all results are written to a central location which at high volumes can create a bottleneck).

By default it will launch the required hardware using Amazon EC2 (ec2 mode)using SUSE Linux AMIs dynamically installing Java and Apache JMeter (2.5.1). In this mode you can run your test over as many instances as you wish (or are allowed to create by Amazon - the default is 20). Alternatively, you can pass in a list of pre-prepared hostnames and the test load will be distributed over these.

Unlike distributed mode, you do not need to adjust the test parameters to ensure even distribution of the load; the script will automatically adjust the thread counts based on how many hosts are in use. As the test is running it will collate the results from each host in real time and display an output of the Generate Summary Results listener to the screen (showing both results host by host and an aggregated view for the entire run). Once execution is complete it will download each host's jtl file and collate them all together to give a single jtl file that can be viewed using the usual JMeter listeners.

Further details and idiot-level step by step instructions:

-- Accept jmx filename as a parameter (not requiring that it be named the same as the directory)

  ./ [PROJECT NAME] [NUMBER OF INSTANCES DESIRED (if ec2 instances are required*)]

*IMPORTANT - There is a limit imposed by Amazon on how many instances can be run [the default is 20 instances - Oct 2011].

-- You cannot have variables in the field Thread Count, this value must be numeric
-- File paths cannot be dynamic, any variables in the filepath will not be used but the filename is not changed.

-- An Amazon ec2 account is required (only in ec2 mode).
-- Amazon API tools must be installed as per Amazon's instructions (only in ec2 mode).
-- Testplans should have a Generate Summary Results Listener present and enabled (no other listeners are required).

Execution Instructions (for UNIX based OSs)
1. Create a project directory on your machine. For example: '/home/username/jmeter-ec2/'. This is the working dir for the script. Under this directory just created, either:

a) Create a project directory, something like: '/home/username/jmeter-ec2/myproject' and then below that create two sub directories named 'jmx' and 'data'. Your directory structure should look something like:

or b) Extract the contents of the file.
Note. '/home/username/jmeter-ec2' can be anything so long as it is accessible and specified in the properties file.

2. Download all files from and place them in the root directory (eg. /home/username/jmeter-ec2).

3. Edit the file, each value listed below must be set:

LOCAL_HOME="[Your local project directory, created above, eg. /home/username/jmeter-ec2]"
The script needs to know a location remotely where it can read and write data from while it runs.

REMOTE_HOME="/tmp" # This value can be left as the default unless you have a specific requirement to change it
This is the location where the script will execute the test from - it is not important as it will only exist for the duration of the test.

AMI_ID="[A linix based AMI, eg. ami-c787bbb3]"
(only in ec2 mode) Recommended AMIs provided. Both Java and JMeter are installed by the script and are not required.

(only in ec2 mode) This depends on the type of AMI - it must be available for the AMI used.

(only in ec2 mode) The name of your security group created under your Amazon account. It must allow Port 22 to the local machine running this script.

(only in ec2 mode) Your Amazon key file - obviously must be installed locally.

(only in ec2 mode) The DIRECTORY where the Amazon PEM file is located. No trailing '/'!

(only in ec2 mode) Should be a valid value for where you want the instances to launch.

(only in ec2 mode) Different AMIs start with different basic users. This value could be 'ec2-user', 'root', 'ubuntu' etc.

How often running totals are printed to the screen. Based on a count of the summariser.interval property. (If the Generate Summary Results listener is set to wait 10 seconds then every 30 (3 * 10) seconds an extra row showing an agraggated summary will be printed.) The summariser.interval property in the standard file defaults to 180 seconds - in the file included with this project it is set to 15 seconds, like this we default to summary updates every 45 seconds.

If you do not wish to use ec2 you can provide a comma-separated list of pre-defined hosts.

If using ec2, then you can also provide a comma-separated list of pre-defined elastic IPs. This is useful is your test needs to pass through a firewall.

Allows the version to be chosen dynamically. Only works on 2.5.1, 2.6 and greater.

4. Copy your JMeter jmx file into the /jmx directory under your root project directory (LOCAL_HOME) and rename it to the same name as the directory. For example, if you created the directory'/testing/myproject' then you should name the jmx file 'myproject.jmx', if you are using LOCAL_HOME=/home/username/someproject then the jmx file should be renamed to 'someproject.jmx'
Note. This naming convention allows the script to work seemlessly over multiple projects (so long as they are all located in the same root) but it would not be difficult to edit the file to use a specific jmx filename.
5. Copy any data files that are required by your testplan to the /data sub directory.

6. Open a termnal window and cd to the project directory you created (eg. cd /home/username/someproject)

7. Type: ./ someproject 1

Where 'someproject' is the name of the project directory (and jmx file) and '1' is the number of instances you wish to spread the test over. If you have provided a list of hosts using REMOTE_HOSTS then this value is ignored and all hosts in the list will be used.

It is not uncommon for an instance to fail to start, this is part of using the Cloud and for that reason this script will dynamically respond to this event by adjusting the number of instances that are used for the test. For example, if you request 10 instances but 1 fails then the test will be run using only 9 machines. This should not be a problem as the load will still be evenly spread and the end results (the throughput) identical. In a similar fashion, should Amazon not provide all the instances you asked for (each accunt is limited) then the script will also adjust to this scenario.
Any testplan should always have suitable pacing to regulate throughput. This script distributes load based on threads, it is assumed that these threads are setup with suitable timers. If not, adding more hardware could create unpredictable results.

JMeter-ec2 is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

JMeter-ec2 is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with JMeter-ec2.  If not, see <>.

The source repository is at: