README

   1 fio
   2 ---
   3
   4 fio is a tool that will spawn a number of thread doing a particular
   5 type of io action as specified by the user. fio takes a number of
   6 global parameters, each inherited by the thread unless otherwise
   7 parameters given to them overriding that setting is given.
   8
   9
  10 Source
  11 ------
  12
  13 fio resides in a git repo, the canonical place is:
  14
  15 git://brick.kernel.dk/data/git/fio.git
  16
  17 Snapshots are frequently generated as well and they include the git
  18 meta data as well. You can download them here:
  19
  20 http://brick.kernel.dk/snaps/
  21
  22 Pascal Bleser <guru@unixtech.be> has fio RPMs in his repository, you
  23 can find them here:
  24
  25 http://linux01.gwdg.de/~pbleser/rpm-navigation.php?cat=System/fio
  26
  27
  28 Options
  29 -------
  30
  31 $ fio
  32         -s IO is sequential
  33         -b block size in KiB for each io
  34         -t <sec> Runtime in seconds
  35         -r For random io, sequence must be repeatable
  36         -R <on> If one thread fails to meet rate, quit all
  37         -o <on> Use direct IO is 1, buffered if 0
  38         -l Generate per-job latency logs
  39         -w Generate per-job bandwidth logs
  40         -f <file> Read <file> for job descriptions
  41         -h Print help info
  42         -v Print version information and exit
  43
  44 The <jobs> format is as follows:
  45
  46         name=x          Use 'x' as the identifier for this job.
  47         directory=x     Use 'x' as the top level directory for storing files
  48         rw=x            'x' may be: read, randread, write, randwrite,
  49                         rw (read-write mix), randrw (read-write random mix)
  50         rwmixcycle=x    Base cycle for switching between read and write
  51                         in msecs.
  52         rwmixread=x     'x' percentage of rw mix ios will be reads. If
  53                         rwmixwrite is also given, the last of the two will
  54                          be used if they don't add up to 100%.
  55         rwmixwrite=x    'x' percentage of rw mix ios will be writes. See
  56                         rwmixread.
  57         size=x          Set file size to x bytes (x string can include k/m/g)
  58         ioengine=x      'x' may be: aio/libaio/linuxaio for Linux aio,
  59                         posixaio for POSIX aio, sync for regular read/write io,
  60                         mmap for mmap'ed io, splice for using splice/vmsplice,
  61                         or sgio for direct SG_IO io. The latter only works on
  62                         Linux on SCSI (or SCSI-like devices, such as
  63                         usb-storage or sata/libata driven) devices.
  64         iodepth=x       For async io, allow 'x' ios in flight
  65         overwrite=x     If 'x', layout a write file first.
  66         prio=x          Run io at prio X, 0-7 is the kernel allowed range
  67         prioclass=x     Run io at prio class X
  68         bs=x            Use 'x' for thread blocksize. May include k/m postfix.
  69         bsrange=x-y     Mix thread block sizes randomly between x and y. May
  70                         also include k/m postfix.
  71         direct=x        1 for direct IO, 0 for buffered IO
  72         thinktime=x     "Think" x usec after each io
  73         rate=x          Throttle rate to x KiB/sec
  74         ratemin=x       Quit if rate of x KiB/sec can't be met
  75         ratecycle=x     ratemin averaged over x msecs
  76         cpumask=x       Only allow job to run on CPUs defined by mask.
  77         fsync=x         If writing, fsync after every x blocks have been written
  78         startdelay=x    Start this thread x seconds after startup
  79         timeout=x       Terminate x seconds after startup
  80         offset=x        Start io at offset x (x string can include k/m/g)
  81         invalidate=x    Invalidate page cache for file prior to doing io
  82         sync=x          Use sync writes if x and writing
  83         mem=x           If x == malloc, use malloc for buffers. If x == shm,
  84                         use shm for buffers. If x == mmap, use anon mmap.
  85         exitall         When one thread quits, terminate the others
  86         bwavgtime=x     Average bandwidth stats over an x msec window.
  87         create_serialize=x      If 'x', serialize file creation.
  88         create_fsync=x  If 'x', run fsync() after file creation.
  89         end_fsync=x     If 'x', run fsync() after end-of-job.
  90         loops=x         Run the job 'x' number of times.
  91         verify=x        If 'x' == md5, use md5 for verifies. If 'x' == crc32,
  92                         use crc32 for verifies. md5 is 'safer', but crc32 is
  93                         a lot faster. Only makes sense for writing to a file.
  94         stonewall       Wait for preceeding jobs to end before running.
  95         numjobs=x       Create 'x' similar entries for this job
  96         thread          Use pthreads instead of forked jobs
  97         zonesize=x
  98         zoneskip=y      Zone options must be paired. If given, the job
  99                         will skip y bytes for every x read/written. This
 100                         can be used to gauge hard drive speed over the entire
 101                         platter, without reading everything. Both x/y can
 102                         include k/m/g suffix.
 103         iolog=x         Open and read io pattern from file 'x'. The file must
 104                         contain one io action per line in the following format:
 105                         rw, offset, length
 106                         where with rw=0/1 for read/write, and the offset
 107                         and length entries being in bytes.
 108         write_iolog=x   Write an iolog to file 'x' in the same format as iolog.
 109                         The iolog options are exclusive, if both given the
 110                         read iolog will be performed.
 111         lockmem=x       Lock down x amount of memory on the machine, to
 112                         simulate a machine with less memory available. x can
 113                         include k/m/g suffix.
 114         nice=x          Run job at given nice value.
 115         exec_prerun=x   Run 'x' before job io is begun.
 116         exec_postrun=x  Run 'x' after job io has finished.
 117         ioscheduler=x   Use ioscheduler 'x' for this job.
 118
 119 Examples using a job file
 120 -------------------------
 121
 122 A sample job file doing the same as above would look like this:
 123
 124 [read_file]
 125 rw=0
 126 bs=4096
 127
 128 [write_file]
 129 rw=1
 130 bs=16384
 131
 132 And fio would be invoked as:
 133
 134 $ fio -o1 -s -f file_with_above
 135
 136 The second example would look like this:
 137
 138 [rf1]
 139 rw=0
 140 prio=6
 141
 142 [rf2]
 143 rw=0
 144 prio=3
 145
 146 [rf3]
 147 rw=0
 148 prio=0
 149 direct=1
 150
 151 And fio would be invoked as:
 152
 153 $ fio -o0 -s -b4096 -f file_with_above
 154
 155 'global' is a reserved keyword. When used as the filename, it sets the
 156 default options for the threads following that section. It is possible
 157 to have more than one global section in the file, as it only affects
 158 subsequent jobs.
 159
 160 Also see the examples/ dir for sample job files.
 161
 162
 163 Interpreting the output
 164 -----------------------
 165
 166 fio spits out a lot of output. While running, fio will display the
 167 status of the jobs created. An example of that would be:
 168
 169 Threads now running: 2 : [ww] [5.73% done]
 170
 171 The characters inside the square brackets denote the current status of
 172 each thread. The possible values (in typical life cycle order) are:
 173
 174 Idle    Run
 175 ----    ---
 176 P               Thread setup, but not started.
 177 C               Thread created and running, but not doing anything yet
 178         R       Running, doing sequential reads.
 179         r       Running, doing random reads.
 180         W       Running, doing sequential writes.
 181         w       Running, doing random writes.
 182 V               Running, doing verification of written data.
 183 E               Thread exited, not reaped by main thread yet.
 184 _               Thread reaped.
 185
 186 The other values are fairly self explanatory - number of thread currently
 187 running and doing io, and the estimated completion percentage.
 188
 189 When fio is done (or interrupted by ctrl-c), it will show the data for
 190 each thread, group of threads, and disks in that order. For each data
 191 direction, the output looks like:
 192
 193 Client1 (g=0): err= 0:
 194   write: io=    32MiB, bw=   666KiB/s, runt= 50320msec
 195     slat (msec): min=    0, max=  136, avg= 0.03, dev= 1.92
 196     clat (msec): min=    0, max=  631, avg=48.50, dev=86.82
 197     bw (KiB/s) : min=    0, max= 1196, per=51.00%, avg=664.02, dev=681.68
 198   cpu        : usr=1.49%, sys=0.25%, ctx=7969
 199
 200 The client number is printed, along with the group id and error of that
 201 thread. Below is the io statistics, here for writes. In the order listed,
 202 they denote:
 203
 204 io=             Number of megabytes io performed
 205 bw=             Average bandwidth rate
 206 runt=           The runtime of that thread
 207         slat=   Submission latency (avg being the average, dev being the
 208                 standard deviation). This is the time it took to submit
 209                 the io. For sync io, the slat is really the completion
 210                 latency, since queue/complete is one operation there.
 211         clat=   Completion latency. Same names as slat, this denotes the
 212                 time from submission to completion of the io pieces. For
 213                 sync io, clat will usually be equal (or very close) to 0,
 214                 as the time from submit to complete is basically just
 215                 CPU time (io has already been done, see slat explanation).
 216         bw=     Bandwidth. Same names as the xlat stats, but also includes
 217                 an approximate percentage of total aggregate bandwidth
 218                 this thread received in this group. This last value is
 219                 only really useful if the threads in this group are on the
 220                 same disk, since they are then competing for disk access.
 221 cpu=            CPU usage. User and system time, along with the number
 222                 of context switches this thread went through.
 223
 224 After each client has been listed, the group statistics are printed. They
 225 will look like this:
 226
 227 Run status group 0 (all jobs):
 228    READ: io=64MiB, aggrb=22178, minb=11355, maxb=11814, mint=2840msec, maxt=2955msec
 229   WRITE: io=64MiB, aggrb=1302, minb=666, maxb=669, mint=50093msec, maxt=50320msec
 230
 231 For each data direction, it prints:
 232
 233 io=             Number of megabytes io performed.
 234 aggrb=          Aggregate bandwidth of threads in this group.
 235 minb=           The minimum average bandwidth a thread saw.
 236 maxb=           The maximum average bandwidth a thread saw.
 237 mint=           The minimum runtime of a thread.
 238 maxt=           The maximum runtime of a thread.
 239
 240 And finally, the disk statistics are printed. They will look like this:
 241
 242 Disk stats (read/write):
 243   sda: ios=16398/16511, merge=30/162, ticks=6853/819634, in_queue=826487, util=100.00%
 244
 245 Each value is printed for both reads and writes, with reads first. The
 246 numbers denote:
 247
 248 ios=            Number of ios performed by all groups.
 249 merge=          Number of merges io the io scheduler.
 250 ticks=          Number of ticks we kept the disk busy.
 251 io_queue=       Total time spent in the disk queue.
 252 util=           The disk utilization. A value of 100% means we kept the disk
 253                 busy constantly, 50% would be a disk idling half of the time.