Home

Awesome

Gee / JMeter EC2 script

Gee is a project based on the Oliver Lloyd's jmeter-ec2 script. I've added few extensions and modifitcations, like:

If all pre-requisits are met, script will automatically download all required tools and plugins.

Prerequisites

  1. java 6+ with JAVA\_HOME sys variable set required to locally generate graphs
  2. CLI tools: scp, wget, zip/bzip2, unzip, grep, awk
  3. an EC2 account, a key pair pem file and AWS Access Key ID & Secret Access Key
  4. Python 2.6+ to run two scripts: genAggregateRepsTimesPercentilesReports.py & extractFaultyUrls.py

Obtaining AWS Access Key ID & Secret Access Key

To get your :

Then:

(*) i.e.: if your user name is 'jk', then file should be named: jk_secrets.properties ps. By default all the *_secrets.properties files are ignored by git. To change this behaviour please edit .gitignore file.

Video tutorials

I prepared a bunch og video tutorial showing how to configure and use Gee. Here's a list of all the videos:

Altenatively you can watch them all here: yt playlist

How to configure it

Edit the file jmeter-ec2.properties and follow instruction inside that file.

You can also create also a custom cfg file i.e. per specific environment and use it by passing "cfg" parameter to the jmeter-ec2.sh. This can be handy when running tests on local machines and non on EC2

    project="drKingShultz" cfg="your_custom_cfg_file.properties" ./jmeter-ec2.sh

How to set up your jmeter (jmx) project

Before you start adding your own projects, please refer to an example ones already present in the projects folder.

Now, in next few steps I'll try to explain how I configure my projects.

Step 1: First of all I highly recommend using Utlimate Thread Group plugin as the thread manager. This plugin gives you precise control over the generated traffic.

Step 2: Once you've added such a thread to your project, then to produce all the nice graphs, add four listeners to your project:

Step 3: Having all listeners in place, the next step is to configure them.

btw. Listener's "Configure" button is here : alt text

Step 4: In projects directory create a folder with the same name as the project file. Then put your jmx in there. Here's an example project folder structure:

./jmeter-ec2
    |
    \projects
        |
        \drKingShultz
            |
            \drKingShultz.jmx

Why do we need those listeners:

Generate Summary Results is used to show status updates while running your tests.
jp@gc Latencies Over Time result file is used to generate most of the graphs.
PerfMon Collector listeners, will collect stat data from the:

To collect data from both sources we're using server-agent. Read the short manual how to run the server agent on the remote machines.

How to run your project

Gee/JMeter-ec2 can be executed locally on you computer or using a CI system like Jenkins. At the moment this script works well on tested on Linux Mint 13,14,15, Ubuntu 12.04, RedHat 5.

How to run it locally

Once you have everything in place, simply run:

    project="drKingShultz" count="2" ./jmeter-ec2.sh

"count" stands for the number of EC2 instances to be launched

To get a bit more verbose output, enable DEBUG mode :

    DEBUG=true project="drKingShultz" count="2" ./jmeter-ec2.sh

How to run it locally using a comma-delimeted list of hosts

All the hosts used as load generators need to have a passwordless SSH access configured. Here's a nice article how this can be done on Debian based OSes.

Once SSH access is configured, then create a copy of an example-local-config.properties file and adjust it to your needs. The most important thing is to provide the list of the IPs/Hostnames you're going to use as generators and a pem key filename. This pem file is your private key, generated when configuring passwordless SSH access.

Then run the project providing the "cfg" parameter.

   project="drKingShultz" cfg="path/to/your/custom/local-config-file.properties" ./jmeter-ec2.sh

ps. You don't have to provide the "count" parameter, as it will be automatically set to the number of hosts provided in the config file.

Running locally with Vagrant

Vagrant allows you to test your jmeter-ec2 scripts locally before pushing them to ec2.

Pre-requisits

Usage:

Use jmeter-ec2.properties.vagrant as a template for local provisioning. This file is setup to use Vagrants ssh key, ports, etc.

# start vm and provision defaultjre
vagrant up
# run your project
project="drKingShultz" cfg=jmeter-ec2.properties.vagrant ./jmeter-ec2.sh
# or for a more verbose output run it with DEBUG=true
DEBUG=true project="drKingShultz" cfg=jmeter-ec2.properties.vagrant ./jmeter-ec2.sh

Note

How to run it on Jenkins

Create a new job:

Mark 'This build is parameterized' as enabled. Then:

in the "Build" section add "Execute shell" and paste the code below:

    # change permission for keys
    if [ -e ec2/jmeter-ec2.pem ]; then
        chmod 400 ec2/jmeter-ec2.pem
    fi;

    # run the tests
    project="drKingShultz" count="2" ./jmeter-ec2.sh

    # remove the unnecessary pem file
    # will prevent errors when trying to overide pem file on a new build 
    if [ -e ec2/jmeter-ec2.pem ]; then
        rm ec2/jmeter-ec2.pem
    fi;

To analyze result files and create a simple performance report: Add a "Publish performance test result report" post-build action. Then point at the $WORKSPACE/projects/drKingShultz/results/jenkins.jtl file Add desired performance thresholds to decide when tests should pass or fail.

Reports

Once test is finished, you can find a simple HTML report in the:

jmeter-ec2
    |
    \drKingShultz
        |
        \results

Report file name is configurable. By default script will use: ${DATETIME}-report.html where ${DATETIME} is the current datetime taken on script start. Datetime pattern is %Y-%m-%d_-_%H-%M so an example report filename will be:

btw. If you plan to run this script on Jenkins, then it's worth setting the report name (cfg variable name is: cfgHtmlReportFilename) to something like index.html Then it's easy to point at a fixed filename when using plugins like HTML Publisher plugin

Handy Jenkins Plugins

A list of Jenkins plugins I found quite handy when working with it.

Test run outputs

Everytime you run your tests, Gee produces few files that can:

What can be generated:

All these files can generated once enabled in your configuration file. Btw. by default most of them are already enabled :) Here's a list of all configuration flags, that control what is produced during a test run:

How to generate graphs from long test runs

By default jmeter-ec2 script will generate graphs using 1920x1200px resolution. In case you need to create a report from a very long test, and you want to change the default graph resolution, then you can use analyzeZippedResults.sh script for this purpose.

Here's an example usage:

    FILES="path/to/a/folder/with/result/files/file_name_pattern_with_an_asterisk-*.zip" WIDTH=20000 HEIGHT=1080 ./analyzeZippedResults.sh

Where:

License:

Gee / 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.

Gee / JMeter-ec2 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Gee / JMeter-ec2. If not, see http://www.gnu.org/licenses/.

handy bash commands

find which custom workspace is used by selected Jenkins jobs

    cd /dir/with/jenkins/jobs
    find QAA* -iname config.xml -print0 | xargs -0 grep customWorkspace

Original Jenkins-ec2 description:

Is available @ jmeter-ec2 page.