bench-rest
Advanced tools
bench-rest - benchmark REST (HTTP/HTTPS) API's. Node.js client module for easy load testing / benchmarking REST API' using a simple structure/DSL can create REST flows with setup and teardown and returns (measured) metrics.
Node.js client module for easy load testing / benchmarking REST (HTTP/HTTPS) API's using a simple structure/DSL can create REST flows with setup and teardown and returns (measured) metrics.
Roughly bench-rest = mikeal/request + caolan/async + felixge/node-measured
Requires node.js >= 0.10
# If using programmatically
npm install bench-rest
# OR possibly with -g option if planning to use from command line
npm install -g bench-rest
Simple flow performing 100 iterations with 10 concurrent connections
var benchrest = require('bench-rest');
var flow = 'http://localhost:8000/'; // can use as simple single GET
// OR more powerfully define an array of REST operations with substitution
// This does a unique PUT and then a GET for each iteration
var flow = {
main: [
{ put: 'http://localhost:8000/foo_#{INDEX}', json: 'mydata_#{INDEX}' },
{ get: 'http://localhost:8000/foo_#{INDEX}' }
]
};
// if the above flow will be used with the command line runner or
// programmatically from a separate file then export it.
module.exports = flow;
// There are even more flow options like setup and teardown, see detailed usage
var runOptions = {
limit: 10, // concurrent connections
iterations: 100 // number of iterations to perform
};
benchrest(flow, runOptions)
.on('error', function (err, ctxName) { console.error('Failed in %s with err: ', ctxName, err); })
.on('end', function (stats, errorCount) {
console.log('error count: ', errorCount);
console.log('stats', stats);
});
See Detailed Usage section below for more details
## Command-line usage# if installed with -g
bench-rest
# otherwise use from node_modules
node_modules/.bin/bench-rest
Outputs
Usage: bench-rest [options] <flow-js-path-or-GET-URL>
Options:
-h, --help output usage information
-V, --version output the version number
-n --iterations <integer> Number of iterations to run, defaults to 1
-a --prealloc <integer> Max iterations to preallocate, defaults 100000
-c --concurrency <integer> Concurrent operations, defaults to 10
-d --progress <integer> Display progress bar (> 0), update every N ms, defaults 1000
-u --user <username> User for basic authentication, default no auth
-p --password <password> Password for basic authentication
-e --evaluate <flow-string> Evaluate flow from string, not file
Examples:
bench-rest -n 100 -c 100 ./examples/simple.js
bench-rest -n 100 -c 100 -u "joe" -p "secret" /foo/flow.js
bench-rest -n 10 -c 2 http://localhost:8000/
bench-rest -n 10 -c 2 -e "{ head: 'http://localhost:8000/' }"
Running this
bench-rest -n 1000 -c 50 ./examples/simple.js
would output
Benchmarking 1000 iteration(s) using up to 50 concurrent connections
Using flow from: /Users/barczewskij/projects/bench-rest/examples/simple.js
{ main: [ { get: 'http://localhost:8000/' } ] }
Progress [=======================================] 100% 0.0s conc:49 1341/s
errors: 0
stats: { totalElapsed: 894,
main:
{ meter:
{ mean: 1240.6947890818858,
count: 1000,
currentRate: 1240.6947890818858,
'1MinuteRate': 0,
'5MinuteRate': 0,
'15MinuteRate': 0 },
histogram:
{ min: 4,
max: 89,
sum: 41603,
variance: 242.0954864864864,
mean: 41.603,
stddev: 15.55941793533699,
count: 1000,
median: 42,
p75: 50,
p95: 70.94999999999993,
p99: 81.99000000000001,
p999: 88.99900000000002 } } }
It has one expected required parameter which is the path to a node.js file which exports a REST flow. For example:
var flow = {
main: [{ get: 'http://localhost:8000/' }] // could be an array of REST operations
};
// if the above flow will be used with the command line runner or
// programmatically from a separate file then export it.
module.exports = flow;
Check for example flows in the examples directory.
See Detailed Usage for more details on creating more advanced REST flows.
## GoalsAdvanced flow with setup/teardown and multiple steps to benchmark in each iteration
var benchrest = require('bench-rest');
var flow = {
before: [], // operations to do before anything
beforeMain: [], // operations to do before each iteration
main: [ // the main flow for each iteration, #{INDEX} is unique iteration counter token
{ put: 'http://localhost:8000/foo_#{INDEX}', json: 'mydata_#{INDEX}' },
{ get: 'http://localhost:8000/foo_#{INDEX}' }
],
afterMain: [{ del: 'http://localhost:8000/foo_#{INDEX}' }], // operations to do after each iteration
after: [] // operations to do after everything is done
};
module.exports = flow;
var runOptions = {
limit: 10, // concurrent connections
iterations: 1000, // number of iterations to perform
prealloc: 100 // only preallocate up to 100 before starting
};
var errors = [];
benchrest(flow, runOptions)
.on('error', function (err, ctxName) { console.error('Failed in %s with err: ', ctxName, err); })
.on('progress', function (stats, percent, concurrent, ips) {
console.log('Progress: %s complete', percent);
})
.on('end', function (stats, errorCount) {
console.log('error count: ', errorCount);
console.log('stats', stats);
});
The main function from require('bench-rest') will return a node.js EventEmitter instance when called with the flow and runOptions. This event emitter will emit the following events:
error - emitted as an error occurs during a run. It emits parameters err and ctxName matching where the error occurred (main, before, beforeMain, after, afterMain)progress - emitted periodically as iterations complete. It emits parameters stats, percentComplete, concurrent, ips. The stats is the current measured stats (discussed below). The concurrent param is the concurrent connection count at that point in time. The ips is the calculated current iterations per second rate at which the iterations are executing. The interval at which progress is output is controlled by the runOption.progress in milliseconds.end - emitted when the benchmark run has finished (successfully or otherwise). It emits parameters stats and errorCount (discussed below).The stats is a measured data object and the errorCount is an count of the errors encountered. Time is reported in milliseconds. See measured for complete description of all the properties. https://github.com/felixge/node-measured
stats.totalElapsed is the elapsed time in milliseconds for the entire run including all setup and teardown operations
The stats.main will be the meter data for the main benchmark flow operations (not including the beforeMain and afterMain operations).
A couple key metrics to be aware of:
stats.main.meter.mean - average iterations / secstats.main.meter.count - iterations completedstats.main.meter.currentRate - iterations / sec at this moment (mainly useful when monitoring progress)stats.main.1MinuteRate - iterations / sec for the last minute (only relevant if more than 1 minute has passed)stats.main.histogram.min - the minimum time any iteration took (milliseconds)stats.main.histogram.max - the maximum time any iteration took (milliseconds)stats.main.histogram.mean - the average time any iteration took (milliseconds)stats.main.histogram.p95 - the amount of time that 95% of all iterations completed within (milliseconds)The output of the above run will look something like:
error count: 0
stats {
totalElapsed: 151,
main:
{ meter:
{ mean: 1190.4761904761904,
count: 100,
currentRate: 1190.4761904761904,
'1MinuteRate': 0,
'5MinuteRate': 0,
'15MinuteRate': 0 },
histogram:
{ min: 3,
max: 66,
sum: 985,
variance: 43.502525252525245,
mean: 9.85,
stddev: 6.595644415258091,
count: 100,
median: 8.5,
p75: 11,
p95: 17,
p99: 65.53999999999976,
p999: 66 } } }
If you have very simple flow that does not need setup and teardown, then there are a few shortcuts for expressing the flow.
var flow = 'http://localhost:8000/';var flow = { head: 'http://localhost:8000/' };// passing as array implies no setup/teardown and these are the main operations
var flow = [
{ put: 'http://localhost:8000/foo', json: 'mydata' },
{ get: 'http://localhost:8000/foo' }
];
The runOptions object can have the following properties which govern the benchmark run:
limit - required number of concurrent operations to limit at any given timeiterations - required number of flow iterations to perform on the main flow (as well as beforeMain and afterMain setup/teardown operations)prealloc - optional max number of iterations to preallocate before starting, defaults to lesser of 100K and iterations. When using large number of iterations or large payload per iteration, it can be necessary to adjust this for optimal memory use.user - optional user to be used for basic authenticationpassword - optional password to be used for basic authenticationprogress - optional, if non-zero number is provided it enables the output of progress events each time this number of milliseconds has passedThe REST operations that need to be performed in either as part of the main flow or for setup and teardown are configured using the following flow properties.
Each array of opertions will be performed in series one after another unless an error is hit. The afterMain and after operations will be performed regardless of any errors encountered in the flow.
var flow = {
before: [], // REST operations to perform before anything starts
beforeMain: [], // REST operations to perform before each iteration
main: [], // REST operations to perform for each iteration
afterMain: [], // REST operations to perform after each iteration
after: [] // REST operations to perform after everything is finished
};
Each operation can have the following properties:
get, head, put, post, patch, del (using del rather than delete since delete is a JS reserved word) with a value pointing to the URI, ex: { get: 'http://localhost:8000/foo' }method (use uppercase) and uri directly, ex: { method: 'GET', uri: 'http://localhost:8000/foo' }json optionally provide data which will be JSON stringified and provided as body also setting content type to application/json, ex: { put: 'http://localhost:8000/foo', json: { foo: 10 } }headers - optional headers to set, ex: { get: 'http://localhost:8000/foo', headers: { 'Accept-Encoding': 'gzip'}mikeal/request - see https://github.com/mikeal/requestbeforeHooks and afterHooks which can perform processing before and/or after an operation. See Pre/post operation processing section below for details.To make REST flows that are independent of each other, one often wants unique URLs and unique data, so one way to make this easy is to include special tokens in the uri, json, or data.
Currently the token(s) replaced in the uri, json, or body are:
#{INDEX} - replaced with the zero based counter/index of the iterationNote: for the json property the json object is JSON.stringified, tokens substituted, then JSON.parsed back to an object so that tokens will be substituted anywhere in the structure. If subsitution is not needed (no #{INDEX} in the structure, then no copy (stringify/parse) will be performed.
If an array of hooks is specified in an operation as beforeHooks and/or afterHooks then these synchronous operations will be done before/after the REST operation.
Built-in processing filters can be referred to by name using a string, while custom filters can be provided as a function, ex:
// This causes the HEAD operation to use a previously saved etag if found for this URI
// setting the If-None-Match header with it, and then if the HEAD request returns a failing
// status code
{ head: 'http://localhost:8000', beforeHooks: ['useEtag'], afterHooks: ['ignoreStatus'] }
The list of current built-in beforeHooks:
useEtag - if an etag had been previously saved for this URI with saveEtag afterHook, then set the appropriate header (for GET/HEAD, If-None-Match, otherwise If-Match). If was not previously saved or empty then no header is set.The list of current built-in afterHooks:
saveEtag - afterHook which causes an etag to be saved into an object cache specific to this iteration. Stored by URI. If the etag was the result of a POST operation and a Location header was provided, then the URI at the Location will be used.ignoreStatus - afterHookif an operation could possibly return an error code that you want to ignore and always continue anyway. Failing status codes are those that are greater than or equal to 400. Normal operation would be to terminate an iteration if there is a failure status code in any before, beforeMain, or main operation.verify2XX - afterHook which fails if an operation's status code was not in 200-299 range. If you don't want a redirect followed, be sure to add the request option followRedirect: false. Note: by default errors are verified (greater than or equal to 400), so this would just be used when you want to make sure it is not a 3xx either.startStepTimer - used in beforeHooks to start a timer for this step named step_OPIDX where OPIDX is the zero based index of the step in the flow. Be sure to call endStepTimer in afterHooks to end it. Provides detailed stats for an individual step in a flow.endStepTimer - used in afterHooks to end a timer previously started with startStepTimer and included in the stats displayed at the end of the run.To create custom beforeHook or afterHook the synchronous function needs to accept an all object and return the same or possibly modified object. To exit the flow, an exception can be thrown which will be caught and emitted. Using these beforeHooks you can modify the next request, and using the afterHooks can verify the response and/or store data for future actions.
One way to keep state for each iteration (without using external variables) is to use the all.iterCtx object which is an empty object provided for each iteration. See examples/hook.js and test/hooks-iter-ctx.mocha.js
So a verification function could be written as such
function verifyData(all) {
if (all.err) return all; // errored so just return and it will error as normal
assert.equal(all.response.statusCode, 200);
assert(all.body, 'foobarbaz'); // if throws, err is caught and counted
return all; // always return all if you want it to continue
}
Postprocess function example:
function postProcess(all) {
// all.iterCtx obj is where you can keep data for an iteration
all.iterCtx.location = all.response.headers.location;
all.iterCtx.body = all.body;
return all; // always return all if you want it to continue
}
Preprocess function example:
function preProcess(all) {
// all.iterCtx object is where you can keep data private for an iteration
// all.requestOptions will be used for the request, modify as needed
all.requestOptions.uri = 'http://localhost:8000' + all.iterCtx.location;
return all; // always return all if you want it to continue
}
The properties available on the all object are:
totalElapsed and main. If startStepTimer and endStepTimer hooks are added to individual steps then additional timers step_OPINDEX will be created for steps that have the hooks.It is important to understand how well your architecture performs and with each change to the system how performance is impacted. The best way to know this is to benchmark your system with each major change.
Benchmarking also lets you:
After attempting to use the variety of load testing clients and modules for benchmarking, none really met all of my desired goals. Most clients are only able to benchmark a single operation, not a whole flow and not one with setup and teardown.
Building your own is certainly an option but it gets tedious to make all the necessary setup and error handling to achieve a simple flow and thus this project was born.
## Tuning OSEach OS may need some tweaking of the configuration to be able to generate or receive a large number of concurrent connections.
### Mac OS XThe Mac OS X can be tweaked using the following parameters. The configuration allowed about 8K concurrent connections for a single process.
sysctl -a | grep maxfiles # display maxfiles and maxfilesperproc defaults 12288 and 10240
sudo sysctl -w kern.maxfiles=25000
sudo sysctl -w kern.maxfilesperproc=24500
sysctl -a | grep somax # display max socket setting, default 128
sudo sysctl -w kern.ipc.somaxconn=20000 # set
ulimit -S -n # display soft max open files, default 256
ulimit -H -n # display hard max open files, default unlimited
ulimit -S -n 20000 # set soft max open files
If you have input or ideas or would like to get involved, you may:
FAQs
bench-rest - benchmark REST (HTTP/HTTPS) API's. Node.js client module for easy load testing / benchmarking REST API' using a simple structure/DSL can create REST flows with setup and teardown and returns (measured) metrics.
The npm package bench-rest receives a total of 432 weekly downloads. As such, bench-rest popularity was classified as not popular.
We found that bench-rest demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.