5. Detailed list of parameters
6. Normal output
7. Terse output
-
+8. Trace file format
1.0 Overview and history
------------------------
1k:4k. If the option allows two sets of ranges, they can be
specified with a ',' or '/' delimiter: 1k-4k/8k-32k. Also see
int.
+float_list A list of floating numbers, separated by a ':' character.
With the above in mind, here follows the complete list of fio job
parameters.
files between threads in a job or several jobs, specify
a filename for each of them to override the default. If
the ioengine used is 'net', the filename is the host, port,
- and protocol to use in the format of =host/port/protocol.
+ and protocol to use in the format of =host,port,protocol.
See ioengine=net for more. If the ioengine is file based, you
can specify a number of files by separating the names with a
':' colon. So if you wanted a job to open /dev/sda and /dev/sdb
a number of IO's to do before getting a new offset, this is
one by appending a ':<nr>' to the end of the string given.
For a random read, it would look like 'rw=randread:8' for
- passing in an offset modifier with a value of 8. See the
- 'rw_sequencer' option.
+ passing in an offset modifier with a value of 8. If the
+ postfix is used with a sequential IO pattern, then the value
+ specified will be added to the generated offset for each IO.
+ For instance, using rw=write:4k will skip 4k for every
+ write. It turns sequential IO into sequential IO with holes.
+ See the 'rw_sequencer' option.
rw_sequencer=str If an offset modifier is given by appending a number to
the rw=<str> line, then this option controls how that
randrepeat=bool For random IO workloads, seed the generator in a predictable
way so that results are repeatable across repetitions.
-fallocate=bool By default, fio will use fallocate() to advise the system
- of the size of the file we are going to write. This can be
- turned off with fallocate=0. May not be available on all
- supported platforms. If using ZFS on Solaris this must be
- set to 0 because ZFS doesn't support it.
+use_os_rand=bool Fio can either use the random generator supplied by the OS
+ to generator random offsets, or it can use it's own internal
+ generator (based on Tausworthe). Default is to use the
+ internal generator, which is often of better quality and
+ faster.
+
+fallocate=str Whether pre-allocation is performed when laying down files.
+ Accepted values are:
+
+ none Do not pre-allocate space
+ posix Pre-allocate via posix_fallocate()
+ keep Pre-allocate via fallocate() with
+ FALLOC_FL_KEEP_SIZE set
+ 0 Backward-compatible alias for 'none'
+ 1 Backward-compatible alias for 'posix'
+
+ May not be available on all supported platforms. 'keep' is only
+ available on Linux.If using ZFS on Solaris this must be set to
+ 'none' because ZFS doesn't support it. Default: 'posix'.
fadvise_hint=bool By default, fio will use fadvise() to advise the kernel
on what IO patterns it is likely to issue. Sometimes you
fio will divide this size between the available files
specified by the job. If not set, fio will use the full
size of the given files or devices. If the the files
- do not exist, size must be given.
+ do not exist, size must be given. It is also possible to
+ give size as a percentage between 1 and 100. If size=20%
+ is given, fio will use 20% of the full size of the given
+ files or devices.
filesize=int Individual file sizes. May be a range, in which case fio
will select sizes for files at random within the given range
and limited to 'size' in total (if that is given). If not
given, each created file is the same size.
-fill_device=bool Sets size to something really large and waits for ENOSPC (no
+fill_device=bool
+fill_fs=bool Sets size to something really large and waits for ENOSPC (no
space left on device) as the terminating condition. Only makes
sense with sequential write. For a read workload, the mount
point will be filled first then IO started on the result. This
isn't specified, naturally. If data verification is enabled,
refill_buffers is also automatically enabled.
+scramble_buffers=bool If refill_buffers is too costly and the target is
+ using data deduplication, then setting this option will
+ slightly modify the IO buffer contents to defeat normal
+ de-dupe attempts. This is not enough to defeat more clever
+ block compression attempts, but it will stop naive dedupe of
+ blocks. Default: true.
+
nrfiles=int Number of files to use for this job. Defaults to 1.
openfiles=int Number of files to keep open at the same time. Defaults to
libaio Linux native asynchronous io. Note that Linux
may only support queued behaviour with
non-buffered IO (set direct=1 or buffered=0).
+ This engine also has a sub-option,
+ userspace_reap. To set it, use
+ ioengine=libaio:userspace_reap. Normally, with
+ the libaio engine in use, fio will use the
+ io_getevents system call to reap newly returned
+ events. With this flag turned on, the AIO ring
+ will be read directly from user-space to reap
+ events. The reaping mode is only enabled when
+ polling for a minimum of 0 events (eg when
+ iodepth_batch_complete=0).
posixaio glibc posix asynchronous io.
for more info on GUASI.
+ rdma The RDMA I/O engine supports both RDMA
+ memory semantics (RDMA_WRITE/RDMA_READ) and
+ channel semantics (Send/Recv) for the
+ InfiniBand, RoCE and iWARP protocols.
+
external Prefix to specify loading an external
IO engine object file. Append the engine
filename, eg ioengine=external:/tmp/foo.o
blocksizes (via bsrange=) are used, since fio only tracks
complete rewrites of blocks.
-softrandommap See norandommap. If fio runs with the random block map enabled
- and it fails to allocate the map, if this option is set it
- will continue without a random block map. As coverage will
- not be as complete as with random maps, this option is
+softrandommap=bool See norandommap. If fio runs with the random block map
+ enabled and it fails to allocate the map, if this option is
+ set it will continue without a random block map. As coverage
+ will not be as complete as with random maps, this option is
disabled by default.
nice=int Run the job with the given nice value. See man nice(2).
bwavgtime=int Average the calculated bandwidth over the given time. Value
is specified in milliseconds.
+iopsavgtime=int Average the calculated IOPS over the given time. Value
+ is specified in milliseconds.
+
create_serialize=bool If true, serialize the file creating for the jobs.
This may be handy to avoid interleaving of data
files, which may greatly depend on the filesystem
verify_dump=bool If set, dump the contents of both the original data
block and the data block we read off disk to files. This
allows later analysis to inspect just what kind of data
- corruption occurred. On by default.
+ corruption occurred. Off by default.
verify_async=int Fio will normally verify IO inline from the submitting
thread. This option takes an integer describing how many
if verify_backlog_batch is larger than verify_backlog, some
blocks will be verified more than once.
-stonewall Wait for preceeding jobs in the job file to exit, before
+stonewall
+wait_for_previous Wait for preceeding jobs in the job file to exit, before
starting this one. Can be used to insert serialization
points in the job file. A stone wall also implies starting
a new reporting group.
and foo_lat.log. This helps fio_generate_plot fine the logs
automatically.
+write_bw_log=str If given, write an IOPS log of the jobs in this job
+ file. See write_bw_log.
+
lockmem=int Pin down the specified amount of memory with mlock(2). Can
potentially be used instead of removing memory or booting
with less memory to simulate a smaller amount of memory.
disable_bw=bool Disable measurements of throughput/bandwidth numbers. See
disable_lat.
+clat_percentiles=bool Enable the reporting of percentiles of
+ completion latencies.
+
+percentile_list=float_list Overwrite the default list of percentiles
+ for completion latencies. Each number is a floating
+ number in the range (0,100], and the maximum length of
+ the list is 20. Use ':' to separate the numbers, and
+ list the numbers in ascending order. For example,
+ --percentile_list=99.5:99.9 will cause fio to report
+ the values of completion latency below which 99.5% and
+ 99.9% of the observed latencies fell, respectively.
+
gtod_reduce=bool Enable all of the gettimeofday() reducing options
(disable_clat, disable_slat, disable_bw) plus reduce
precision of the timeout somewhat to really shrink
direction, the output looks like:
Client1 (g=0): err= 0:
- write: io= 32MB, bw= 666KB/s, runt= 50320msec
+ write: io= 32MB, bw= 666KB/s, iops=89 , runt= 50320msec
slat (msec): min= 0, max= 136, avg= 0.03, stdev= 1.92
clat (msec): min= 0, max= 631, avg=48.50, stdev=86.82
bw (KB/s) : min= 0, max= 1196, per=51.00%, avg=664.02, stdev=681.68
io= Number of megabytes io performed
bw= Average bandwidth rate
+iops= Average IOs performed per second
runt= The runtime of that thread
slat= Submission latency (avg being the average, stdev being the
standard deviation). This is the time it took to submit
Split up, the format is as follows:
- version, jobname, groupid, error
+ terse version, fio version, jobname, groupid, error
READ status:
- KB IO, bandwidth (KB/sec), runtime (msec)
+ Total IO (KB), bandwidth (KB/sec), IOPS, runtime (msec)
Submission latency: min, max, mean, deviation
Completion latency: min, max, mean, deviation
+ Completion latency percentiles: 20 fields (see below)
Total latency: min, max, mean, deviation
Bw: min, max, aggregate percentage of total, mean, deviation
WRITE status:
- KB IO, bandwidth (KB/sec), runtime (msec)
+ Total IO (KB), bandwidth (KB/sec), IOPS, runtime (msec)
Submission latency: min, max, mean, deviation
Completion latency: min, max, mean, deviation
+ Completion latency percentiles: 20 fields (see below)
Total latency: min, max, mean, deviation
Bw: min, max, aggregate percentage of total, mean, deviation
CPU usage: user, system, context switches, major faults, minor faults
IO depths: <=1, 2, 4, 8, 16, 32, >=64
IO latencies microseconds: <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000
IO latencies milliseconds: <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000, 2000, >=2000
+ Disk utilization: Disk name, Read ios, write ios,
+ Read merges, write merges,
+ Read ticks, write ticks,
+ Time spent in queue, disk utilization percentage
Additional Info (dependant on continue_on_error, default off): total # errors, first error code
Additional Info (dependant on description being set): Text description
+
+Completion latency percentiles can be a grouping of up to 20 sets, so
+for the terse output fio writes all of them. Each field will look like this:
+
+ 1.00%=6112
+
+which is the Xth percentile, and the usec latency associated with it.
+
+For disk utilization, all disks used by fio are shown. So for each disk
+there will be a disk utilization section.
+
+
+8.0 Trace file format
+---------------------
+There are two trace file format that you can encounter. The older (v1) format
+is unsupported since version 1.20-rc3 (March 2008). It will still be described
+below in case that you get an old trace and want to understand it.
+
+In any case the trace is a simple text file with a single action per line.
+
+
+8.1 Trace file format v1
+------------------------
+Each line represents a single io action in the following format:
+
+rw, offset, length
+
+where rw=0/1 for read/write, and the offset and length entries being in bytes.
+
+This format is not supported in Fio versions => 1.20-rc3.
+
+
+8.2 Trace file format v2
+------------------------
+The second version of the trace file format was added in Fio version 1.17.
+It allows to access more then one file per trace and has a bigger set of
+possible file actions.
+
+The first line of the trace file has to be:
+
+fio version 2 iolog
+
+Following this can be lines in two different formats, which are described below.
+
+The file management format:
+
+filename action
+
+The filename is given as an absolute path. The action can be one of these:
+
+add Add the given filename to the trace
+open Open the file with the given filename. The filename has to have
+ been added with the add action before.
+close Close the file with the given filename. The file has to have been
+ opened before.
+
+
+The file io action format:
+
+filename action offset length
+
+The filename is given as an absolute path, and has to have been added and opened
+before it can be used with this format. The offset and length are given in
+bytes. The action can be one of these:
+
+wait Wait for 'offset' microseconds. Everything below 100 is discarded.
+read Read 'length' bytes beginning from 'offset'
+write Write 'length' bytes beginning from 'offset'
+sync fsync() the file
+datasync fdatasync() the file
+trim trim the given file from the given 'offset' for 'length' bytes