Table of Contents

• sysbench
  • Features
• Installing from Binary Packages
  • Linux
  • macOS
  • Windows
• Building and Installing From Source
  • Build Requirements
    • Windows
    • Debian/Ubuntu
    • RHEL/CentOS
    • Fedora
    • macOS
  • Build and Install
• Usage
  • General Syntax
  • General Command Line Options
  • Random Numbers Options
• Versioning

sysbench is a scriptable multi-threaded benchmark tool based on LuaJIT. It is most frequently used for database benchmarks, but can also be used to create arbitrarily complex workloads that do not involve a database server.

sysbench comes with the following bundled benchmarks:

• oltp_*.lua: a collection of OLTP-like database benchmarks
• fileio: a filesystem-level benchmark
• cpu: a simple CPU benchmark
• memory: a memory access benchmark
• threads: a thread-based scheduler benchmark
• mutex: a POSIX mutex benchmark

• extensive statistics about rate and latency is available, including latency percentiles and histograms;
• low overhead even with thousands of concurrent threads. sysbench is capable of generating and tracking hundreds of millions of events per second;
• new benchmarks can be easily created by implementing pre-defined hooks in user-provided Lua scripts;
• can be used as a general-purpose Lua interpreter as well, simply replace #!/usr/bin/lua with #!/usr/bin/sysbench in your script.

The easiest way to download and install sysbench on Linux is using binary package repositories hosted by packagecloud. The repositories are automatically updated on each sysbench release. Currently x86_64, i386 and aarch64 binaries are available.

Multiple methods to download and install sysbench packages are available and described at https://packagecloud.io/akopytov/sysbench/install.

Quick install instructions:

• Debian/Ubuntu

  curl -s https://packagecloud.io/install/repositories/akopytov/sysbench/script.deb.sh | sudo bash
  sudo apt -y install sysbench

• RHEL/CentOS:

  curl -s https://packagecloud.io/install/repositories/akopytov/sysbench/script.rpm.sh | sudo bash
  sudo yum -y install sysbench

• Fedora:

  curl -s https://packagecloud.io/install/repositories/akopytov/sysbench/script.rpm.sh | sudo bash	
  sudo dnf -y install sysbench

• Arch Linux:

  sudo pacman -Suy sysbench

On macOS, up-to-date sysbench packages are available from Homebrew:

# Add --with-postgresql if you need PostgreSQL support
brew install sysbench

As of sysbench 1.0 support for native Windows builds was dropped. It may be re-introduced in later releases. Currently, the recommended way to obtain sysbench on Windows is using Windows Subsystem for Linux available in Windows 10.

After installing WSL and getting into he bash prompt on Windows following Debian/Ubuntu installation instructions is sufficient. Alternatively, one can use WSL to build and install sysbench from source, or use an older sysbench release to build a native binary.

It is recommended to install sysbench from the official binary packages as described in Installing from Binary Packages. Below are instruction for cases when you want to use sysbench on an architecture for which no binary packages are available.

As of sysbench 1.0 support for native Windows builds was dropped. It may be re-introduced in later versions. Currently, the recommended way to build sysbench on Windows is using Windows Subsystem for Linux available in Windows 10.

After installing WSL and getting into bash prompt on Windows, following Debian/Ubuntu build instructions is sufficient. Alternatively, one can build and use an older 0.5 release on Windows.

    apt -y install make automake libtool pkg-config libaio-dev
    # For MySQL support
    apt -y install libmysqlclient-dev libssl-dev
    # For PostgreSQL support
    apt -y install libpq-dev

    yum -y install make automake libtool pkgconfig libaio-devel
    # For MySQL support, replace with mysql-devel on RHEL/CentOS 5
    yum -y install mariadb-devel openssl-devel
    # For PostgreSQL support
    yum -y install postgresql-devel

    dnf -y install make automake libtool pkgconfig libaio-devel
    # For MySQL support
    dnf -y install mariadb-devel openssl-devel
    # For PostgreSQL support
    dnf -y install postgresql-devel

Assuming you have Xcode (or Xcode Command Line Tools) and Homebrew installed:

    brew install automake libtool openssl pkg-config
    # For MySQL support
    brew install mysql
    # For PostgreSQL support
    brew install postgresql
    # openssl is not linked by Homebrew, this is to avoid "ld: library not found for -lssl"
    export LDFLAGS=-L/usr/local/opt/openssl/lib 

    ./autogen.sh
    # Add --with-pgsql to build with PostgreSQL support
    ./configure
    make -j
    make install

The above will build sysbench with MySQL support by default. If you have MySQL headers and libraries in non-standard locations (and no mysql_config can be found in the PATH), you can specify them explicitly with --with-mysql-includes and --with-mysql-libs options to ./configure.

To compile sysbench without MySQL support, use --without-mysql. If no database drivers are available database-related scripts will not work, but other benchmarks will be functional.

The general command line syntax for sysbench is:

	  sysbench [options]... [testname] [command] 

• testname is an optional name of a built-in test (e.g. fileio, memory, cpu, etc.), or a name of one of the bundled Lua scripts (e.g. oltp_read_only), or a path to a custom Lua script. If no test name is specified on the command line (and thus, there is no command too, as in that case it would be parsed as a testname), or the test name is a dash ("-"), then sysbench expects a Lua script to execute on its standard input.

• command is an optional argument that will be passed by sysbench to the built-in test or script specified with testname. command defines the action that must be performed by the test. The list of available commands depends on a particular test. Some tests also implement their own custom commands.

  Below is a description of typical test commands and their purpose:

  • prepare: performs preparative actions for those tests which need them, e.g. creating the necessary files on disk for the fileio test, or filling the test database for database benchmarks.
  • run: runs the actual test specified with the testname argument. This command is provided by all tests.
  • cleanup: removes temporary data after the test run in those tests which create one.
  • help: displays usage information for the test specified with the testname argument. This includes the full list of commands provided by the test, so it should be used to get the available commands.

• options is a list of zero or more command line options starting with '--'. As with commands, the sysbench testname help command should be used to describe available options provided by a particular test.

  See General command line options for a description of general options provided by sysbench itself.

You can use sysbench --help to display the general command line syntax and options.

The table below lists the supported common options, their descriptions and default values:

Note that numerical values for all size options (like --thread-stack-size in this table) may be specified by appending the corresponding multiplicative suffix (K for kilobytes, M for megabytes, G for gigabytes and T for terabytes).

sysbench provides a number of algorithms to generate random numbers that are distributed according to a given probability distribution. The table below lists options that can be used to control those algorithms.

For transparency and insight into its release cycle, and for striving to maintain backward compatibility, sysbench will be maintained under the Semantic Versioning guidelines as much as possible.

Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)
• New additions without breaking backward compatibility bumps the minor (and resets the patch)
• Bug fixes and misc changes bumps the patch

For more information on SemVer, please visit https://semver.org/.