and it will start doing what the job_file tells it to do. You can give
more than one job file on the command line, fio will serialize the running
of those files. Internally that is the same as using the 'stonewall'
-parameter described the the parameter section.
+parameter described in the parameter section.
If the job file contains only one job, you may as well just give the
parameters on the command line. The command line parameters are identical
str String. This is a sequence of alpha characters.
time Integer with possible time suffix. In seconds unless otherwise
specified, use eg 10m for 10 minutes. Accepts s/m/h for seconds,
- minutes, and hours.
+ minutes, and hours, and accepts 'ms' (or 'msec') for milliseconds,
+ and 'us' (or 'usec') for microseconds.
int SI integer. A whole number value, which may contain a suffix
describing the base of the number. Accepted suffixes are k/m/g/t/p,
meaning kilo, mega, giga, tera, and peta. The suffix is not case
not parsed.
directory=str Prefix filenames with this directory. Used to place files
- in a different location than "./".
+ in a different location than "./". See the 'filename' option
+ for escaping certain characters.
filename=str Fio normally makes up a filename based on the job name,
thread number, and file number. If you want to share
randrepeat=bool For random IO workloads, seed the generator in a predictable
way so that results are repeatable across repetitions.
+randseed=int Seed the random number generators based on this seed value, to
+ be able to control what sequence of output is being generated.
+ If not set, the random sequence depends on the randrepeat
+ setting.
+
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
Unless specific nrfiles and filesize options are given,
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. 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
+ size of the given files or devices. If the files 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.
+io_limit=int Normally fio operates within the region set by 'size', which
+ means that the 'size' option sets both the region and size of
+ IO to be performed. Sometimes that is not what you want. With
+ this option, it is possible to define just the amount of IO
+ that fio should do. For instance, if 'size' is set to 20G and
+ 'io_limit' is set to 5G, fio will perform IO within the first
+ 20G but exit when 5G have been done.
+
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.
+file_append=bool Perform IO after the end of the file. Normally fio will
+ operate within the size of a file. If this option is set, then
+ fio will append to the file instead. This has identical
+ behavior to setting offset to the size of a file. This option
+ is ignored on non-regular files.
+
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
can be given for both read and writes. If a single int is
given, it will apply to both. If a second int is specified
after a comma, it will apply to writes only. In other words,
- the format is either bs=read_and_write or bs=read,write.
- bs=4k,8k will thus use 4k blocks for reads, and 8k blocks
- for writes. If you only wish to set the write size, you
+ the format is either bs=read_and_write or bs=read,write,trim.
+ bs=4k,8k will thus use 4k blocks for reads, 8k blocks for
+ writes, and 8k for trims. You can terminate the list with
+ a trailing comma. bs=4k,8k, would use the default value for
+ trims.. If you only wish to set the write size, you
can do so by passing an empty read size - bs=,8k will set
8k for writes and leave the read default value.
may be used as a block range. This typically wont work with
direct IO, as that normally requires sector alignment.
+bs_is_seq_rand If this option is set, fio will use the normal read,write
+ blocksize settings as sequential,random instead. Any random
+ read or write will use the WRITE blocksize settings, and any
+ sequential read or write will use the READ blocksize setting.
+
zero_buffers If this option is given, fio will init the IO buffers to
all zeroes. The default is to fill them with random data.
+ The resulting IO buffers will not be completely zeroed,
+ unless scramble_buffers is also turned off.
refill_buffers If this option is given, fio will refill the IO buffers
on every submit. The default is to only fill it at init
alternate random and zeroed data throughout the IO
buffer.
+buffer_pattern=str If set, fio will fill the io buffers with this pattern.
+ If not set, the contents of io buffers is defined by the other
+ options related to buffer contents. The setting can be any
+ pattern of bytes, and can be prefixed with 0x for hex values.
+
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
vsync Basic readv(2) or writev(2) IO.
+ psyncv Basic preadv(2) or pwritev(2) IO.
+
libaio Linux native asynchronous io. Note that Linux
may only support queued behaviour with
non-buffered IO (set direct=1 or buffered=0).
O_DIRECT. Note that ZFS on Solaris doesn't support direct io.
On Windows the synchronous ioengines don't support direct io.
+atomic=bool If value is true, attempt to use atomic direct IO. Atomic
+ writes are guaranteed to be stable once acknowledged by
+ the operating system. Only Linux supports O_ATOMIC right
+ now.
+
buffered=bool If value is true, use buffered io. This is the opposite
of the 'direct' option. Defaults to true.
caps the file size at real_size - offset.
offset_increment=int If this is provided, then the real offset becomes
- the offset + offset_increment * thread_number, where the
- thread number is a counter that starts at 0 and is incremented
- for each job. This option is useful if there are several jobs
- which are intended to operate on a file in parallel in disjoint
- segments, with even spacing between the starting points.
+ offset + offset_increment * thread_number, where the thread
+ number is a counter that starts at 0 and is incremented for
+ each sub-job (i.e. when numjobs option is specified). This
+ option is useful if there are several jobs which are intended
+ to operate on a file in parallel disjoint segments, with
+ even spacing between the starting points.
+
+number_ios=int Fio will normally perform IOs until it has exhausted the size
+ of the region set by size=, or if it exhaust the allocated
+ time (or hits an error condition). With this setting, the
+ range/size can be set independently of the number of IOs to
+ perform. When fio reaches this number, it will exit normally
+ and report status.
fsync=int If writing to a file, issue a sync of the dirty data
for every number of blocks given. For example, if you give
is fully random. It can be set from anywhere from 0 to 100.
Setting it to 0 would make the workload fully sequential. Any
setting in between will result in a random mix of sequential
- and random IO, at the given percentages.
+ and random IO, at the given percentages. It is possible to
+ set different values for reads, writes, and trim. To do so,
+ simply use a comma separated list. See blocksize.
-percentage_sequential=int See percentage_random. It is guaranteed that
- they add up to 100. The later setting has priority, each
- will adjust the other.
-
norandommap Normally fio will cover every block of the file when doing
random IO. If this option is given, fio will just get a
new random offset without looking at past io history. This
to sleeping for the rest of the period specified by
thinktime.
-thinktime_blocks
+thinktime_blocks=int
Only valid if thinktime is set - control how many blocks
to issue, before waiting 'thinktime' usecs. If not set,
defaults to 1 which will make fio wait 'thinktime' usecs
- after every block.
+ after every block. This effectively makes any queue depth
+ setting redundant, since no more than 1 IO will be queued
+ before we have to complete it and do our thinktime. In
+ other words, this setting effectively caps the queue depth
+ if the latter is larger.
rate=int Cap the bandwidth used by this job. The number is in bytes/sec,
the normal suffix rules apply. You can use rate=500k to limit
as rate, just specified independently of bandwidth. If the
job is given a block size range instead of a fixed value,
the smallest block size is used as the metric. The same format
- as rate is used for read vs write seperation.
+ as rate is used for read vs write separation.
rate_iops_min=int If fio doesn't meet this rate of IO, it will cause
the job to exit. The same format as rate is used for read vs
- write seperation.
+ write separation.
+
+latency_target=int If set, fio will attempt to find the max performance
+ point that the given workload will run at while maintaining a
+ latency below this target. The values is given in microseconds.
+ See latency_window and latency_percentile
+
+latency_window=int Used with latency_target to specify the sample window
+ that the job is run at varying queue depths to test the
+ performance. The value is given in microseconds.
+
+latency_percentile=float The percentage of IOs that must fall within the
+ criteria specified by latency_target and latency_window. If not
+ set, this defaults to 100.0, meaning that all IOs must be equal
+ or below to the value set by latency_target.
max_latency=int If set, fio will exit the job if it exceeds this maximum
latency. It will exit with an ETIME error.
allows a range of CPUs. Say you wanted a binding to CPUs
1, 5, and 8-15, you would set cpus_allowed=1,5,8-15.
+cpus_allowed_policy=str Set the policy of how fio distributes the CPUs
+ specified by cpus_allowed or cpumask. Two policies are
+ supported:
+
+ shared All jobs will share the CPU set specified.
+ split Each job will get a unique CPU from the CPU set.
+
+ 'shared' is the default behaviour, if the option isn't
+ specified. If split is specified, then fio will will assign
+ one cpu per job. If not enough CPUs are given for the jobs
+ listed, then fio will roundrobin the CPUs in the set.
+
numa_cpu_nodes=str Set this job running on spcified NUMA nodes' CPUs. The
arguments allow comma delimited list of cpu numbers,
A-B ranges, or 'all'. Note, to enable numa options support,
to repeat the same workload a given number of times. Defaults
to 1.
+verify_only Do not perform specified workload---only verify data still
+ matches previous invocation of this workload. This option
+ allows one to check data multiple times at a later date
+ without overwriting it. This option makes sense only for
+ workloads that write data, and does not support workloads
+ with the time_based option set.
+
do_verify=bool Run the verify phase after a write phase. Only makes sense if
verify is set. Defaults to 1.
crc7 Use a crc7 sum of the data area and store
it in the header of each block.
+ xxhash Use xxhash as the checksum function. Generally
+ the fastest software checksum that fio
+ supports.
+
sha512 Use sha512 as the checksum function.
sha256 Use sha256 as the checksum function.
meta Write extra information about each io
(timestamp, block number etc.). The block
- number is verified. See also verify_pattern.
+ number is verified. The io sequence number is
+ verified for workloads that write data.
+ See also verify_pattern.
null Only pretend to verify. Useful for testing
internals with ioengine=null, not for much
holding this meta data. If this option is enabled, fio
will write only N blocks before verifying these blocks.
- will verify the previously written blocks before continuing
- to write new ones.
-
verify_backlog_batch=int Control how many blocks fio will verify
if verify_backlog is set. If not set, will default to
the value of verify_backlog (meaning the entire queue
blocks will be verified more than once.
stonewall
-wait_for_previous Wait for preceeding jobs in the job file to exit, before
+wait_for_previous Wait for preceding 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.
replay_redirect=str While replaying I/O patterns using read_iolog the
default behavior is to replay the IOPS onto the major/minor
device that each IOP was recorded from. This is sometimes
- undesireable because on a different machine those major/minor
+ undesirable because on a different machine those major/minor
numbers can map to a different device. Changing hardware on
the same system can also result in a different major/minor
mapping. Replay_redirect causes all IOPS to be replayed onto
jobs in their lifetime. The included fio_generate_plots
script uses gnuplot to turn these text files into nice
graphs. See write_lat_log for behaviour of given
- filename. For this option, the suffix is _bw.log.
+ filename. For this option, the suffix is _bw.x.log, where
+ x is the index of the job (1..N, where N is the number of
+ jobs).
write_lat_log=str Same as write_bw_log, except that this option stores io
submission, completion, and total latencies instead. If no
write_lat_log=foo
- The actual log names will be foo_slat.log, foo_clat.log,
- 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.
+ The actual log names will be foo_slat.x.log, foo_clat.x.log,
+ and foo_lat.x.log, where x is the index of the job (1..N,
+ where N is the number of jobs). This helps fio_generate_plot
+ fine the logs automatically.
write_iops_log=str Same as write_bw_log, but writes IOPS. If no filename is
given with this option, the default filename of
- "jobname_type.log" is used. Even if the filename is given,
- fio will still append the type of log.
+ "jobname_type.x.log" is used,where x is the index of the job
+ (1..N, where N is the number of jobs). Even if the filename
+ is given, fio will still append the type of log.
log_avg_msec=int By default, fio will log an entry in the iops, latency,
or bw log for every IO that completes. When writing to the
specified period of time, reducing the resolution of the log.
Defaults to 0.
+log_offset=int If this is set, the iolog options will include the byte
+ offset for the IO entry as well as the other data values.
+
+log_compression=int If this is set, fio will compress the IO logs as
+ it goes, to keep the memory footprint lower. When a log
+ reaches the specified size, that chunk is removed and
+ compressed in the background. Given that IO logs are
+ fairly highly compressible, this yields a nice memory
+ savings for longer runs. The downside is that the
+ compression will consume some background CPU cycles, so
+ it may impact the run. This, however, is also true if
+ the logging ends up consuming most of the system memory.
+ So pick your poison. The IO logs are saved normally at the
+ end of a run, by decompressing the chunks and storing them
+ in the specified log file. This feature depends on the
+ availability of zlib.
+
+log_store_compressed=bool If set, and log_compression is also set,
+ fio will store the log files in a compressed format. They
+ can be decompressed with fio, using the --inflate-log
+ command line parameter. The files will be stored with a
+ .fz suffix.
+
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.
The amount specified is per worker.
exec_prerun=str Before running this job, issue the command specified
- through system(3).
+ through system(3). Output is redirected in a file called
+ jobname.prerun.txt.
exec_postrun=str After the job completes, issue the command specified
- though system(3).
+ though system(3). Output is redirected in a file called
+ jobname.postrun.txt.
ioscheduler=str Attempt to switch the device hosting the file to the specified
io scheduler before running.
[cpu] cpuchunks=int Split the load into cycles of the given time. In
microseconds.
+[cpu] exit_on_io_done=bool Detect when IO threads are done, then exit.
+
[netsplice] hostname=str
[net] hostname=str The host name or IP address to use for TCP or UDP based IO.
If the job is a TCP listener or UDP reader, the hostname is not
- used and must be omitted.
+ used and must be omitted unless it is a valid UDP multicast
+ address.
[netsplice] port=int
[net] port=int The TCP or UDP port to bind to or connect to.
+[netsplice] interface=str
+[net] interface=str The IP address of the network interface used to send or
+ receive UDP multicast
+
+[netsplice] ttl=int
+[net] ttl=int Time-to-live value for outgoing UDP multicast packets.
+ Default: 1
+
[netsplice] nodelay=bool
[net] nodelay=bool Set TCP_NODELAY on TCP connections.
[net] proto=str The network protocol to use. Accepted values are:
tcp Transmission control protocol
+ tcpv6 Transmission control protocol V6
udp User datagram protocol
+ udpv6 User datagram protocol V6
unix UNIX domain socket
When the protocol is TCP or UDP, the port must also be given,
[net] listen For TCP network connections, tell fio to listen for incoming
connections rather than initiating an outgoing connection. The
hostname must be omitted if this option is used.
-[net] pingpong Normal a network writer will just continue writing data, and
+[net] pingpong Normaly a network writer will just continue writing data, and
a network reader will just consume packages. If pingpong=1
is set, a writer will send its normal payload to the reader,
then wait for the reader to send the same payload back. This
and completion latencies then measure local time spent
sending or receiving, and the completion latency measures
how long it took for the other end to receive and send back.
+ For UDP multicast traffic pingpong=1 should only be set for a
+ single reader when multiple readers are listening to the same
+ address.
[e4defrag] donorname=str
File will be used as a block donor(swap extents between files)
M Running, doing mixed sequential reads/writes.
m Running, doing mixed random reads/writes.
F Running, currently waiting for fsync()
+ f Running, finishing up (writing IO logs, etc)
V Running, doing verification of written data.
E Thread exited, not reaped by main thread yet.
_ Thread reaped, or
X Thread reaped, exited with an error.
K Thread reaped, exited due to signal.
+Fio will condense the thread string as not to take up more space on the
+command line as is needed. For instance, if you have 10 readers and 10
+writers running, the output would look like this:
+
+Jobs: 20 (f=20): [R(10),W(10)] [4.0% done] [2103MB/0KB/0KB /s] [538K/0/0 iops] [eta 57m:36s]
+
+Fio will still maintain the ordering, though. So the above means that jobs
+1..10 are readers, and 11..20 are writers.
+
The other values are fairly self explanatory - number of threads
currently running and doing io, rate of io since last check (read speed
listed first, then write speed), and the estimated completion percentage
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 (dependent on continue_on_error, default off): total # errors, first error code
- Additional Info (dependant on description being set): Text description
+ Additional Info (dependent 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:
projects / fio.git / blobdiff