fio
---
-fio is a tool that will spawn a number of thread doing a particular
-type of io action as specified by the user. fio takes a number of
-global parameters, each inherited by the thread unless otherwise
-parameters given to them overriding that setting is given.
+fio is a tool that will spawn a number of threads or processes doing a
+particular type of io action as specified by the user. fio takes a
+number of global parameters, each inherited by the thread unless
+otherwise parameters given to them overriding that setting is given.
+The typical use of fio is to write a job file matching the io load
+one wants to simulate.
Source
git://brick.kernel.dk/data/git/fio.git
-Snapshots are frequently generated as well and they include the git
-meta data as well. You can download them here:
+Snapshots are frequently generated and they include the git meta data as
+well. You can download them here:
http://brick.kernel.dk/snaps/
$ make -f Makefile.Freebsd && make -f Makefile.FreeBSD install
+Likewise with OpenSolaris, use the Makefile.solaris to compile there.
This might change in the future if I opt for an autoconf type setup.
-Options
--------
+Command line
+------------
$ fio
- -s IO is sequential
- -b block size in KiB for each io
-t <sec> Runtime in seconds
- -r For random io, sequence must be repeatable
- -R <on> If one thread fails to meet rate, quit all
- -o <on> Use direct IO is 1, buffered if 0
-l Generate per-job latency logs
-w Generate per-job bandwidth logs
- -f <file> Read <file> for job descriptions
+ -o <file> Log output to file
+ -m Minimal (terse) output
-h Print help info
-v Print version information and exit
-The <jobs> format is as follows:
+Any parameters following the options will be assumed to be job files.
+You can add as many as you want, each job file will be regarded as a
+separate group and fio will stonewall it's execution.
+
+
+Job file
+--------
+
+Only a few options can be controlled with command line parameters,
+generally it's a lot easier to just write a simple job file to describe
+the workload. The job file format is in the ini style format, as it's
+easy to read and write for the user.
+
+The job file parameters are:
name=x Use 'x' as the identifier for this job.
directory=x Use 'x' as the top level directory for storing files
be used if they don't add up to 100%.
rwmixwrite=x 'x' percentage of rw mix ios will be writes. See
rwmixread.
+ rand_repeatable=x The sequence of random io blocks can be repeatable
+ across runs, if 'x' is 1.
size=x Set file size to x bytes (x string can include k/m/g)
ioengine=x 'x' may be: aio/libaio/linuxaio for Linux aio,
posixaio for POSIX aio, sync for regular read/write io,
cpumask=x Only allow job to run on CPUs defined by mask.
fsync=x If writing, fsync after every x blocks have been written
startdelay=x Start this thread x seconds after startup
- timeout=x Terminate x seconds after startup
+ timeout=x Terminate x seconds after startup. Can include a
+ normal time suffix if not given in seconds, such as
+ 'm' for minutes, 'h' for hours, and 'd' for days.
offset=x Start io at offset x (x string can include k/m/g)
invalidate=x Invalidate page cache for file prior to doing io
sync=x Use sync writes if x and writing
exec_prerun=x Run 'x' before job io is begun.
exec_postrun=x Run 'x' after job io has finished.
ioscheduler=x Use ioscheduler 'x' for this job.
+ cpuload=x For a CPU io thread, percentage of CPU time to attempt
+ to burn.
+ cpuchunks=x Split burn cycles into pieces of x.
+
Examples using a job file
-------------------------
-A sample job file doing the same as above would look like this:
+Example 1) Two random readers
-[read_file]
-rw=0
-bs=4096
+Lets say we want to simulate two threads reading randomly from a file
+each. They will be doing IO in 4KiB chunks, using raw (O_DIRECT) IO.
+Since they share most parameters, we'll put those in the [global]
+section. Job 1 will use a 128MiB file, job 2 will use a 256MiB file.
-[write_file]
-rw=1
-bs=16384
+; ---snip---
-And fio would be invoked as:
+[global]
+ioengine=sync ; regular read/write(2), the default
+rw=randread
+bs=4k
+direct=1
-$ fio -o1 -s -f file_with_above
+[file1]
+size=128m
-The second example would look like this:
+[file2]
+size=256m
-[rf1]
-rw=0
-prio=6
+; ---snip---
-[rf2]
-rw=0
-prio=3
+Generally the [] bracketed name specifies a file name, but the "global"
+keyword is reserved for setting options that are inherited by each
+subsequent job description. It's possible to have several [global]
+sections in the job file, each one adds options that are inherited by
+jobs defined below it. The name can also point to a block device, such
+as /dev/sda. To run the above job file, simply do:
-[rf3]
-rw=0
-prio=0
-direct=1
+$ fio jobfile
+
+Example 2) Many random writers
+
+Say we want to exercise the IO subsystem some more. We'll define 64
+threads doing random buffered writes. We'll let each thread use async io
+with a depth of 4 ios in flight. A job file would then look like this:
+
+; ---snip---
+
+[global]
+ioengine=libaio
+iodepth=4
+rw=randwrite
+bs=32k
+direct=0
+size=64m
-And fio would be invoked as:
+[files]
+numjobs=64
-$ fio -o0 -s -b4096 -f file_with_above
+; ---snip---
-'global' is a reserved keyword. When used as the filename, it sets the
-default options for the threads following that section. It is possible
-to have more than one global section in the file, as it only affects
-subsequent jobs.
+This will create files.[0-63] and perform the random writes to them.
-Also see the examples/ dir for sample job files.
+There are endless ways to define jobs, the examples/ directory contains
+a few more examples.
Interpreting the output
fio spits out a lot of output. While running, fio will display the
status of the jobs created. An example of that would be:
-Threads now running: 2 : [ww] [5.73% done]
+Threads running: 1: [_r] [24.79% done] [eta 00h:01m:31s]
The characters inside the square brackets denote the current status of
each thread. The possible values (in typical life cycle order) are:
Idle Run
---- ---
P Thread setup, but not started.
-C Thread created and running, but not doing anything yet
+C Thread created.
+I Thread initialized, waiting.
R Running, doing sequential reads.
r Running, doing random reads.
W Running, doing sequential writes.
w Running, doing random writes.
+ M Running, doing mixed sequential reads/writes.
+ m Running, doing mixed random reads/writes.
+ F Running, currently waiting for fsync()
V Running, doing verification of written data.
E Thread exited, not reaped by main thread yet.
_ Thread reaped.
-The other values are fairly self explanatory - number of thread currently
-running and doing io, and the estimated completion percentage.
+The other values are fairly self explanatory - number of threads
+currently running and doing io, and the estimated completion percentage
+and time for the running group. It's impossible to estimate runtime
+of the following groups (if any).
When fio is done (or interrupted by ctrl-c), it will show the data for
each thread, group of threads, and disks in that order. For each data
aggrb= Aggregate bandwidth of threads in this group.
minb= The minimum average bandwidth a thread saw.
maxb= The maximum average bandwidth a thread saw.
-mint= The minimum runtime of a thread.
-maxt= The maximum runtime of a thread.
+mint= The smallest runtime of the threads in that group.
+maxt= The longest runtime of the threads in that group.
And finally, the disk statistics are printed. They will look like this:
io_queue= Total time spent in the disk queue.
util= The disk utilization. A value of 100% means we kept the disk
busy constantly, 50% would be a disk idling half of the time.
+
+
+Terse output
+------------
+
+For scripted usage where you typically want to generate tables or graphs
+of the results, fio can output the results in a comma seperated format.
+The format is one long line of values, such as:
+
+client1,0,0,936,331,2894,0,0,0.000000,0.000000,1,170,22.115385,34.290410,16,714,84.252874%,366.500000,566.417819,3496,1237,2894,0,0,0.000000,0.000000,0,246,6.671625,21.436952,0,2534,55.465300%,1406.600000,2008.044216,0.000000%,0.431928%,1109
+
+Split up, the format is as follows:
+
+ jobname, groupid, error
+ READ status:
+ KiB IO, bandwidth (KiB/sec), runtime (msec)
+ Submission latency: min, max, mean, deviation
+ Completion latency: min, max, mean, deviation
+ Bw: min, max, aggreate percentage of total, mean, deviation
+ WRITE status:
+ KiB IO, bandwidth (KiB/sec), runtime (msec)
+ Submission latency: min, max, mean, deviation
+ Completion latency: min, max, mean, deviation
+ Bw: min, max, aggreate percentage of total, mean, deviation
+ CPU usage: user, system, context switches
+
+
+Author
+------
+
+Fio was written by Jens Axboe <axboe@kernel.dk> to enable flexible testing
+of the Linux IO subsystem and schedulers. He got tired of writing
+specific test applications to simulate a given workload, and found that
+the existing io benchmark/test tools out there weren't flexible enough
+to do what he wanted.
+
+Jens Axboe <axboe@kernel.dk> 20060905
+
projects / fio.git / blobdiff