Skip to content

CLI Tutorial

Jump to bottom
Sayantam Dey edited this page Dec 6, 2020 · 4 revisions

This is a quick tutorial on how to use the CLI, refer to the other pages for more information on a particular topic.

Installation

The recommended approach is to use docker-compose. You need to have make on your system. This is present by default on most Linux and OSX machines. For Windows, try installing with Chocolatey: choco install make.

cd hailstorm-cli
docker-compose up -d
make

This launches a container which shows a bash prompt:

hailstorm@ab7ecdeac102:/hailstorm$

🌟 make will wait for the database to be initialized. You may see messages such as Waiting for: tcp://hailstorm-db:3306 a number of times before the bash prompt is shown. This is the expected behavior.

The current directory on the host is mapped to /hailstorm in the container. Any files saved to this location in the container will persist across container restarts.

Create your project

hailstorm@ab7ecdeac102:/hailstorm$ hailstorm getting_started

This will create the following application directory structure and files -

getting_started/
|-- config
|   |-- boot.rb
|   |-- database.properties
|   `-- environment.rb
|-- db
|-- Gemfile
|-- jmeter
|-- log
|-- reports
|-- script
|   `-- hailstorm
|-- tmp
`-- vendor

Start the CLI

hailstorm@ab7ecdeac102:/hailstorm$ cd getting_started
hailstorm@ab7ecdeac102:/hailstorm/getting_started$ ./script/hailstorm
Welcome to the Hailstorm (version 5.0.0) shell.
Type help to get started...
hs > _

To bring down the containers, exit the CLI container, and execute on the host: docker-compose -f docker-compose-cli.yml down.

Add your JMeter plans

If you have got a JMeter script ready, copy it to the getting_started/jmeter directory along with any data files it may need. Make sure of two things -

  • You would typically want to control the number of threads each time JMeter executes your plan with a property whose value you pass as an argument to JMeter.
  • You must have the Simple Data Writer listener enabled in your test plan.

A bit of configuration

Open the getting_started/config/environment.rb file, copy the following contents and edit it.

Hailstorm.application.config do |config|

  # This is the JMeter configuration
  config.jmeter do |jmeter|

    # default properties for all jmeter/**/*.jmx files
    jmeter.properties do |map|
      # provide values to all your properties
      # ThreadGroup.num_threads is supposed to be present in the plan as ${__P(ThreadGroup.num_threads)}
      # and can optionally define a default value, in which case it is not necessary to redefine it here
      # map['ThreadGroup.num_threads'] = 10
    end
  end


  # Cluster configuration
  config.clusters(:amazon_cloud) do |cluster|
    cluster.access_key  = 'YOUR AWS ACCESS KEY'
    cluster.secret_key  = 'YOUR AWS SECRET KEY'
  end
end

Set it up

We'll now start the Hailstorm CLI application. You do this by executing the script/hailstorm executable file, which displays the hs > prompt to indicate that Hailstorm is ready to take commands.

$ script/hailstorm
hs > setup

If your JMeter plan does not have any errors and your EC2 keys are correct, when the setup command finishes, you'll have the complete infrastructure for load testing from Amazon EC2.

Run a few tests

Start your tests

You start your tests with the start command, that will create requisite number of EC2 instances (default m3.small type).

hs > start
4534: 15:25:28 [INFO] Starting load generation and monitoring on targets...
Active Clusters
===============================================================================
1] Amazon Cloud, region: us-west-1
+----------------+--------+----------------+------------+
| JMeter Plan    | Type   | IP Address     | JMeter PID |
+----------------+--------+----------------+------------+
| YourJMeterPlan | Master | 184.169.195.43 | 1111       |
+----------------+--------+----------------+------------+

Stop your tests

Depending on how you have set your tests up, you can stop your JMeter steps accordingly. If your tests run for a specific duration, and you try to stop your tests before the duration is up, Hailstorm will not stop the tests unless --force flag is used. If your test runs indefinitely, Hailstorm will stop it when you issue the stop command.

Assuming your JMeter plan runs the tests for a fixed duration, you can ask Hailstorm to wait till the tests are done -

hs > stop wait
3774: 18:08:48 [INFO] Stopping load generation and monitoring on targets...
4586: 18:08:55 [INFO] JMeter is still running, waiting as asked...
4586: 18:09:56 [INFO] JMeter has exited, proceeding...
4918: 15:27:48 [INFO] Fetching logs from  Amazon Cloud, region: us-east-1...
Active Clusters
===============================================================================
1] Amazon Cloud, region: us-east-1
+----------------+--------+----------------+------------+
| JMeter Plan    | Type   | IP Address     | JMeter PID |
+----------------+--------+----------------+------------+
| YourJMeterPlan | Master | 184.169.195.43 |            |
+----------------+--------+----------------+------------+

Rerun with modified configuration

You can make modifications to your configuration by editing the config/environment.rb. Hailstorm auatomatically detects changes to your configuration file and will run appropriate steps to sync your test environment. Go ahead and increase the number of threads in the configuration and start/stop the tests. Do it two more times at least.

Generate a report

Reports are simple to generate -

hs > results report
3774: 18:50:31 [INFO] Creating report for stopped tests...
3774: 18:50:41 [INFO] Report generated to: /home/vagrant/getting_started/reports/getting_started-1-3.docx

You can copy the report from your VM to your host machine (by copying to the /vagrant directory), and open it in Microsoft Word.

Terminate your environment

Once your done with your tests, you can terminate your test environment. Note that stopping tests does not stop the EC2 instances, so if you do not terminate, your EC2 instances will keep running (and Amazon will gleefully charge you!).

hs > terminate
3774: 18:57:55 [INFO] Terminating test cycle...
15982: 18:57:55 [INFO] Terminating agent#i-2f5d9349...

Further Resources

Clone this wiki locally