The build was originally derived from https://github.com/allardhoeve/bombard and https://github.com/klokantech/bombard-docker, with some changes made by me to allow for more control over how bombard called siege and reducing the size of the Docker environment.
Derived off work by the following:
-
Jeffrey Fulmer http://www.joedog.org/contact/author.shtml
-
Bill Proud <bill.proud@nl.wanadoo.com>
-
Peter Hutnick <phutnick@aperian.com>
-
Allard Hoeve (https://github.com/allardhoeve)
-
Klokan Technologies GmbH (https://github.com/klokantech)
I’ve made use of Siege from http:/www.joedog.org/ and Bombard from https://github.com/allardhoeve over the years, and decided to make few changes to bombard to better suit my testing needs. See the README.original.md for the original Siege Support Utilities document.
Using the Docker file in this project you can build an image to siege or bombard against an http service. A copy of the docker image is available via dockerhub
While siege can be run against a single url, it is generally more useful to run it against a list of urls. The url list allows for variables, so you can use those to make your test data mostly independent of the ultimate target ip address and port. For example
$ head -4 urls.txt
ADDR=192.168.10.103:8080
http://${ADDR}/editorial.html
http://${ADDR}/editorial/2020/03/14.cover-source.tif
http://${ADDR}/editorial/2020/03/14.cover.gif
Note that we are assuming your test data directory is being mounted onto the path /data in the container, and that /data is the default working directory for the container (you can override this with docker run’s '-w').
To run a siege test using a container image named 'bombard:latest' when you are in your data directory on your machine (not inside a docker instance), you could execute the following to start up a docker container running siege:
$ docker run --rm -v $(pwd):/data bombard:latest siege -l siege.log -f urls.txt -i -c 10 -b -r 10000
Within the container we read and write to the /data directory. By default the container assumes UID 1000 and GID 1000, but you can override the uid and gid values at runtime:
$ docker run --rm --user $(id -u):$(id -g) -it -v $(pwd):/data bombard:latest siege -l siege.log -f urls.txt -i -c 10 -b -r 10000
With this example siege, inside its container, will log to /data/siege.log ('-l siege.log') within the container, read its urls from /data/url.txt ('-f urls.txt') within the container, use internet mode ('-i') which tells it to randomly select urls from the data file, limits itself to 10 concurrent connections ('-c 10'), and runs in benchmark ('-b') mode which tells it to make requests as quickly as possible, and to exit after making 10,000 requests ('-r 10000').
The default user within the container, 'siegerc', has a siegerc configuration file in /.siege/. If you want to override these values you can bind an external directory over /.siege when you run the image, the same as we’re doing with our data directory.
The default siege configuration file here sets a 'logfile = /data/siege.log' and a 'file = /data/urls.txt', so if your 'data' directory source contains these files, they will be used by default unless you specify the '-l' / '--logfile' or '-f' / '--file' command line overrides.
See https://www.joedog.org/siege-manual/ for the full manual on siege’s capabilities and on the authors recommendations on how to most effectively use it.
The bombard tool can be used to graph siege results over time as concurrent users are added to the load.
The idea behind the bombard usage options are to scale up the number of users on each run, and then examine the siege log to graph the performance profile of the service as concurrent users increases.
The usage:
$ docker run --rm -it -v $(pwd):/data bombard:latest bombard -h
usage:
bombard --initial <n> --step <n> --runs <n> [<options>]
required parameters:
--initial <n>:
the number of concurrent users on the initial run
--step <n>:
the number of users to add on each subsequent run
--runs <n>:
the total number of siege runs to execute
options:
--output <dir>:
output directory for bombard results, by default this will be the
directory holding the siege log
-h | --help:
print full help, including siege options, and exit
-v | --version:
print version and exit
optional seige arguments to pass on each run:
-V, --version VERSION, prints the version number.
-h, --help HELP, prints this section.
-C, --config CONFIGURATION, show the current config.
-v, --verbose VERBOSE, prints notification to screen.
-q, --quiet QUIET turns verbose off and suppresses output.
-g, --get GET, pull down HTTP headers and display the
transaction. Great for application debugging.
-p, --print PRINT, like GET only it prints the entire page.
-c, --concurrent=NUM CONCURRENT users, default is 10
-r, --reps=NUM REPS, number of times to run the test.
-t, --time=NUMm TIMED testing where "m" is modifier S, M, or H
ex: --time=1H, one hour test.
-d, --delay=NUM Time DELAY, random delay before each request
-b, --benchmark BENCHMARK: no delays between requests.
-i, --internet INTERNET user simulation, hits URLs randomly.
-f, --file=FILE FILE, select a specific URLS FILE.
-R, --rc=FILE RC, specify an siegerc file
-l, --log[=FILE] LOG to FILE. If FILE is not specified, the
default is used: PREFIX/var/siege.log
-m, --mark="text" MARK, mark the log file with a string.
between .001 and NUM. (NOT COUNTED IN STATS)
-H, --header="text" Add a header to request (can be many)
-A, --user-agent="text" Sets User-Agent in request
-T, --content-type="text" Sets Content-Type in request
-j, --json-output JSON OUTPUT, print final stats to stdout as JSON
--no-parser NO PARSER, turn off the HTML page parser
--no-follow NO FOLLOW, do not follow HTTP redirects
note that not all siege options make sense from the context of bombard, and
those that are detected will be dropped or overridden
As an example, take the following run:
$ docker run --rm -it -v $(pwd):/data bombard:latest bombard --initial 5 --step 1 --runs 20 -l siege.log -f urls.txt -i -b -r 10000
This example would start with 5 concurrent users, then add 1 more user on each run, for a total of 20 runs. This will ultimately run '(initial + ((runs-1) * step)' users, or 24 concurrent users. The, '-l', '-f', '-i', '-b', and '-r' flags are all passed through to siege, meaning the log will be written to siege.log, the urls read from urls.txt, it will operate in "internet" mode (random selection of urls for the source urls list), benchmarking mode (no pause between requests), and will make 10,000 requests.
After the siege runs have completed bombard will examine the 'logfile' siege produced, and produce its report.
The report files are placed into a subdirectory 'YYYY-MM-DD' within the output directory. The output files within that 'YYYY-MM-DD' directory will be named after the hour and minute the last run ended, 'MMHH.*' The graphs chart the trendline for response times compared to users and connection rates. As an example:
$ ls -l 2020-03-15/0050* -rw-r--r-- 1 jimr staff 2683 Mar 14 17:50 2020-03-15/0050 -rw-r--r-- 1 jimr staff 204 Mar 14 17:50 2020-03-15/0050.bps -rw-r--r--@ 1 jimr staff 2561 Mar 14 17:50 2020-03-15/0050.bps.png -rw-r--r-- 1 jimr staff 179 Mar 14 17:50 2020-03-15/0050.conc -rw-r--r--@ 1 jimr staff 2113 Mar 14 17:50 2020-03-15/0050.conc.png -rw-r--r-- 1 jimr staff 11138874 Mar 14 17:50 2020-03-15/0050.info -rw-r--r-- 1 jimr staff 165 Mar 14 17:50 2020-03-15/0050.resp -rw-r--r--@ 1 jimr staff 1586 Mar 14 17:50 2020-03-15/0050.resp.png -rw-r--r-- 1 jimr staff 228 Mar 14 17:50 2020-03-15/0050.tps -rw-r--r--@ 1 jimr staff 2608 Mar 14 17:50 2020-03-15/0050.tps.png
A description of the summary and graph files:
| Name | Description |
|---|---|
0050 |
Master siege log, one line per run |
0050.info |
The urls data passed to siege |
0050.bps.png |
Graph of bytes per second served, by user load |
0050.conc.png |
Graph of the concurrency, average simultaneous connections, by user load |
0050.resp.png |
Graph of the response time, in seconds, by user load |
0050.tps.png |
Graph of the transactions per second by, user load |
The other files, with extensions .bps, .conf, .info, .resp, and .tps are the data files fed to into siegechart to produce the graphs. They are derived from the Master siege log data file.
Since we’re mounting our current directory as /data in this example, we should expect to find the final 'seige.log' and 'YYYY-MM-DD' output directory there.