← Back to branch summary

~percona-dev/percona-xtradb-cluster/galera-24.2.x

« back to all changes in this revision

Viewing changes to tests/test_sysbench/doc/manual.xml

  • Committer: Raghavendra D Prabhu
  • Date: 2013-11-08 06:51:43 UTC
  • mfrom: (95.3.11 2.x)
  • Revision ID: raghavendra.prabhu@percona.com-20131108065143-o7o4yyy064112lzf
Merge galera upto revno 164

Show diffs side-by-side

added added

removed removed

Lines of Context:
tests/test_sysbench/doc/manual.xml
1
 
<?xml version="1.0" encoding='ISO-8859-1'?>
2
 
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
3
 
 
4
 
<book id="sysbench-guide">
5
 
  <bookinfo>
6
 
    <title>SysBench manual</title>
7
 
    
8
 
    <authorgroup>
9
 
      <author>
10
 
        <firstname>Alexey</firstname>
11
 
        <surname>Kopytov</surname>
12
 
        <affiliation>
13
 
          <address><email>kaamos@users.sourceforge.net</email></address>
14
 
        </affiliation>
15
 
      </author>
16
 
    </authorgroup>
17
 
    
18
 
    <copyright>
19
 
      <year>2004-2006</year>
20
 
      <holder>MySQL AB</holder>
21
 
    </copyright></bookinfo>
22
 
  
23
 
  <toc></toc>
24
 
 
25
 
  <chapter id="introduction">
26
 
    <title>Introduction</title>
27
 
 
28
 
    <para>
29
 
      SysBench is a modular, cross-platform and multi-threaded benchmark tool for evaluating OS parameters 
30
 
      that are important for a system running a database under intensive load. 
31
 
    </para>
32
 
    <para>
33
 
      The idea of this benchmark suite is to quickly get an impression about system performance without setting up 
34
 
      complex database benchmarks or even without installing a database at all. 
35
 
    </para>
36
 
    <section id="features">
37
 
      <title>Features of SysBench</title>
38
 
      <para>
39
 
        Current features allow to test the following system parameters: 
40
 
        <itemizedlist>
41
 
          <listitem><para>file I/O performance</para></listitem>
42
 
          <listitem><para>scheduler performance</para></listitem>
43
 
          <listitem><para>memory allocation and transfer speed</para></listitem>
44
 
          <listitem><para>POSIX threads implementation performance</para></listitem>
45
 
          <listitem><para>database server performance</para></listitem>
46
 
        </itemizedlist> 
47
 
      </para>
48
 
    </section>
49
 
 
50
 
    <section id="design">
51
 
      <title>Design</title>
52
 
      <para>
53
 
        The design is very simple. SysBench runs a specified number of threads and they all execute requests in parallel.
54
 
        The actual workload produced by requests depends on the specified test mode. You can limit either the total number of
55
 
        requests or the total time for the benchmark, or both.
56
 
      </para>
57
 
      <para>
58
 
        Available test modes are implemented by compiled-in modules, and SysBench was designed to make adding new test modes
59
 
        an easy task. Each test mode may have additional (or workload-specific) options.
60
 
      </para>
61
 
    </section>
62
 
 
63
 
    <section id="links">
64
 
      <title>Links</title>
65
 
 
66
 
      <variablelist>
67
 
        <varlistentry>
68
 
          <term>Home page</term>
69
 
          <listitem><para>
70
 
              <ulink url="http://sysbench.sf.net/">http://sysbench.sf.net/</ulink>.
71
 
            </para></listitem>
72
 
        </varlistentry>
73
 
        <varlistentry>
74
 
          <term>Download</term>
75
 
          <listitem><para>
76
 
              <ulink url="http://sf.net/projects/sysbench/">http://sf.net/projects/sysbench/</ulink>.
77
 
            </para></listitem>
78
 
        </varlistentry>
79
 
        <varlistentry>
80
 
          <term>Mailing lists</term>
81
 
          <listitem><para>
82
 
              <ulink url="http://sourceforge.net/mail/?group_id=102348">sysbench-general</ulink>
83
 
            </para></listitem>
84
 
        </varlistentry>
85
 
        <varlistentry>
86
 
          <term>Web forums</term>
87
 
          <listitem><para>
88
 
              <itemizedlist>
89
 
                <listitem>
90
 
                  <ulink url="http://sourceforge.net/forum/forum.php?forum_id=353125">Developers</ulink>
91
 
                </listitem>
92
 
                <listitem>
93
 
                  <ulink url="http://sourceforge.net/forum/forum.php?forum_id=353124">Help</ulink>
94
 
                </listitem>
95
 
                <listitem>
96
 
                  <ulink url="http://sourceforge.net/forum/forum.php?forum_id=353123">Open discussion</ulink>
97
 
                </listitem>
98
 
              </itemizedlist> 
99
 
            </para></listitem>
100
 
        </varlistentry>
101
 
        <varlistentry>
102
 
          <term>Bug tracking system</term>
103
 
          <listitem><para>
104
 
              <itemizedlist>
105
 
                <listitem>
106
 
                  <ulink url="http://sourceforge.net/tracker/?atid=631676&amp;group_id=102348&amp;func=browse">
107
 
                    Bug reports
108
 
                  </ulink>
109
 
                </listitem>
110
 
                <listitem>
