basho_bench

Overview

Travis-CI ::

Additional documentation on docs.basho.com

Basho Bench is a benchmarking tool created to conduct accurate and repeatable performance tests and stress tests, and produce performance graphs.

Originally developed to benchmark Riak, it exposes a pluggable driver interface and has been extended to serve as a benchmarking tool across a variety of projects.

Basho Bench focuses on two metrics of performance:

• Throughput: number of operations performed in a timeframe, captured in aggregate across all operation types
• Latency: time to complete single operations, captured in quantiles per-operation

Quick Start

You must have Erlang/OTP R16 or later to build and run Basho Bench, and R to generate graphs of your benchmarks. A sane GNU-style build system is also required if you want to use make to build the project.

git clone git://github.com/basho/basho_bench.git
cd basho_bench
make all

This will build an executable script, basho_bench, which you can use to run one of the existing benchmark configurations from the examples/ directory. You will likely have to make some minor directory changes to the configs in order to get the examples running (see, e.g., the source of the bitcask and innostore benchmark config files for direction).

$ ./basho_bench examples/riakc_pb.config
INFO: Est. data size: 95.37 MB
INFO: Using target ip {127,0,0,1} for worker 1
INFO: Starting max worker: <0.55.0>

At the end of the benchmark, results will be available in CSV format in the tests/current/ directory. Now you can generate a graph:

$ make results
priv/summary.r -i tests/current
Loading required package: proto
Loading required package: reshape
Loading required package: plyr
Loading required package: digest
null device 
          1 
$ open tests/current/summary.png

Running as an Application

You can also run basho_bench as an included app rather than an escript. In order to compile and run basho_bench as an included app, you can use make run. You can also include basho_bench as a dependency in another app. basho_bench can be started with basho_bench:start() or from the command-line with erl -s basho_bench. Once you have a shell with basho_bench running, you can run benchmarks with the following:

basho_bench:setup_benchmark([]).
basho_bench:run_benchmark(["/path/to/config"]).

basho_bench:setup_benchmark/1 accepts a proplist of configuration options. These options are the same as the options which are passed to basho_bench via the command line when compiled as an escript.

Troubleshooting Graph Generation

If make results fails with the error /usr/bin/env: Rscript --vanilla: No such file or directory please edit priv/summary.r and replace the first line with the full path to the Rscript binary on your system

If you receive the error message Warning: unable to access index for repository http://lib.stat.cmu.edu/R/CRAN/src/contrib it means the default R repo for installing additional packages is broken, you can change it as follows:

$ R
> chooseCRANmirror()
Selection: 69
quit()
make results

Customizing your Benchmark

Basho Bench has many drivers, each with its own configuration, and a number of key and value generators that you can use to customize your benchmark. It is also straightforward – with less than 200 lines of Erlang code – to create custom drivers that can exercise other systems or perform custom operations. These are covered more in detail in the documentation.

Duration vs Op-Count termination

Benchmarks by default are time-duration limited, meaning you specify a number of minutes for the benchmark to run using the `duration` configuration parameter. Additionally you may specify the `op_counter` configuration parameter, which is set up as an iteration-limited Key Generator, such as the `partitioned_sequential_int`. Once this op_counter has been exhausted for a particular worker, that worker will quit, waiting for other workers to complete before shutting down basho_bench.

Example Configuration: “` {op_counter, {int_to_str, {partitioned_sequential_int, 100}}}. “`

Benchmarking with riak-java-client

The riak-java-client can be used to benchmark a Riak cluster. There is an example configuration in examples/riakc_java.config. You will need the bench_shim project. You will also need to uncomment and edit the following line in basho_bench’s rebar.config, adding your own erlang cookie value:

%% {escript_emu_args, "%%! -name [email protected] -setcookie YOUR_ERLANG_COOKIE\n"}.

Alternative Graph Generation by gnuplot

You can generate graphs using gnuplot.

$ ./priv/gp_throughput.sh

$ ./priv/gp_latencies.sh

By passing -h option to each script, help messages are shown.

Some of options for these scripts are:

• -d TEST_DIR : comma separated list of directories which include test result CSV files
• -t TERMINAL_TYPE : gnuplot terminal type
• -P : just print gnuplot script without drawing graph

For example, you can draw graphs with ASCII characters by the option -t dumb, which is useful in non-graphical environment or quick sharing of result in chat.

Also, you can plot multiple test runs on a single plot by using “-d” switch.

Benchmarking Erlang cluster

A typical benchmark scenario is that Basho Bench spawn Erlang VM and executes the driver inside. However, there is needs to catch performance metrics from an application executed remotely within dedicated environment (e.g. probe performance from live system; benchmark an application inside C or Java node, etc). Bash Bench implements a generic basho_bench_driver_cluster that acts as proxy. It uses Erlang distribution to delegate benchmark responsibility to remote actor, which is randomly selected from configured pool.

Basho Bench do not define how the actors are spawned within SUT. It only defined a communication protocol. The actor is responsible to handle the message:

{pid(), atom(), key(), val()}

• pid() : request originator, actor shall respond to this process
• atom() : id of operation to execute as defined in config file
• key() : materialized key value as defined by key generator function
• val() : materialized value as defined by value generator function

The actor executes the request, measures performance and respond to originator process pid() with one of the message {ok, microsecond()} or {error, reason()}

See cluster.config example for details. Use following command to spawn benchmark

./basho_bench -C nocookie -N [email protected] -J [email protected] examples/cluster.config

Contributing

We encourage contributions to Basho Bench from the community.

1. Fork the basho_bench repository on Github.
2. Clone your fork or add the remote if you already have a clone of the repository.

   git clone [email protected]:yourusername/basho_bench.git
   # or
   git remote add mine [email protected]:yourusername/basho_bench.git
       

3. Create a topic branch for your change.

   git checkout -b some-topic-branch
       

4. Make your change and commit. Use a clear and descriptive commit message, spanning multiple lines if detailed explanation is needed.
5. Push to your fork of the repository and then send a pull-request through Github.

   git push mine some-topic-branch
       

6. A Basho engineer or community maintainer will review your patch and merge it into the main repository or send you feedback.