X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=README;h=d6ff1096ce4c8482adab333b626e8aac2f2fd07c;hp=8b84a08a8d8583ce2e24b03dc74947f565e40b84;hb=c6ae0a5b8123ea9af2ce70319081fbd5d65c8093;hpb=a4e167ee3ba40cb0587cf27dca2a9f8b947e568a diff --git a/README b/README index 8b84a08a..d6ff1096 100644 --- a/README +++ b/README @@ -1,10 +1,12 @@ 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 @@ -14,33 +16,70 @@ fio resides in a git repo, the canonical place is: 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/ +Pascal Bleser has fio RPMs in his repository, you +can find them here: -Options -------- +http://linux01.gwdg.de/~pbleser/rpm-navigation.php?cat=System/fio + + +Building +-------- + +Just type 'make' and 'make install'. If on FreeBSD, for now you have to +specify the FreeBSD Makefile with -f, eg: + +$ 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. + + +Command line +------------ $ fio - -s IO is sequential - -b block size in KiB for each io -t Runtime in seconds - -r For random io, sequence must be repeatable - -R If one thread fails to meet rate, quit all - -o Use direct IO is 1, buffered if 0 -l Generate per-job latency logs -w Generate per-job bandwidth logs -f Read for job descriptions + -o Log output to file + -m Minimal (terse) output -h Print help info -v Print version information and exit -The 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 rw=x 'x' may be: read, randread, write, randwrite, rw (read-write mix), randrw (read-write random mix) + rwmixcycle=x Base cycle for switching between read and write + in msecs. + rwmixread=x 'x' percentage of rw mix ios will be reads. If + rwmixwrite is also given, the last of the two will + 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, @@ -92,52 +131,78 @@ The format is as follows: rw, offset, length where with rw=0/1 for read/write, and the offset and length entries being in bytes. + write_iolog=x Write an iolog to file 'x' in the same format as iolog. + The iolog options are exclusive, if both given the + read iolog will be performed. lockmem=x Lock down x amount of memory on the machine, to simulate a machine with less memory available. x can include k/m/g suffix. + nice=x Run job at given nice value. + 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. + 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 -And fio would be invoked as: +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: -$ 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. +[global] +ioengine=libaio +iodepth=4 +rw=randwrite +bs=32k +direct=0 +size=64m -Also see the examples/ dir for sample job files. +[files] +numjobs=64 + +; ---snip--- + +This will create files.[0-63] and perform the random writes to them. + +There are endless ways to define jobs, the examples/ directory contains +a few more examples. Interpreting the output @@ -146,7 +211,7 @@ 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: @@ -154,17 +219,23 @@ 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 @@ -214,8 +285,8 @@ io= Number of megabytes io performed. 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: @@ -231,3 +302,41 @@ ticks= Number of ticks we kept the disk busy. 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 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 20060609 +