111
 
                  <ulink url="http://sourceforge.net/tracker/?atid=631679&amp;group_id=102348&amp;func=browse">
112
 
                    Feature requests
113
 
                  </ulink>
114
 
                </listitem>
115
 
              </itemizedlist> 
116
 
            </para></listitem>
117
 
        </varlistentry>
118
 
      </variablelist>
119
 
 
120
 
    </section>
121
 
 
122
 
    <section id="install">
123
 
      <title>Installation</title>
124
 
 
125
 
      <para>
126
 
        The following standart procedure will be sufficient to build SysBench in most cases:
127
 
        <synopsis>
128
 
          <command>./configure</command>
129
 
          <command>make</command>
130
 
          <command>make install</command>
131
 
        </synopsis>
132
 
        The above procedure will try to compile SysBench with MySQL support by default. If you have MySQL headers and libraries
133
 
        in non-standard locations (and no <command>mysql_config</command> can be found in the <constant>PATH</constant>
134
 
        environmental variable), then you can specify them explicitly with <option>--with-mysql-includes</option> and
135
 
        <option>--with-mysql-libs</option> options to <command>./configure</command>. 
136
 
      </para>
137
 
      <para>
138
 
        To compile SysBench without MySQL support, use <option>--without-mysql</option>. In this case all database-related
139
 
        test modes will be unavailable.
140
 
      </para>
141
 
      <para>
142
 
        If you are running on a 64-bit platform, make sure to build a 64-bit binary by passing the proper target platform and compiler options to <command>configure</command> script. You can also consult the INSTALL file for generic installation instructions.
143
 
      </para>
144
 
    </section>
145
 
 
146
 
  </chapter>
147
 
 
148
 
  <chapter id="usage"> 
149
 
    <title>Usage</title>
150
 
    <section id="general_syntax">
151
 
      <title>General syntax</title>
152
 
 
153
 
      <para>
154
 
        The general syntax for SysBench is as follows:
155
 
        <screen>
156
 
          sysbench <emphasis>[common-options]</emphasis> --test=<emphasis>name</emphasis> <emphasis>[test-options]</emphasis> <emphasis>command</emphasis>
157
 
        </screen>
158
 
        See <xref linkend="common_options"/> for a description of common options and documentation for particular test mode for a list
159
 
        of test-specific options.
160
 
      </para>
161
 
 
162
 
      <para>
163
 
        Below is a brief description of available commands and their purpose:
164
 
        <variablelist>
165
 
          <varlistentry>
166
 
            <term><command>prepare</command></term>
167
 
            <listitem>Performs preparative actions for those tests which need them, e.g. creating the necessary 
168
 
              files on disk for the <option>fileio</option> test, or filling the test database for the
169
 
              <option>oltp</option> test.
170
 
            </listitem>
171
 
          </varlistentry>
172
 
          <varlistentry>
173
 
            <term><command>run</command></term>
174
 
            <listitem>Runs the actual test specified with the <option>--test=<emphasis>name</emphasis></option> option.
175
 
            </listitem>
176
 
          </varlistentry>
177
 
          <varlistentry>
178
 
            <term><command>cleanup</command></term>
179
 
            <listitem>Removes temporary data after the test run in those tests which create one.
180
 
            </listitem>
181
 
          </varlistentry>
182
 
          <varlistentry>
183
 
            <term><command>help</command></term>
184
 
            <listitem>Displays usage information for a test specified with the 
185
 
              <option>--test=<emphasis>name</emphasis></option> option.
186
 
            </listitem>
187
 
          </varlistentry>
188
 
        </variablelist>
189
 
      </para>
190
 
      <para>
191
 
        Also you can use <command>sysbench help</command> to display the brief usage summary and the list of available test modes.
192
 
      </para>
193
 
    </section>
194
 
 
195
 
    <section id="common_options">
196
 
      <title>Common command line options</title>
197
 
      <para>
198
 
        The table below lists the supported common options, their descriptions and default values:
199
 
      </para>
200
 
      <informaltable frame="all">
201
 
        <tgroup cols='3'> 
202
 
          <tbody>
203
 
            <row><entry><emphasis>Option</emphasis></entry><entry><emphasis>Description</emphasis></entry><entry><emphasis>Default value</emphasis></entry></row>
204
 
            <row><entry><option>--num-threads</option></entry><entry>The total number of worker threads to create</entry><entry>1</entry></row>
205
 
            <row><entry><option>--max-requests</option></entry><entry>Limit for total number of requests. 0 means unlimited</entry><entry>10000</entry></row>
206
 
            <row><entry><option>--max-time</option></entry><entry>Limit for total execution time in seconds. 0 (default) means unlimited</entry><entry>0</entry></row>
207
 
            <row><entry><option>--thread-stack-size</option></entry><entry>Size of stack for each thread</entry><entry>32K</entry></row>
208
 
            <row><entry><option>--init-rnd</option></entry><entry>Specifies if random numbers generator should be initialized from timer before the test start</entry><entry>off</entry></row>
209
 
            <row><entry><option>--test</option></entry><entry>Name of the test mode to run</entry><entry><emphasis>Required</emphasis></entry></row>
210
 
            <row><entry><option>--debug</option></entry><entry>Print more debug info</entry><entry>off</entry></row>
211
 
            <row><entry><option>--validate</option></entry><entry>Perform
