README.md
1[![Latest Release][release-badge]][release-url]
2[![Build Status][travis-badge]][travis-url]
3[![Debian Packages][deb-badge]][deb-url]
4[![RPM Packages][rpm-badge]][rpm-url]
5[![Coverage Status][coveralls-badge]][coveralls-url]
6[![License][license-badge]][license-url]
7
8<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-generate-toc again -->
9**Table of Contents**
10
11- [sysbench](#sysbench)
12 - [Features](#features)
13- [Installing from Binary Packages](#installing-from-binary-packages)
14 - [Linux](#linux)
15 - [macOS](#macos)
16 - [Windows](#windows)
17- [Building and Installing From Source](#building-and-installing-from-source)
18 - [Build Requirements](#build-requirements)
19 - [Windows](#windows)
20 - [Debian/Ubuntu](#debianubuntu)
21 - [RHEL/CentOS](#rhelcentos)
22 - [Fedora](#fedora)
23 - [macOS](#macos)
24 - [Build and Install](#build-and-install)
25- [Usage](#usage)
26 - [General Syntax](#general-syntax)
27 - [General Command Line Options](#general-command-line-options)
28- [Versioning](#versioning)
29
30<!-- markdown-toc end -->
31
32# sysbench
33
34sysbench is a scriptable multi-threaded benchmark tool based on
35LuaJIT. It is most frequently used for database benchmarks, but can also
36be used to create arbitrarily complex workloads that do not involve a
37database server.
38
39sysbench comes with the following bundled benchmarks:
40
41- `oltp_*.lua`: a collection of OLTP-like database benchmarks
42- `fileio`: a filesystem-level benchmark
43- `cpu`: a simple CPU benchmark
44- `memory`: a memory access benchmark
45- `threads`: a thread-based scheduler benchmark
46- `mutex`: a POSIX mutex benchmark
47
48## Features
49
50- extensive statistics about rate and latency is available, including
51 latency percentiles and histograms;
52- low overhead even with thousands of concurrent threads. sysbench is
53 capable of generating and tracking hundreds of millions of events per
54 second;
55- new benchmarks can be easily created by implementing pre-defined hooks
56 in user-provided Lua scripts;
57- can be used as a general-purpose Lua interpreter as well, simply
58 replace `#!/usr/bin/lua` with `#!/usr/bin/sysbench` in your script.
59
60# Installing from Binary Packages
61
62## Linux
63
64The easiest way to download and install sysbench on Linux is using
65binary package repositories hosted by
66[packagecloud](https://packagecloud.io). The repositories are
67automatically updated on each sysbench release. Currently x86_64, i386
68and aarch64 binaries are available.
69
70Multiple methods to download and install sysbench packages are available and
71described at <https://packagecloud.io/akopytov/sysbench/install>.
72
73Quick install instructions:
74
75- Debian/Ubuntu
76 ``` shell
77 curl -s https://packagecloud.io/install/repositories/akopytov/sysbench/script.deb.sh | sudo bash
78 sudo apt -y install sysbench
79 ```
80
81- RHEL/CentOS:
82 ``` shell
83 curl -s https://packagecloud.io/install/repositories/akopytov/sysbench/script.rpm.sh | sudo bash
84 sudo yum -y install sysbench
85 ```
86
87- Fedora:
88 ``` shell
89 curl -s https://packagecloud.io/install/repositories/akopytov/sysbench/script.rpm.sh | sudo bash
90 sudo dnf -y install sysbench
91 ```
92
93## macOS
94
95On macOS, up-to-date sysbench packages are available from Homebrew:
96```shell
97# Add --with-postgresql if you need PostgreSQL support
98brew install sysbench
99```
100
101## Windows
102As of sysbench 1.0 support for native Windows builds was dropped. It may
103be re-introduced in later releases. Currently, the recommended way to
104obtain sysbench on Windows is
105using
106[Windows Subsystem for Linux available in Windows 10](https://msdn.microsoft.com/en-us/commandline/wsl/about).
107
108After installing WSL and getting into he bash prompt on Windows
109following Debian/Ubuntu installation instructions is
110sufficient. Alternatively, one can use WSL to build and install sysbench
111from source, or use an older sysbench release to build a native binary.
112
113# Building and Installing From Source
114
115It is recommended to install sysbench from the official binary
116packages as described in
117[Installing from Binary Packages](#installing-from-binary-packages). Below
118are instruction for cases when you want to use sysbench on an
119architecture for which no binary packages are available.
120
121## Build Requirements
122
123### Windows
124As of sysbench 1.0 support for native Windows builds was
125dropped. It may be re-introduced in later versions. Currently, the
126recommended way to build sysbench on Windows is using
127[Windows Subsystem for Linux available in Windows 10](https://msdn.microsoft.com/en-us/commandline/wsl/about).
128
129After installing WSL and getting into bash prompt on Windows, following
130Debian/Ubuntu build instructions is sufficient. Alternatively, one can
131build and use an older 0.5 release on Windows.
132
133### Debian/Ubuntu
134``` shell
135 apt -y install make automake libtool pkg-config libaio-dev
136 # For MySQL support
137 apt -y install libmysqlclient-dev libssl-dev
138 # For PostgreSQL support
139 apt -y install libpq-dev
140```
141
142### RHEL/CentOS
143``` shell
144 yum -y install make automake libtool pkgconfig libaio-devel
145 # For MySQL support, replace with mysql-devel on RHEL/CentOS 5
146 yum -y install mariadb-devel openssl-devel
147 # For PostgreSQL support
148 yum -y install postgresql-devel
149```
150
151### Fedora
152``` shell
153 dnf -y install make automake libtool pkgconfig libaio-devel
154 # For MySQL support
155 dnf -y install mariadb-devel openssl-devel
156 # For PostgreSQL support
157 dnf -y install postgresql-devel
158```
159
160### macOS
161
162Assuming you have Xcode (or Xcode Commane Line Tools) and Homebrew installed:
163``` shell
164 brew install automake libtool openssl pkg-config
165 # For MySQL support
166 brew install mysql
167 # For PostgreSQL support
168 brew install postgresql
169 # openssl is not linked by Homebrew, this is to avoid "ld: library not found for -lssl"
170 export LDFLAGS=-L/usr/local/opt/openssl/lib
171```
172
173## Build and Install
174``` shell
175 ./autogen.sh
176 # Add --with-pgsql to build with PostgreSQL support
177 ./configure
178 make -j
179 make install
180```
181
182The above will build sysbench with MySQL support by default. If you have
183MySQL headers and libraries in non-standard locations (and no
184`mysql_config` can be found in the `PATH`), you can specify them
185explicitly with `--with-mysql-includes` and `--with-mysql-libs` options
186to `./configure`.
187
188To compile sysbench without MySQL support, use `--without-mysql`. If no
189database drivers are available database-related scripts will not work,
190but other benchmarks will be functional.
191
192See [README-Oracle.md](README-Oracle.md) for instructions on building
193with Oracle client libraries.
194
195# Usage
196
197## General Syntax
198
199The general command line syntax for sysbench is:
200
201 sysbench [options]... [testname] [command]
202
203- *testname* is an optional name of a built-in test (e.g. `fileio`,
204 `memory`, `cpu`, etc.), or a name of one of the bundled Lua scripts
205 (e.g. `oltp_read_only`), or a *path* to a custom Lua script. If no
206 test name is specified on the command line (and thus, there is no
207 *command* too, as in that case it would be parsed as a *testname*), or
208 the test name is a dash ("`-`"), then sysbench expects a Lua script to
209 execute on its standard input.
210
211- *command* is an optional argument that will be passed by sysbench to
212 the built-in test or script specified with *testname*. *command*
213 defines the *action* that must be performed by the test. The list of
214 available commands depends on a particular test. Some tests also
215 implement their own custom commands.
216
217 Below is a description of typical test commands and their purpose:
218
219 + `prepare`: performs preparative actions for those tests which need
220 them, e.g. creating the necessary files on disk for the `fileio`
221 test, or filling the test database for database benchmarks.
222 + `run`: runs the actual test specified with the *testname*
223 argument. This command is provided by all tests.
224 + `cleanup`: removes temporary data after the test run in those
225 tests which create one.
226 + `help`: displays usage information for the test specified with the
227 *testname* argument. This includes the full list of commands
228 provided by the test, so it should be used to get the available
229 commands.
230
231- *options* is a list of zero or more command line options starting with
232 `'--'`. As with commands, the `sysbench testname help` command
233 should be used to describe available options provided by a
234 particular test.
235
236 See [General command line options](README.md#general-command-line-options)
237 for a description of general options provided by sysbench itself.
238
239
240You can use `sysbench --help` to display the general command line syntax
241and options.
242
243## General Command Line Options
244
245The table below lists the supported common options, their descriptions and default values:
246
247*Option* | *Description* | *Default value*
248----------------------|---------------|----------------
249| `--threads` | The total number of worker threads to create | 1 |
250| `--events` | Limit for total number of requests. 0 (the default) means no limit | 0 |
251| `--time` | Limit for total execution time in seconds. 0 means no limit | 10 |
252| `--rate` | Average transactions rate. The number specifies how many events (transactions) per seconds should be executed by all threads on average. 0 (default) means unlimited rate, i.e. events are executed as fast as possible | 0 |
253| `--thread-stack-size` | Size of stack for each thread | 32K |
254| `--report-interval` | Periodically report intermediate statistics with a specified interval in seconds. Note that statistics produced by this option is per-interval rather than cumulative. 0 disables intermediate reports | 0 |
255| `--debug` | Print more debug info | off |
256| `--validate` | Perform validation of test results where possible | off |
257| `--help` | Print help on general syntax or on a test mode specified with --test, and exit | off |
258| `--verbosity` | Verbosity level (0 - only critical messages, 5 - debug) | 4 |
259| `--percentile` | sysbench measures execution times for all processed requests to display statistical information like minimal, average and maximum execution time. For most benchmarks it is also useful to know a request execution time value matching some percentile (e.g. 95% percentile means we should drop 5% of the most long requests and choose the maximal value from the remaining ones). This option allows to specify a percentile rank of query execution times to count | 95 |
260
261Note 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).
262
263# Versioning
264
265For 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.
266
267Releases will be numbered with the following format:
268
269`<major>.<minor>.<patch>`
270
271And constructed with the following guidelines:
272
273* Breaking backward compatibility bumps the major (and resets the minor and patch)
274* New additions without breaking backward compatibility bumps the minor (and resets the patch)
275* Bug fixes and misc changes bumps the patch
276
277For more information on SemVer, please visit [http://semver.org/](http://semver.org/).
278
279[coveralls-badge]: https://coveralls.io/repos/github/akopytov/sysbench/badge.svg?branch=1.0
280[coveralls-url]: https://coveralls.io/github/akopytov/sysbench?branch=1.0
281[travis-badge]: https://travis-ci.org/akopytov/sysbench.svg?branch=1.0
282[travis-url]: https://travis-ci.org/akopytov/sysbench?branch=1.0
283[license-badge]: https://img.shields.io/badge/license-GPLv2-blue.svg
284[license-url]: COPYING
285[release-badge]: https://img.shields.io/github/release/akopytov/sysbench.svg
286[release-url]: https://github.com/akopytov/sysbench/releases/latest
287[deb-badge]: https://img.shields.io/badge/Packages-Debian-red.svg?style=flat
288[deb-url]: https://packagecloud.io/akopytov/sysbench?filter=debs
289[rpm-badge]: https://img.shields.io/badge/Packages-RPM-blue.svg?style=flat
290[rpm-url]: https://packagecloud.io/akopytov/sysbench?filter=rpms
291
