Version 2.3.1
Simulating workloads with wtperf

The WiredTiger distribution includes a tool that can be used to simulate workloads in WiredTiger, in the directory bench/wtperf.

The wtperf utility generally has two phases, the populate phase which creates a database and then populates an object in that database, and a workload phase, that does some set of operations on the object.

For example, the following configuration uses a single thread to populate a file object with 500,000 records in a 500MB cache. The workload phase consists of 8 threads running for two minutes, all reading from the file.

conn_config="cache_size=500MB"
table_config="type=file"
icount=500000
run_time=120
populate_threads=1
threads=((count=8,reads=1))

In most cases, where the workload is the only interesting phase, the populate phase can be performed once and the workload phase run repeatedly (for more information, see the wtperf create configuration variable).

The conn_config configuration supports setting any WiredTiger connection configuration value. This is commonly used to configure statistics with regular reports, to obtain more information from the run:

conn_config="cache_size=20G,statistics=(fast,clear),statistics_log=(wait=600)"
report_interval=5

Note quoting must be used when passing values to Wiredtiger configuration, as opposed to configuring the wtperf utility itself.

The table_config configuration supports setting any WiredTiger object creation configuration value, for example, the above test can be converted to using an LSM store instead of a B+tree store, with additional LSM configuration, by changing conn_config to:

table_config="lsm=(chunk_size=5MB),type=lsm,os_cache_dirty_max=16MB"

More complex workloads can be configured by creating more threads doing inserts and updates as well as reads. For example, to configure two inserting threads two threads doing a mixture of inserts, reads and updates:

threads=((count=2,inserts=1),(count=2,inserts=1,reads=1,updates=1))

Example wtperf configuration files can be found in the bench/wtperf/runners/ directory.

There are also a number of command line arguments that can be passed to wtperf:

-C config
Specify configuration strings for the wiredtiger_open function. This argument is additive to the conn_config parameter in the configuration file.
-h directory
Specify a database home directory. The default is ./WT_TEST.
-m monitor_directory
Specify a directory for all monitoring related files. The default is the database home directory.
-O config_file
Specify the configuration file to run.
-o config
Specify configuration strings for the wtperf program. This argument will override settings in the configuration file.
-T config
Specify configuration strings for the WT_SESSION::create function. This argument is additive to the table_config parameter in the configuration file.

Monitoring wtperf performance

In addition to testing a particular configuration, wtperf can monitor performance and operation latency times. Monitoring can be enabled using the sample_interval configuration setting. For example to record information every 10 seconds, add the following to the wtperf configuration file:

sample_interval=10

Enabling monitoring causes wtperf to create a file monitor in the database home directory, or another directory as specified in the -m option to wtperf.

A visualization tool to see the performance over the course of the wtperf run can be found in tools/wtperf_stats.py.

The following example shows how to run the large-lsm.wtperf configuration to a subdirectory of build_posix called WTPERF_RUN with monitoring enabled, and then generate a graph. This example assumes you have all the necessary tools already installed to build WiredTiger, Python and python-nvd3.

cd $WIREDTIGER_SOURCE
./configure && make
mkdir WTPERF_RUN && ./bench/wtperf/wtperf -h WTPERF_RUN -O ./bench/wtperf/runners/large-lsm.wtperf
cd WTPERF_RUN; python ../tools/wtperf_stats.py monitor

The python tool creates a file named wtperf_stats.html in the current working directory. You can open the generated HTML document in your browser and see the generated statistics. The keys in the graph are clickable, including the graph included on this page. Double clicking on one of the keys will show only that item. Single clicking will enable or disable a particular item.

The script as a few optional arguments. For example, -o file or –output file to redirect the HTML output to another filename, and –abstime to display time on the X-axis in absolute time.

For example, the file will have content like this:

1,00002,0710.0020.0040.0060.0080.00100.00120.00140.00160.000.00175.260.00100.00200.00300.00400.00500.00600.000.00673.32insert average latency(ms)insert maximum latency(ms)insert min latency(ms)insert ops per second (thousands) (right axis)read average latency(ms)read maximum latency(ms)read minimum latency(ms)read ops per second (thousands) (right axis)

Wtperf configuration options

The following is a list of the currently available wtperf configuration options:

async_threads (unsigned int, default=0)
number of async worker threads
checkpoint_interval (unsigned int, default=120)
checkpoint every interval seconds during the workload phase.
checkpoint_stress_rate (unsigned int, default=0)
checkpoint every rate operations during the populate phase in the populate thread(s), 0 to disable
checkpoint_threads (unsigned int, default=0)
number of checkpoint threads
conn_config (string, default=create)
connection configuration string
compact (boolean, default=false)
post-populate compact for LSM merging activity
compression (string, default=none)
compression extension. Allowed configuration values are: 'none', 'bzip', 'snappy', 'zlib'
create (boolean, default=true)
do population phase; false to use existing database
database_count (unsigned int, default=1)
number of WiredTiger databases to use. Each database will execute the workload using a separate home directory and complete set of worker threads
icount (unsigned int, default=5000)
number of records to initially populate. If multiple tables are configured, each table has this many items inserted.
insert_rmw (boolean, default=false)
execute a read prior to each insert in workload phase
key_sz (unsigned int, default=20)
key size
min_throughput (unsigned int, default=0)
abort if any throughput measured is less than this amount. Requires sample_interval to be configured
max_latency (unsigned int, default=0)
abort if any latency measured exceeds this number of milliseconds.Requires sample_interval to be configured
pareto (boolean, default=false)
use pareto 80/20 distribution for random numbers
populate_ops_per_txn (unsigned int, default=0)
number of operations to group into each transaction in the populate phase, zero for auto-commit
populate_threads (unsigned int, default=1)
number of populate threads, 1 for bulk load
random_range (unsigned int, default=0)
if non zero choose a value from within this range as the key for insert operations
random_value (boolean, default=false)
generate random content for the value
report_interval (unsigned int, default=2)
output throughput information every interval seconds, 0 to disable
run_ops (unsigned int, default=0)
total read, insert and update workload operations
run_time (unsigned int, default=0)
total workload seconds
sample_interval (unsigned int, default=0)
performance logging every interval seconds, 0 to disable
sample_rate (unsigned int, default=50)
how often the latency of operations is measured. One for every operation,two for every second operation, three for every third operation etc.
sess_config (string, default=)
session configuration string
table_config (string, default=key_format=S,value_format=S,type=lsm,exclusive=true,allocation_size=4kb,internal_page_max=64kb,leaf_page_max=4kb,split_pct=100)
table configuration string
table_count (unsigned int, default=1)
number of tables to run operations over. Keys are divided evenly over the tables. Default 1, maximum 99.
threads (string, default=)
workload configuration: each 'count' entry is the total number of threads, and the 'insert', 'read' and 'update' entries are the ratios of insert, read and update operations done by each worker thread; multiple workload configurations may be specified; for example, a more complex threads configuration might be 'threads=((count=2,reads=1)(count=8,reads=1,inserts=2,updates=1))' which would create 2 threads doing nothing but reads and 8 threads each doing 50% inserts and 25% reads and updates. Allowed configuration values are 'count', 'reads', 'inserts', 'updates'
transaction_config (string, default=)
transaction configuration string, relevant when populate_opts_per_txn is nonzero
table_name (string, default=test)
table name
value_sz (unsigned int, default=100)
value size
verbose (unsigned int, default=1)
verbosity
warmup (unsigned int, default=0)
How long to run the workload phase before starting measurements