212
 
                validation of test results where possible </entry><entry>off</entry></row>
213
 
            <row><entry><option>--help</option></entry><entry>Print help on general syntax or on a test mode specified with --test, and exit</entry><entry>off</entry></row>
214
 
            <row><entry><option>--verbosity</option></entry><entry>Verbosity level (0 - only critical messages, 5 - debug)</entry><entry>4</entry></row>
215
 
            <row><entry><option>--percentile</option></entry>
216
 
              <entry>
217
 
                <para>
218
 
                  SysBench measures execution times for all processed
219
 
                  requests to display statistical information like minimal, average and
220
 
                  maximum execution time. For most benchmarks it is also useful to know
221
 
                  a request execution time value matching some percentile (e.g. 95%
222
 
                  percentile means we should drop 5% of the most long requests and
223
 
                  choose the maximal value from the remaining ones). 
224
 
                </para>
225
 
                <para>
226
 
                  This option allows to specify a percentile rank of query
227
 
                  execution times to count
228
 
                </para>
229
 
              </entry>
230
 
              <entry>95</entry></row>
231
 
            <row><entry><option>--batch</option></entry><entry>Dump current results periodically (see <xref linkend="batch_mode"/>)</entry><entry>off</entry></row>
232
 
            <row><entry><option>--batch-delay</option></entry><entry>Delay between batch dumps in secods (see <xref linkend="batch_mode"/>)</entry><entry>300</entry></row>
233
 
            <row><entry><option>--validate</option></entry><entry>Perform validation of test results where possible</entry><entry>off</entry></row>
234
 
          </tbody>
235
 
        </tgroup>
236
 
      </informaltable>
237
 
      <para>
238
 
        Note that numerical values for all <emphasis>size</emphasis> options
239
 
        (like <option>--thread-stack-size</option> in this table) may be
240
 
        specified by appending the corresponding multiplicative suffix (K for
241
 
        kilobytes, M for megabytes, G for gigabytes and T for terabytes).
242
 
      </para>
243
 
    </section>
244
 
    <section id="batch_mode">
245
 
      <title>Batch mode</title>
246
 
      In some cases it is useful to have not only the final benchmarks
247
 
      statistics, but also periodical dumps of current stats to see how they
248
 
      change over the test run. For this purpose SysBench has a batch
249
 
      execution mode which is turned on by the <option>--batch</option>
250
 
      option. You may specify the delay in seconds between the consequent dumps with
251
 
      the <option>--batch-delay</option> option. Example:
252
 
      <screen>
253
 
        sysbench --batch --batch-delay=5 --test=threads run
254
 
      </screen>
255
 
      This will run SysBench in a threads test mode, with the current values
256
 
      of minimum, average, maximum and percentile for request execution
257
 
      times printed every 5 seconds.
258
 
    </section>
259
 
 
260
 
 
261
 
    <section id="test_modes">
262
 
      <title>Test modes</title>
263
 
      This section gives a detailed description for each test mode available
264
 
      in SysBench.
265
 
 
266
 
      <section id="cpu_mode">
267
 
        <title><option>cpu</option></title>
268
 
      </section>
269
 
      <para>
270
 
        The <option>cpu</option> is one of the most simple benchmarks in
271
 
        SysBench. In this mode each request consists in calculation of prime numbers up to a value
272
 
        specified by the <option>--cpu-max-primes</option> option. All calculations are performed using 64-bit integers.
273
 
      </para>
274
 
      <para>
275
 
        Each thread executes the requests concurrently until either the total number of requests or the total execution
276
 
        time exceed the limits specified with the common command line options.
277
 
      </para>
278
 
      <para>
279
 
        Example:
280
 
        <screen>
281
 
          sysbench --test=cpu --cpu-max-prime=20000 run
282
 
        </screen>
283
 
      </para>
284
 
 
285
 
      <section id="threads_mode">
286
 
        <title><option>threads</option></title>
287
 
      </section>
288
 
      <para>
289
 
        This test mode was written to benchmark scheduler performance, more specifically the cases
290
 
        when a scheduler has a large number of threads competing for some set of mutexes.
291
 
      </para>
292
 
      <para>
293
 
        SysBench creates a specified number of threads and a specified number of mutexes. Then each thread
294
 
        starts running the requests consisting of locking the mutex, yielding the CPU, so the thread is
295
 
        placed in the run queue by the scheduler, then unlocking the mutex when the thread is rescheduled back
296
 
        to execution. For each request, the above actions are run several times in a loop, so the more iterations
297
 
        is performed, the more concurrency is placed on each mutex.
298
 
      </para>
299
 
      <para>
300
 
        The following options are available in this test mode:
301
 
        <informaltable frame="all">
302
 
          <tgroup cols='3'> 
303
 
            <tbody>
304
 
              <row><entry><emphasis>Option</emphasis></entry><entry><emphasis>Description</emphasis></entry><entry><emphasis>Default value</emphasis></entry></row>
305
 
              <row><entry><option>--thread-yields</option></entry><entry>Number of <emphasis>lock/yield/unlock</emphasis> loops to execute per each request</entry><entry>1000</entry></row>
306
 
              <row><entry><option>--thread-locks</option></entry><entry>Number of mutexes to create</entry><entry>8</entry></row>
307
 
            </tbody>
308
 
          </tgroup>
309
 
        </informaltable>
310
 
      </para>
