README

   1 fio
   2 ---
   3
   4 fio is a tool that will spawn a number of threads or processes doing a
   5 particular type of io action as specified by the user. fio takes a
   6 number of global parameters, each inherited by the thread unless
   7 otherwise parameters given to them overriding that setting is given.
   8 The typical use of fio is to write a job file matching the io load
   9 one wants to simulate.
  10
  11
  12 Source
  13 ------
  14
  15 fio resides in a git repo, the canonical place is:
  16
  17 git://brick.kernel.dk/data/git/fio.git
  18
  19 Snapshots are frequently generated and they include the git meta data as
  20 well. You can download them here:
  21
  22 http://brick.kernel.dk/snaps/
  23
  24 Pascal Bleser <guru@unixtech.be> has fio RPMs in his repository, you
  25 can find them here:
  26
  27 http://linux01.gwdg.de/~pbleser/rpm-navigation.php?cat=System/fio
  28
  29
  30 Building
  31 --------
  32
  33 Just type 'make' and 'make install'. If on FreeBSD, for now you have to
  34 specify the FreeBSD Makefile with -f, eg:
  35
  36 $ make -f Makefile.Freebsd && make -f Makefile.FreeBSD install
  37
  38 Likewise with OpenSolaris, use the Makefile.solaris to compile there.
  39 This might change in the future if I opt for an autoconf type setup.
  40
  41
  42 Command line
  43 ------------
  44
  45 $ fio
  46         -s IO is sequential
  47         -b block size in KiB for each io
  48         -t <sec> Runtime in seconds
  49         -r For random io, sequence must be repeatable
  50         -R <on> If one thread fails to meet rate, quit all
  51         -o <on> Use direct IO is 1, buffered if 0
  52         -l Generate per-job latency logs
  53         -w Generate per-job bandwidth logs
  54         -f <file> Read <file> for job descriptions
  55         -O <file> Log output to file
  56         -h Print help info
  57         -v Print version information and exit
  58
  59 Any parameters following the options will be assumed to be job files.
  60 You can add as many as you want, each job file will be regarded as a
  61 separate group and fio will stonewall it's execution.
  62
  63
  64 Job file
  65 --------
  66
  67 Only a few options can be controlled with command line parameters,
  68 generally it's a lot easier to just write a simple job file to describe
  69 the workload. The job file format is in the ini style format, as it's
  70 easy to read and write for the user.
  71
  72 The job file parameters are:
  73
  74         name=x          Use 'x' as the identifier for this job.
  75         directory=x     Use 'x' as the top level directory for storing files
  76         rw=x            'x' may be: read, randread, write, randwrite,
  77                         rw (read-write mix), randrw (read-write random mix)
  78         rwmixcycle=x    Base cycle for switching between read and write
  79                         in msecs.
  80         rwmixread=x     'x' percentage of rw mix ios will be reads. If
  81                         rwmixwrite is also given, the last of the two will
  82                          be used if they don't add up to 100%.
  83         rwmixwrite=x    'x' percentage of rw mix ios will be writes. See
  84                         rwmixread.
  85         size=x          Set file size to x bytes (x string can include k/m/g)
  86         ioengine=x      'x' may be: aio/libaio/linuxaio for Linux aio,
  87                         posixaio for POSIX aio, sync for regular read/write io,
  88                         mmap for mmap'ed io, splice for using splice/vmsplice,
  89                         or sgio for direct SG_IO io. The latter only works on
  90                         Linux on SCSI (or SCSI-like devices, such as
  91                         usb-storage or sata/libata driven) devices.
  92         iodepth=x       For async io, allow 'x' ios in flight
  93         overwrite=x     If 'x', layout a write file first.
  94         prio=x          Run io at prio X, 0-7 is the kernel allowed range
  95         prioclass=x     Run io at prio class X
  96         bs=x            Use 'x' for thread blocksize. May include k/m postfix.
  97         bsrange=x-y     Mix thread block sizes randomly between x and y. May
  98                         also include k/m postfix.
  99         direct=x        1 for direct IO, 0 for buffered IO
 100         thinktime=x     "Think" x usec after each io
 101         rate=x          Throttle rate to x KiB/sec
 102         ratemin=x       Quit if rate of x KiB/sec can't be met
 103         ratecycle=x     ratemin averaged over x msecs
 104         cpumask=x       Only allow job to run on CPUs defined by mask.
 105         fsync=x         If writing, fsync after every x blocks have been written
 106         startdelay=x    Start this thread x seconds after startup
 107         timeout=x       Terminate x seconds after startup
 108         offset=x        Start io at offset x (x string can include k/m/g)
 109         invalidate=x    Invalidate page cache for file prior to doing io
 110         sync=x          Use sync writes if x and writing
 111         mem=x           If x == malloc, use malloc for buffers. If x == shm,
 112                         use shm for buffers. If x == mmap, use anon mmap.
 113         exitall         When one thread quits, terminate the others
 114         bwavgtime=x     Average bandwidth stats over an x msec window.
 115         create_serialize=x      If 'x', serialize file creation.
 116         create_fsync=x  If 'x', run fsync() after file creation.
 117         end_fsync=x     If 'x', run fsync() after end-of-job.
 118         loops=x         Run the job 'x' number of times.
 119         verify=x        If 'x' == md5, use md5 for verifies. If 'x' == crc32,
 120                         use crc32 for verifies. md5 is 'safer', but crc32 is
 121                         a lot faster. Only makes sense for writing to a file.
 122         stonewall       Wait for preceeding jobs to end before running.
 123         numjobs=x       Create 'x' similar entries for this job
 124         thread          Use pthreads instead of forked jobs
 125         zonesize=x
 126         zoneskip=y      Zone options must be paired. If given, the job
 127                         will skip y bytes for every x read/written. This
 128                         can be used to gauge hard drive speed over the entire
 129                         platter, without reading everything. Both x/y can
 130                         include k/m/g suffix.
 131         iolog=x         Open and read io pattern from file 'x'. The file must
 132                         contain one io action per line in the following format:
 133                         rw, offset, length
 134                         where with rw=0/1 for read/write, and the offset
 135                         and length entries being in bytes.
 136         write_iolog=x   Write an iolog to file 'x' in the same format as iolog.
 137                         The iolog options are exclusive, if both given the
 138                         read iolog will be performed.
 139         lockmem=x       Lock down x amount of memory on the machine, to
 140                         simulate a machine with less memory available. x can
 141                         include k/m/g suffix.
 142         nice=x          Run job at given nice value.
 143         exec_prerun=x   Run 'x' before job io is begun.
 144         exec_postrun=x  Run 'x' after job io has finished.
 145         ioscheduler=x   Use ioscheduler 'x' for this job.
 146
 147
 148 Examples using a job file
 149 -------------------------
 150
 151 Example 1) Two random readers
 152
 153 Lets say we want to simulate two threads reading randomly from a file
 154 each. They will be doing IO in 4KiB chunks, using raw (O_DIRECT) IO.
 155 Since they share most parameters, we'll put those in the [global]
 156 section. Job 1 will use a 128MiB file, job 2 will use a 256MiB file.
 157
 158 ; ---snip---
 159
 160 [global]
 161 ioengine=sync   ; regular read/write(2), the default
 162 rw=randread
 163 bs=4k
 164 direct=1
 165
 166 [file1]
 167 size=128m
 168
 169 [file2]
 170 size=256m
 171
 172 ; ---snip---
 173
 174 Generally the [] bracketed name specifies a file name, but the "global"
 175 keyword is reserved for setting options that are inherited by each
 176 subsequent job description. It's possible to have several [global]
 177 sections in the job file, each one adds options that are inherited by
 178 jobs defined below it. The name can also point to a block device, such
 179 as /dev/sda. To run the above job file, simply do:
 180
 181 $ fio jobfile
 182
 183 Example 2) Many random writers
 184
 185 Say we want to exercise the IO subsystem some more. We'll define 64
 186 threads doing random buffered writes. We'll let each thread use async io
 187 with a depth of 4 ios in flight. A job file would then look like this:
 188
 189 ; ---snip---
 190
 191 [global]
 192 ioengine=libaio
 193 iodepth=4
 194 rw=randwrite
 195 bs=32k
 196 direct=0
 197 size=64m
 198
 199 [files]
 200 numjobs=64
 201
 202 ; ---snip---
 203
 204 This will create files.[0-63] and perform the random writes to them.
 205
 206 There are endless ways to define jobs, the examples/ directory contains
 207 a few more examples.
 208
 209
 210 Interpreting the output
 211 -----------------------
 212
 213 fio spits out a lot of output. While running, fio will display the
 214 status of the jobs created. An example of that would be:
 215
 216 Threads running: 1: [_r] [24.79% done] [eta 00h:01m:31s]
 217
 218 The characters inside the square brackets denote the current status of
 219 each thread. The possible values (in typical life cycle order) are:
 220
 221 Idle    Run
 222 ----    ---
 223 P               Thread setup, but not started.
 224 C               Thread created.
 225 I               Thread initialized, waiting.
 226         R       Running, doing sequential reads.
 227         r       Running, doing random reads.
 228         W       Running, doing sequential writes.
 229         w       Running, doing random writes.
 230         M       Running, doing mixed sequential reads/writes.
 231         m       Running, doing mixed random reads/writes.
 232         F       Running, currently waiting for fsync()
 233 V               Running, doing verification of written data.
 234 E               Thread exited, not reaped by main thread yet.
 235 _               Thread reaped.
 236
 237 The other values are fairly self explanatory - number of threads
 238 currently running and doing io, and the estimated completion percentage
 239 and time for the running group. It's impossible to estimate runtime
 240 of the following groups (if any).
 241
 242 When fio is done (or interrupted by ctrl-c), it will show the data for
 243 each thread, group of threads, and disks in that order. For each data
 244 direction, the output looks like:
 245
 246 Client1 (g=0): err= 0:
 247   write: io=    32MiB, bw=   666KiB/s, runt= 50320msec
 248     slat (msec): min=    0, max=  136, avg= 0.03, dev= 1.92
 249     clat (msec): min=    0, max=  631, avg=48.50, dev=86.82
 250     bw (KiB/s) : min=    0, max= 1196, per=51.00%, avg=664.02, dev=681.68
 251   cpu        : usr=1.49%, sys=0.25%, ctx=7969
 252
 253 The client number is printed, along with the group id and error of that
 254 thread. Below is the io statistics, here for writes. In the order listed,
 255 they denote:
 256
 257 io=             Number of megabytes io performed
 258 bw=             Average bandwidth rate
 259 runt=           The runtime of that thread
 260         slat=   Submission latency (avg being the average, dev being the
 261                 standard deviation). This is the time it took to submit
 262                 the io. For sync io, the slat is really the completion
 263                 latency, since queue/complete is one operation there.
 264         clat=   Completion latency. Same names as slat, this denotes the
 265                 time from submission to completion of the io pieces. For
 266                 sync io, clat will usually be equal (or very close) to 0,
 267                 as the time from submit to complete is basically just
 268                 CPU time (io has already been done, see slat explanation).
 269         bw=     Bandwidth. Same names as the xlat stats, but also includes
 270                 an approximate percentage of total aggregate bandwidth
 271                 this thread received in this group. This last value is
 272                 only really useful if the threads in this group are on the
 273                 same disk, since they are then competing for disk access.
 274 cpu=            CPU usage. User and system time, along with the number
 275                 of context switches this thread went through.
 276
 277 After each client has been listed, the group statistics are printed. They
 278 will look like this:
 279
 280 Run status group 0 (all jobs):
 281    READ: io=64MiB, aggrb=22178, minb=11355, maxb=11814, mint=2840msec, maxt=2955msec
 282   WRITE: io=64MiB, aggrb=1302, minb=666, maxb=669, mint=50093msec, maxt=50320msec
 283
 284 For each data direction, it prints:
 285
 286 io=             Number of megabytes io performed.
 287 aggrb=          Aggregate bandwidth of threads in this group.
 288 minb=           The minimum average bandwidth a thread saw.
 289 maxb=           The maximum average bandwidth a thread saw.
 290 mint=           The smallest runtime of the threads in that group.
 291 maxt=           The longest runtime of the threads in that group.
 292
 293 And finally, the disk statistics are printed. They will look like this:
 294
 295 Disk stats (read/write):
 296   sda: ios=16398/16511, merge=30/162, ticks=6853/819634, in_queue=826487, util=100.00%
 297
 298 Each value is printed for both reads and writes, with reads first. The
 299 numbers denote:
 300
 301 ios=            Number of ios performed by all groups.
 302 merge=          Number of merges io the io scheduler.
 303 ticks=          Number of ticks we kept the disk busy.
 304 io_queue=       Total time spent in the disk queue.
 305 util=           The disk utilization. A value of 100% means we kept the disk
 306                 busy constantly, 50% would be a disk idling half of the time.
 307
 308
 309 Author
 310 ------
 311
 312 Fio was written by Jens Axboe <axboe@suse.de> to enable flexible testing
 313 of the Linux IO subsystem and schedulers. He got tired of writing
 314 specific test applications to simulate a given workload, and found that
 315 the existing io benchmark/test tools out there weren't flexible enough
 316 to do what he wanted.
 317
 318 Jens Axboe <axboe@suse.de> 20060609
 319