311
 
      <para>
312
 
        Example:
313
 
        <screen>
314
 
          sysbench --num-threads=64 --test=threads --thread-yields=100 --thread-locks=2 run
315
 
        </screen>
316
 
      </para>
317
 
 
318
 
 
319
 
      <section id="mutex_mode">
320
 
        <title><option>mutex</option></title>
321
 
      </section>
322
 
      <para>
323
 
        This test mode was written to emulate a situation when all threads run concurrently most of the time, 
324
 
        acquiring the mutex lock only for a short period of time (incrementing a global variable). So the purpose
325
 
        of this benchmarks is to examine the performance of mutex implementation.
326
 
      </para>
327
 
      <para>
328
 
        The following options are available in this test mode:
329
 
        <informaltable frame="all">
330
 
          <tgroup cols='3'> 
331
 
            <tbody>
332
 
              <row><entry><emphasis>Option</emphasis></entry><entry><emphasis>Description</emphasis></entry><entry><emphasis>Default value</emphasis></entry></row>
333
 
              <row><entry><option>--mutex-num</option></entry><entry>Number of mutexes. The actual mutex to lock is chosen randomly before each lock</entry><entry>4096</entry></row>
334
 
              <row><entry><option>--mutex-locks</option></entry><entry>Number of mutex locks to acquire per each request</entry><entry>50000</entry></row>
335
 
              <row><entry><option>--mutex-loops</option></entry><entry>Number of iterations for an empty loop to perform before acquiring the lock</entry><entry>10000</entry></row>
336
 
            </tbody>
337
 
          </tgroup>
338
 
        </informaltable>
339
 
      </para>
340
 
 
341
 
 
342
 
      <section id="memory_mode">
343
 
        <title><option>memory</option></title>
344
 
        <para>
345
 
          This test mode can be used to benchmark sequential memory reads or writes. Depending on command line
346
 
          options each thread can access either a global or a local block for all memory operations.
347
 
        </para>
348
 
        <para>
349
 
          The following options are available in this test mode:
350
 
          <informaltable frame="all">
351
 
            <tgroup cols='3'> 
352
 
              <tbody>
353
 
                <row><entry><emphasis>Option</emphasis></entry><entry><emphasis>Description</emphasis></entry><entry><emphasis>Default value</emphasis></entry></row>
354
 
                <row><entry><option>--memory-block-size</option></entry><entry>Size of memory block to use</entry><entry>1K</entry></row>
355
 
                <row><entry><option>--memory-scope</option></entry><entry>
356
 
                    Possible values: <option>global</option>, <option>local</option>. Specifies whether each thread will
357
 
                    use a globally allocated memory block, or a local one.
358
 
                  </entry><entry>global</entry></row>
359
 
                <row><entry><option>--memory-total-size</option></entry><entry>Total size of data to transfer</entry><entry>100G</entry></row>
360
 
                <row><entry><option>--memory-oper</option></entry><entry>
361
 
                    Type of memory operations. Possible values: <option>read</option>, <option>write</option>.
362
 
                  </entry><entry>100G</entry></row>
363
 
              </tbody>
364
 
            </tgroup>
365
 
          </informaltable>
366
 
        </para>
367
 
      </section>
368
 
 
369
 
      <section id="fileio_mode">
370
 
        <title><option>fileio</option></title>
371
 
 
372
 
        <para>
373
 
          This test mode can be used to produce various kinds of file I/O workloads. At the <option>prepare</option>
374
 
          stage SysBench creates a specified number of files with a specified total size, then at the <option>run</option>
375
 
          stage, each thread performs specified I/O operations on this set of files.
376
 
        </para>
377
 
 
378
 
        <para>
379
 
          When the global <option>--validate</option> option is used with the <option>fileio</option> test mode, SysBench
380
 
          performs checksums validation on all data read from the disk. On each write operation the block is filled with random values,
381
 
          then the checksum is calculated
382
 
          and stored in the block along with the offset of this block within a file. On each read operation the block is validated
383
 
          by comparing the stored offset with the real offset, and the stored checksum with the real calculated checksum.
384
 
        </para>
385
 
 
386
 
        <para>
387
 
          The following I/O operations are supported:
388
 
 
389
 
          <variablelist>
390
 
            <varlistentry>
391
 
              <term><command>seqwr</command></term>
392
 
              <listitem>sequential write
393
 
              </listitem>
394
 
            </varlistentry>
395
 
            <varlistentry>
396
 
              <term><command>seqrewr</command></term>
397
 
              <listitem>sequential rewrite
398
 
              </listitem>
399
 
            </varlistentry>
400
 
            <varlistentry>
401
 
              <term><command>seqrd</command></term>
402
 
              <listitem>sequential read
403
 
              </listitem>
404
 
            </varlistentry>
405
 
            <varlistentry>
406
 
              <term><command>rndrd</command></term>
407
 
              <listitem>random read
408
 
              </listitem>
409
 
            </varlistentry>
410
 
            <varlistentry>
411
 
              <term><command>rndwr</command></term>
412
 
              <listitem>random write
413
 
              </listitem>
414
 
            </varlistentry>
415
 
            <varlistentry>
416
 
              <term><command>rndrw</command></term>
417
 
              <listitem>combined random read/write
418
 
              </listitem>
419
 
            </varlistentry>
420
 
          </variablelist>
421
 
        </para>
422
 
 
423
 
        <para>
424
 
          Also, the following file access modes can be specified, if the underlying platform supports them:
425
 
          <variablelist>
426
 
            <varlistentry>
427
 
              <term>Asynchronous I/O mode</term>
428
 
              <listitem>
429
 
                At the moment only Linux AIO implementation is supported. When running in asynchronous mode,
430
 
                SysBench queues a specified number of I/O requests using Linux AIO API, then waits for 
431
 
                at least one of submitted requests to complete. After that a new series of I/O requests
432
 
                is submitted. 
433
 
              </listitem>
434
 
            </varlistentry>
435
 
            <varlistentry>
436
 
              <term>Slow <option>mmap()</option> mode</term>
437
 
              <listitem>In this mode SysBench will use <option>mmap</option>'ed I/O. However, a separate
438
 
                <option>mmap</option> will be used for each I/O request due to the limitation of 32-bit
439
 
                architectures (we cannot <option>mmap()</option> the whole file, as its size migth possibly
440
 
                exceed the maximum of 2 GB of the process address space).
441
 
              </listitem>
442
 
            </varlistentry>
443
 
            <varlistentry>
444
 
              <term>Fast <option>mmap()</option> mode</term>
445
 
              <listitem>On 64-bit architectures it is possible to <option>mmap()</option> the whole file
446
 
                into the process address space, avoiding the limitation of 2 GB on 32-bit platforms.
447
 
              </listitem>
448
 
            </varlistentry>
449
 
            <varlistentry>
450
 
              <term>Using <option>fdatasync()</option> instead of <option>fsync()</option></term>
451
 
              Flush only data buffers, but not the metadata.
452
 
              <listitem>
453
 
              </listitem>
454
 
            </varlistentry>
455
 
            <varlistentry>
456
 
              <term>Additional flags to <option>open(2)</option></term>
457
 
              <listitem>SysBench can use additional flags to <option>open(2)</option>, such as <option>O_SYNC</option>,
458
 
                <option>O_DSYNC</option> and <option>O_DIRECT</option>.
459
 
              </listitem>
460
 
            </varlistentry>
461
 
          </variablelist>
462
 
        </para>
463
 
        <para>
464
 
          Below is a list of test-specific option for the <command>fileio</command> mode:
465
 
 
466
 
          <informaltable frame="all">
467
 
            <tgroup cols='3'> 
468
 
              <tbody>
469
 
                <row><entry><emphasis>Option</emphasis></entry><entry><emphasis>Description</emphasis></entry><entry><emphasis>Default value</emphasis></entry></row>
470
 
                <row><entry><option>--file-num</option></entry><entry>Number of files to create</entry><entry>128</entry></row>
471
 
                <row><entry><option>--file-block-size</option></entry><entry>
472
 
                    Block size to use in all I/O operations
473
 
                  </entry><entry>16K</entry></row>
474
 
                <row><entry><option>--file-total-size</option></entry><entry>Total size of files</entry><entry>2G</entry></row>
475
 
                <row><entry><option>--file-test-mode</option></entry><entry>
476
 
                    Type of workload to produce. Possible values: <option>seqwr</option>, <option>seqrewr</option>,
477
 
                    <option>seqrd</option>, <option>rndrd</option>, <option>rndwr</option>, <option>rndwr</option> (see above)
478
 
                  </entry><entry><emphasis>required</emphasis></entry></row>
479
 
                <row><entry><option>--file-io-mode</option></entry><entry>
480
 
                    I/O mode. Possible values: <option>sync</option>, <option>async</option>, <option>fastmmap</option>, 
481
 
                    <option>slowmmap</option> (only if supported by the platform, see above).
482
 
                  </entry><entry>sync</entry></row>
483
 
                <row><entry><option>--file-async-backlog</option></entry><entry>
484
 
                    Number of asynchronous operations to queue per thread (only for <option>--file-io-mode=async</option>, see above)
485
 
                  </entry><entry>128</entry></row>
486
 
                <row><entry><option> --file-extra-flags</option></entry><entry>
487
 
                    Additional flags to use with <option>open(2)</option>
488
 
                  </entry><entry></entry></row>
489
 
                <row><entry><option>--file-fsync-freq</option></entry><entry>
490
 
                    Do <option>fsync()</option> after this number of requests (0 - don't use <option>fsync()</option>)
491
 
                  </entry><entry>100</entry></row>
492
 
                <row><entry><option>--file-fsync-all</option></entry><entry>
493
 
                    Do <option>fsync()</option> after each write operation
494
 
                  </entry><entry>no</entry></row>
495
 
                <row><entry><option>--file-fsync-end</option></entry><entry>
496
 
                    Do <option>fsync()</option> at the end of the test
497
 
                  </entry><entry>yes</entry></row>
498
 
                <row><entry><option>--file-fsync-mode</option></entry><entry>
499
 
                    Which method to use for synchronization. Possible values: <option>fsync</option>, <option>fdatasync</option> (see above)
500
 
                  </entry><entry>fsync</entry></row>
501
 
                <row><entry><option>--file-merged-requests</option></entry><entry>
502
 
                    Merge at most this number of I/O requests if possible (0 - don't merge)
503
 
                  </entry><entry>0</entry></row>
504
 
                <row><entry><option>--file-rw-ratio</option></entry><entry>
505
 
                    reads/writes ration for combined random read/write test
506
 
                  </entry><entry>1.5</entry></row>
507
 
 
508
 
              </tbody>
509
 
            </tgroup>
510
 
          </informaltable>
511
 
 
512
 
        </para>
513
 
 
514
 
        <para>
515
 
          Usage example:
516
 
          <screen>
517
 
            $ sysbench --num-threads=16 --test=fileio --file-total-size=3G --file-test-mode=rndrw prepare
518
 
            $ sysbench --num-threads=16 --test=fileio --file-total-size=3G --file-test-mode=rndrw run
519
 
            $ sysbench --num-threads=16 --test=fileio --file-total-size=3G --file-test-mode=rndrw cleanup
520
 
          </screen>
521
 
          In the above example the first command creates 128 files with the total size of 3 GB in the current directory, the
522
 
          second command runs the actual benchmark and displays the results upon completion, and the third one removes the files
523
 
          used for the test.
524
 
        </para>
525
 
      </section>
526
 
 
527
 
      <section id="database_mode">
528
 
        <title><option>oltp</option></title>
529
 
      </section>
530
 
      <para>
531
 
        This test mode was written to benchmark a real database performance. At the <command>prepare</command> stage
532
 
        the following table is created in the specified database (<option>sbtest</option> by default):
533
 
        <screen>
534
 
          CREATE TABLE `sbtest` (
535
 
          `id` int(10) unsigned NOT NULL auto_increment,
536
 
          `k` int(10) unsigned NOT NULL default '0',
537
 
          `c` char(120) NOT NULL default '',
538
 
          `pad` char(60) NOT NULL default '',
539
 
          PRIMARY KEY  (`id`),
540
 
          KEY `k` (`k`);
541
 
        </screen>
542
 
        Then this table is filled with a specified number of rows. 
543
 
      </para>
544
 
      <para>
545
 
        The following execution modes are available at the <command>run</command> stage:
546
 
        <variablelist>
547
 
          <varlistentry>
548
 
            <term>Simple</term>
549
 
            <listitem>
550
 
              <para>
551
 
                In this mode each thread runs simple queries of the following form:
552
 
                <screen> SELECT c FROM sbtest WHERE id=<emphasis>N</emphasis>  </screen>
553
 
                where <emphasis>N</emphasis> takes a random value in range 1..<emphasis>&lt;table size&gt;</emphasis>
554
 
              </para>
555
 
            </listitem>
556
 
          </varlistentry>
557
 
          <varlistentry>
558
 
            <term>Advanced transactional</term>
559
 
            <listitem> 
560
 
              <para>
561
 
                Each thread performs transactions on the test table. If the test table and database support transactions
562
 
                (e.g. InnoDB engine in MySQL), then <option>BEGIN</option>/<option>COMMIT</option> statements will be used
563
 
                to start/stop a transaction. Otherwise, SysBench will use <option>LOCK TABLES</option>/<option>UNLOCK TABLES
564
 
                </option> statements (e.g. for MyISAM engine in MySQL). If some rows are deleted in a transaction,
565
 
                the same rows will be inserted within the same transaction, so this test mode does not destruct any data
566
 
                in the test table and can be run multiple times on the same table.
567
 
              </para>
568
 
 
569
 
              Depending on the command line options, each transaction may contain the following statements:
570
 
              <itemizedlist>
571
 
                <listitem>Point queries: <screen>SELECT c FROM sbtest WHERE id=<emphasis>N</emphasis></screen></listitem>
572
 
                <listitem>
573
 
                  Range queries: <screen>SELECT c FROM sbtest WHERE id BETWEEN <emphasis>N</emphasis> AND <emphasis>M</emphasis> </screen> </listitem>
574
 
                <listitem>
575
 
                  Range SUM() queries: <screen>SELECT SUM(K) FROM sbtest WHERE id BETWEEN <emphasis>N</emphasis> and <emphasis>M</emphasis></screen></listitem>
576
 
                <listitem>Range ORDER BY queries:<screen>SELECT c FROM sbtest WHERE id between <emphasis>N</emphasis> and <emphasis>M</emphasis> ORDER BY c</screen></listitem>
577
 
                <listitem>Range DISTINCT queries:<screen>SELECT DISTINCT c FROM sbtest WHERE id BETWEEN <emphasis>N</emphasis> and <emphasis>M</emphasis> ORDER BY c</screen> </listitem>
578
 
                <listitem>UPDATEs on index column:<screen>UPDATE sbtest SET k=k+1 WHERE id=<emphasis>N</emphasis> </screen> </listitem>
579
 
                <listitem>UPDATEs on non-index column:<screen>UPDATE sbtest SET c=<emphasis>N</emphasis> WHERE id=<emphasis>M</emphasis> </screen> </listitem>
580
 
                <listitem>DELETE queries:<screen>DELETE FROM sbtest WHERE id=<emphasis>N</emphasis> </screen> </listitem>
581
 
                <listitem>INSERT queries:<screen>INSERT INTO sbtest VALUES (<emphasis>...</emphasis>) </screen> </listitem>
582
 
              </itemizedlist> 
583
 
            </listitem>
584
 
          </varlistentry>
585
 
          <varlistentry>
586
 
            
587
 
            <term>Non-transactional</term>
588
 
            <listitem>
589
 
              <para>
590
 
                This mode is similar to <command>Simple</command>, but you can also choose the query to run. Note that unlike the 
591
 
                <command>Advanced transactional</command> mode, this one does not preserve the test table between requests, so
592
 
                you should recreate it with the appropriate <command>cleanup</command>/<command>prepare</command> commands between
593
 
                consecutive benchmarks. 
594
 
              </para>
595
 
              <para>
596
 
                Below is a list of possible queries:
597
 
                <itemizedlist>
598
 
                  <listitem>
599
 
                    Point queries:
600
 
                    <screen>SELECT pad FROM sbtest WHERE id=<emphasis>N</emphasis></screen>
601
 
                  </listitem>
602
 
                  <listitem>
603
 
                    UPDATEs on index column:
604
 
                    <screen>UPDATE sbtest SET k=k+1 WHERE id=<emphasis>N</emphasis></screen>
605
 
                  </listitem>
606
 
                  <listitem>
607
 
                    UPDATEs on non-index column:
608
 
                    <screen>UPDATE sbtest SET c=<emphasis>N</emphasis> WHERE id=<emphasis>M</emphasis></screen>
609
 
                  </listitem>
610
 
                  <listitem>
611
 
                    DELETE queries:
612
 
                    <screen>DELETE FROM sbtest WHERE id=<emphasis>N</emphasis></screen> 
613
 
                    The generated row IDs are unique over each test run, so no row is deleted twice.
614
 
                  </listitem>
615
 
                  <listitem>
616
 
                    INSERT queries:
617
 
                    <screen>INSERT INTO sbtest (k, c, pad) VALUES(<emphasis>N</emphasis>, <emphasis>M</emphasis>, <emphasis>S</emphasis>)</screen> 
618
 
                  </listitem>
619
 
                </itemizedlist> 
620
 
              </para>
621
 
            </listitem>
622
 
          </varlistentry>
623
 
        </variablelist>
624
 
      </para>
625
 
 
626
 
      <para>
627
 
        Below is a list of options available for the database test mode:
628
 
 
629
 
        <informaltable frame="all">
630
 
          <tgroup cols='3'> 
631
 
            <tbody>
632
 
              <row><entry><emphasis>Option</emphasis></entry><entry><emphasis>Description</emphasis></entry><entry><emphasis>Default value</emphasis></entry></row>
633
 
              <row><entry><option>--oltp-test-mode</option></entry><entry>Execution mode (see above). Possible values: <option>simpe</option> (simple), <option>complex</option> (advanced transactional) and <option>nontrx</option> (non-transactional)</entry><entry><option>complex</option></entry></row>
634
 
              <row><entry><option>--oltp-read-only</option></entry><entry>
635
 
                  Read-only mode. No <option>UPDATE</option>, <option>DELETE</option> or <option>INSERT</option> queries will be performed.
636
 
                </entry><entry>off</entry></row>
637
 
              <row><entry><option>--oltp-range-size</option></entry><entry>Range size for range queries</entry><entry>100</entry></row>
638
 
              <row><entry><option>--oltp-point-selects</option></entry><entry>
639
 
                  Number of point select queries in a single transaction
640
 
                </entry><entry>10</entry></row>
641
 
              <row><entry><option>--oltp-simple-ranges</option></entry><entry>
642
 
                  Number of simple range queries in a single transaction
643
 
                </entry><entry>1</entry></row>
644
 
              <row><entry><option>--oltp-sum-ranges</option></entry><entry>
645
 
                  Number of SUM range queries in a single transaction
646
 
                </entry><entry>1</entry></row>
647
 
              <row><entry><option>--oltp-order-ranges</option></entry><entry>
648
 
                  Number of ORDER range queries in a single transaction
649
 
                </entry><entry>1</entry></row>
650
 
              <row><entry><option>--oltp-distinct-ranges</option></entry><entry>
651
 
                  Number of DISTINCT range queries in a single transaction
652
 
                </entry><entry>1</entry></row>
653
 
              <row><entry><option>--oltp-index-updates</option></entry><entry>
654
 
                  Number of index UPDATE queries in a single transaction
655
 
                </entry><entry>1</entry></row>
656
 
              <row><entry><option>--oltp-non-index-updates</option></entry><entry>
657
 
                  Number of non-index UPDATE queries in a single transaction
658
 
                </entry><entry>1</entry></row>
659
 
              <row><entry><option> --oltp-nontrx-mode</option></entry><entry>
660
 
                  Type of queries for non-transactional execution mode (see above). Possible values: <option>select</option>,
661
 
                  <option>update_key</option>, <option>update_nokey</option>, <option>insert</option>, <option>delete</option>.
662
 
                </entry><entry><option>select</option></entry></row>
663
 
              <row><entry><option>--oltp-connect-delay</option></entry><entry>
664
 
                  Time in microseconds to sleep after each connection to database
665
 
                </entry><entry>10000</entry></row>
666
 
              <row><entry><option>--oltp-user-delay-min</option></entry><entry>
667
 
                  Minimum time in microseconds to sleep after each request
668
 
                </entry><entry>0</entry></row>
669
 
              <row><entry><option>--oltp-user-delay-max</option></entry><entry>
670
 
                  Maximum time in microseconds to sleep after each request
671
 
                </entry><entry>0</entry></row>
672
 
              <row><entry><option>--oltp-table-name</option></entry><entry>
673
 
                  Name of the test table
674
 
                </entry><entry>sbtest</entry></row>
675
 
              <row><entry><option>--oltp-table-size</option></entry><entry>
676
 
                  Number of rows in the test table
677
 
                </entry><entry>10000</entry></row>
678
 
              <row><entry><option>--oltp-dist-type</option></entry><entry>
679
 
                  <para>
680
 
                    Distribution of random numbers. Possible values: <option>uniform</option> (uniform distribution),
681
 
                    <option>gauss</option> (gaussian distribution) and <option>special</option>.
682
 
                  </para>
683
 
                  <para>
684
 
                    With special distribution a specified percent of numbers is generated in a specified percent of cases (see options below).
685
 
                  </para>
686
 
                </entry><entry><option>special</option></entry></row>
687
 
              <row><entry><option>--oltp-dist-pct</option></entry><entry>
688
 
                  Percentage of values to be treated as 'special' (for special distribution)
689
 
                </entry><entry>1</entry></row>
690
 
              <row><entry><option>--oltp-dist-res</option></entry><entry>
691
 
                  Percentage of cases when 'special' values are generated (for special distribution)
692
 
                </entry><entry>75</entry></row>
693
 
              <row><entry><option>--db-ps-mode</option></entry><entry>
694
 
                  If the database driver supports Prepared Statements API, SysBench will use server-side prepared statements for all queries
695
 
                  where possible. Otherwise, client-side (or emulated) prepared statements will be used. This option allows to force using
696
 
                  emulation even when PS API is available. Possible values: <option>disable</option>, <option>auto</option>.
697
 
                </entry><entry><option>auto</option></entry></row>
698
 
 
699
 
            </tbody>
700
 
          </tgroup>
701
 
        </informaltable>
702
 
      </para>
703
 
 
704
 
      <para>
705
 
        Also, each database driver may provide its own options. Currently only MySQL driver is available. Below is a list of MySQL-specific options:
706
 
 
707
 
        <informaltable frame="all">
708
 
          <tgroup cols='3'> 
709
 
            <tbody>
710
 
              <row><entry><emphasis>Option</emphasis></entry><entry><emphasis>Description</emphasis></entry><entry><emphasis>Default value</emphasis></entry></row>
711
 
              <row><entry><option>--mysql-host</option></entry>
712
 
                   <entry>
713
 
                      <para>
714
 
                          MySQL server host. 
715
 
                      </para>
716
 
                      <para>
717
 
                          Starting from version 0.4.5 you may specify a list of hosts separated by commas. In this case SysBench will distribute connections between specified MySQL hosts on a round-robin basis. Note that all connection ports and passwords must be the same on all hosts. Also, databases and tables must be prepared explicitely on each host before executing the benchmark.
718
 
                      </para>
719
 
                  </entry><entry><option>localhost</option></entry></row>
720
 
              <row><entry><option>--mysql-port</option></entry><entry>
721
 
                  MySQL server port (in case TCP/IP connection should be used)
722
 
                </entry><entry>3306</entry></row>
723
 
              <row><entry><option>--mysql-socket</option></entry><entry>Unix socket file to communicate with the MySQL server</entry><entry></entry></row>
724
 
              <row><entry><option>--mysql-user</option></entry><entry>
725
 
                  MySQL user
726
 
                </entry><entry>user</entry></row>
727
 
              <row><entry><option>--mysql-password</option></entry><entry>
728
 
                  MySQL password
729
 
                </entry><entry></entry></row>
730
 
              <row><entry><option>--mysql-db</option></entry><entry>
731
 
                  MySQL database name. Note SysBench will not automatically create this database. You should create it manually and grant
732
 
                  the appropriate privileges to a user which will be used to access the test table.
733
 
                </entry><entry>sbtest</entry></row>
734
 
              <row><entry><option>--mysql-table-type</option></entry><entry>
735
 
                  Type of the test table. Possible values: <option>myisam</option>, <option>innodb</option>, <option>heap</option>,
736
 
                  <option>ndbcluster</option>, <option>bdb</option>. 
737
 
                </entry><entry>innodb</entry></row>
738
 
              <row><entry><option>--myisam-max-rows</option></entry><entry>
739
 
                  MAX_ROWS option for MyISAM tables (required for big tables)  
740
 
                </entry><entry>1000000</entry></row>
741
 
            </tbody>
742
 
          </tgroup>
743
 
        </informaltable>
744
 
      </para>
745
 
 
746
 
      <para>
747
 
        Example usage:
748
 
        <screen>
749
 
          $ sysbench --test=oltp --mysql-table-type=myisam --oltp-table-size=1000000 --mysql-socket=/tmp/mysql.sock prepare
750
 
          $ sysbench --num-threads=16 --max-requests=100000 --test=oltp --oltp-table-size=1000000 --mysql-socket=/tmp/mysql.sock --oltp-read-only run
751
 
        </screen>
752
 
        The first command will create a MyISAM table 'sbtest' in a database 'sbtest' on a MySQL server using <option>/tmp/mysql.sock</option> socket, then fill this table with 1M records. The second command will run the actual benchmark with 16 client threads, limiting the total number of request by 100,000.
753
 
      </para>
754
 
 
755
 
    </section>
756
 
 
757
 
  </chapter>
758
 
 
759
 
</book>