CPU mask of other jobs.
.. option:: job_start_clock_id=int
- The clock_id passed to the call to `clock_gettime` used to record job_start
- in the `json` output format. Default is 0, or CLOCK_REALTIME.
+
+ The clock_id passed to the call to `clock_gettime` used to record
+ job_start in the `json` output format. Default is 0, or CLOCK_REALTIME.
Target file/device
On Windows, disk devices are accessed as :file:`\\\\.\\PhysicalDrive0` for
the first device, :file:`\\\\.\\PhysicalDrive1` for the second etc.
- Note: Windows and FreeBSD prevent write access to areas
+ Note: Windows and FreeBSD (refer to geom(4)) prevent write access to areas
of the disk containing in-use data (e.g. filesystems).
The filename "`-`" is a reserved name, meaning *stdin* or *stdout*. Which
.. option:: unlink=bool
- Unlink the job files when done. Not the default, as repeated runs of that
+ Unlink (delete) the job files when done. Not the default, as repeated runs of that
job would then waste time recreating the file set again and again. Default:
false.
.. option:: unlink_each_loop=bool
- Unlink job files after each iteration or loop. Default: false.
+ Unlink (delete) job files after each iteration or loop. Default: false.
.. option:: zonemode=str
**none**
The :option:`zonerange`, :option:`zonesize`,
- :option `zonecapacity` and option:`zoneskip`
+ :option:`zonecapacity` and :option:`zoneskip`
parameters are ignored.
**strided**
I/O happens in a single zone until
:option:`zonesize` bytes have been transferred.
After that number of bytes has been
transferred processing of the next zone
- starts. :option `zonecapacity` is ignored.
+ starts. :option:`zonecapacity` is ignored.
**zbd**
Zoned block device mode. I/O happens
sequentially in each zone, even if random I/O
Comma-separated ranges may be specified for reads, writes, and trims as
described in :option:`blocksize`.
- Example: ``bsrange=1k-4k,2k-8k``.
+ Example: ``bsrange=1k-4k,2k-8k`` also the ':' delimiter ``bsrange=1k:4k,2k:8k``.
.. option:: bssplit=str[,str][,str]
.. option:: ioengine=str
- Defines how the job issues I/O to the file. The following types are defined:
+ fio supports 2 kinds of performance measurement: I/O and file/directory operation.
+
+ I/O engines define how the job issues I/O to the file. The following types are defined:
**sync**
Basic :manpage:`read(2)` or :manpage:`write(2)`
absolute or relative. See :file:`engines/skeleton_external.c` for
details of writing an external I/O engine.
- **filecreate**
- Simply create the files and do no I/O to them. You still need to
- set `filesize` so that all the accounting still occurs, but no
- actual I/O will be done other than creating the file.
-
- **filestat**
- Simply do stat() and do no I/O to the file. You need to set 'filesize'
- and 'nrfiles', so that files will be created.
- This engine is to measure file lookup and meta data access.
-
- **filedelete**
- Simply delete the files by unlink() and do no I/O to them. You need to set 'filesize'
- and 'nrfiles', so that the files will be created.
- This engine is to measure file delete.
-
**libpmem**
Read and write using mmap I/O to a file on a filesystem
mounted with DAX on a persistent memory device through the PMDK
several instances to access the same device or file
simultaneously, but allow it for threads.
+ File/directory operation engines define how the job operates file or directory. The
+ following types are defined:
+
+ **filecreate**
+ Simply create the files and do no I/O to them. You still need to
+ set `filesize` so that all the accounting still occurs, but no
+ actual I/O will be done other than creating the file.
+ Example job file: filecreate-ioengine.fio.
+
+ **filestat**
+ Simply do stat() and do no I/O to the file. You need to set 'filesize'
+ and 'nrfiles', so that files will be created.
+ This engine is to measure file lookup and meta data access.
+ Example job file: filestat-ioengine.fio.
+
+ **filedelete**
+ Simply delete the files by unlink() and do no I/O to them. You need to set 'filesize'
+ and 'nrfiles', so that the files will be created.
+ This engine is to measure file delete.
+ Example job file: filedelete-ioengine.fio.
+
+ **dircreate**
+ Simply create the directories and do no I/O to them. You still need to
+ set `filesize` so that all the accounting still occurs, but no
+ actual I/O will be done other than creating the directories.
+ Example job file: dircreate-ioengine.fio.
+
+ **dirstat**
+ Simply do stat() and do no I/O to the directories. You need to set 'filesize'
+ and 'nrfiles', so that directories will be created.
+ This engine is to measure directory lookup and meta data access.
+ Example job file: dirstat-ioengine.fio.
+
+ **dirdelete**
+ Simply delete the directories by rmdir() and do no I/O to them. You need to set 'filesize'
+ and 'nrfiles', so that the directories will be created.
+ This engine is to measure directory delete.
+ Example job file: dirdelete-ioengine.fio.
+
+ For file and directory operation engines, there is no I/O throughput, then the
+ statistics data in report have different meanings. The meaningful output indexes are: 'iops' and 'clat'.
+ 'bw' is meaningless. Refer to section: "Interpreting the output" for more details.
+
+
I/O engine specific parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
want fio to use placement identifier only at indices 0, 2 and 5 specify
``fdp_pli=0,2,5``.
-.. option:: md_per_io_size=int : [io_uring_cmd]
+.. option:: md_per_io_size=int : [io_uring_cmd] [xnvme]
Size in bytes for separate metadata buffer per IO. Default: 0.
-.. option:: pi_act=int : [io_uring_cmd]
+.. option:: pi_act=int : [io_uring_cmd] [xnvme]
Action to take when nvme namespace is formatted with protection
information. If this is set to 1 and namespace is formatted with
it will use the default slower generator.
(see: https://github.com/intel/isa-l)
-.. option:: pi_chk=str[,str][,str] : [io_uring_cmd]
+.. option:: pi_chk=str[,str][,str] : [io_uring_cmd] [xnvme]
Controls the protection information check. This can take one or more
of these values. Default: none.
**APPTAG**
Enables protection information checking of application tag field.
-.. option:: apptag=int : [io_uring_cmd]
+.. option:: apptag=int : [io_uring_cmd] [xnvme]
Specifies logical block application tag value, if namespace is
formatted to use end to end protection information. Default: 0x1234.
-.. option:: apptag_mask=int : [io_uring_cmd]
+.. option:: apptag_mask=int : [io_uring_cmd] [xnvme]
Specifies logical block application tag mask value, if namespace is
formatted to use end to end protection information. Default: 0xffff.
+.. option:: num_range=int : [io_uring_cmd]
+
+ For trim command this will be the number of ranges to trim per I/O
+ request. The number of logical blocks per range is determined by the
+ :option:`bs` option which should be a multiple of logical block size.
+ This cannot be used with read or write. Note that setting this
+ option > 1, :option:`log_offset` will not be able to log all the
+ offsets. Default: 1.
+
.. option:: cpuload=int : [cpuio]
Attempt to use the specified percentage of CPU cycles. This is a mandatory
User datagram protocol V6.
**unix**
UNIX domain socket.
+ **vsock**
+ VSOCK protocol.
- When the protocol is TCP or UDP, the port must also be given, as well as the
- hostname if the job is a TCP listener or UDP reader. For unix sockets, the
+ When the protocol is TCP, UDP or VSOCK, the port must also be given, as well as the
+ hostname if the job is a TCP or VSOCK listener or UDP reader. For unix sockets, the
normal :option:`filename` option should be used and the port is invalid.
+ When the protocol is VSOCK, the :option:`hostname` is the CID of the remote VM.
.. option:: listen : [netsplice] [net]
.. option:: sg_write_mode=str : [sg]
- Specify the type of write commands to issue. This option can take three values:
+ Specify the type of write commands to issue. This option can take ten values:
**write**
This is the default where write opcodes are issued as usual.
I/O rate
~~~~~~~~
+.. option:: thinkcycles=int
+
+ Stall the job for the specified number of cycles after an I/O has completed before
+ issuing the next. May be used to simulate processing being done by an application.
+ This is not taken into account for the time to be waited on for :option:`thinktime`.
+ Might not have any effect on some platforms, this can be checked by trying a setting
+ a high enough amount of thinkcycles.
+
.. option:: thinktime=time
Stall the job for the specified period of time after an I/O has completed before issuing the
.. option:: rate_cycle=int
- Average bandwidth for :option:`rate` and :option:`rate_min` over this number
- of milliseconds. Defaults to 1000.
+ Average bandwidth for :option:`rate_min` and :option:`rate_iops_min`
+ over this number of milliseconds. Defaults to 1000.
I/O latency
.. option:: per_job_logs=bool
- If set, this generates bw/clat/iops log with per file private filenames. If
- not set, jobs with identical names will share the log filename. Default:
- true.
+ If set to true, fio generates bw/clat/iops logs with per job unique
+ filenames. If set to false, jobs with identical names will share a log
+ filename. Note that when this option is set to false log files will be
+ opened in append mode and if log files already exist the previous
+ contents will not be overwritten. Default: true.
.. option:: group_reporting
same reporting group, unless if separated by a :option:`stonewall`, or by
using :option:`new_group`.
- NOTE: When :option: `group_reporting` is used along with `json` output,
- there are certain per-job properties which can be different between jobs
- but do not have a natural group-level equivalent. Examples include
- `kb_base`, `unit_base`, `sig_figs`, `thread_number`, `pid`, and
- `job_start`. For these properties, the values for the first job are
- recorded for the group.
+ NOTE: When :option:`group_reporting` is used along with `json` output,
+ there are certain per-job properties which can be different between jobs
+ but do not have a natural group-level equivalent. Examples include
+ `kb_base`, `unit_base`, `sig_figs`, `thread_number`, `pid`, and
+ `job_start`. For these properties, the values for the first job are
+ recorded for the group.
.. option:: new_group
.. option:: log_avg_msec=int
- By default, fio will log an entry in the iops, latency, or bw log for every
- I/O that completes. When writing to the disk log, that can quickly grow to a
- very large size. Setting this option makes fio average the each log entry
- over the specified period of time, reducing the resolution of the log. See
- :option:`log_max_value` as well. Defaults to 0, logging all entries.
- Also see `Log File Formats`_.
+ By default, fio will log an entry in the iops, latency, or bw log for
+ every I/O that completes. When writing to the disk log, that can
+ quickly grow to a very large size. Setting this option directs fio to
+ instead record an average over the specified duration for each log
+ entry, reducing the resolution of the log. When the job completes, fio
+ will flush any accumulated latency log data, so the final log interval
+ may not match the value specified by this option and there may even be
+ duplicate timestamps. See :option:`log_window_value` as well. Defaults
+ to 0, logging entries for each I/O. Also see `Log File Formats`_.
.. option:: log_hist_msec=int
histogram logs contain 1216 latency bins. See :option:`write_hist_log`
and `Log File Formats`_.
-.. option:: log_max_value=bool
+.. option:: log_window_value=str, log_max_value=str
+
+ If :option:`log_avg_msec` is set, fio by default logs the average over that
+ window. This option determines whether fio logs the average, maximum or
+ both the values over the window. This only affects the latency logging,
+ as both average and maximum values for iops or bw log will be same.
+ Accepted values are:
+
+ **avg**
+ Log average value over the window. The default.
+
+ **max**
+ Log maximum value in the window.
- If :option:`log_avg_msec` is set, fio logs the average over that window. If
- you instead want to log the maximum value, set this option to 1. Defaults to
- 0, meaning that averaged values are logged.
+ **both**
+ Log both average and maximum value over the window.
+
+ **0**
+ Backward-compatible alias for **avg**.
+
+ **1**
+ Backward-compatible alias for **max**.
.. option:: log_offset=bool
commit if available) functions were completed to when the I/O's
completion was reaped by fio.
+ For file and directory operation engines, **clat** denotes the time
+ to complete one file or directory operation.
+
+ **filecreate engine**:the time cost to create a new file
+
+ **filestat engine**: the time cost to look up an existing file
+
+ **filedelete engine**:the time cost to delete a file
+
+ **dircreate engine**: the time cost to create a new directory
+
+ **dirstat engine**: the time cost to look up an existing directory
+
+ **dirdelete engine**: the time cost to delete a directory
+
**lat**
Total latency. Same names as slat and clat, this denotes the time from
when fio created the I/O unit to completion of the I/O operation.
are on the same disk, since they are then competing for disk
access.
+ For file and directory operation engines, **bw** is meaningless.
+
**iops**
IOPS statistics based on measurements from discrete intervals.
For details see the description for bw above. See
:option:`iopsavgtime` to control the duration of the intervals.
Same values reported here as for bw except for percentage.
+ For file and directory operation engines, **iops** is the most
+ fundamental index to denote the performance.
+ It means how many files or directories can be operated per second.
+
+ **filecreate engine**:number of files can be created per second
+
+ **filestat engine**: number of files can be looked up per second
+
+ **filedelete engine**:number of files can be deleted per second
+
+ **dircreate engine**: number of directories can be created per second
+
+ **dirstat engine**: number of directories can be looked up per second
+
+ **dirdelete engine**: number of directories can be deleted per second
+
**lat (nsec/usec/msec)**
The distribution of I/O completion latencies. This is the time from when
I/O leaves fio and when it gets completed. Unlike the separate
by the ioengine specific :option:`cmdprio_percentage`.
Fio defaults to logging every individual I/O but when windowed logging is set
-through :option:`log_avg_msec`, either the average (by default) or the maximum
-(:option:`log_max_value` is set) *value* seen over the specified period of time
-is recorded. Each *data direction* seen within the window period will aggregate
-its values in a separate row. Further, when using windowed logging the *block
-size* and *offset* entries will always contain 0.
+through :option:`log_avg_msec`, either the average (by default), the maximum
+(:option:`log_window_value` is set to max) *value* seen over the specified period
+of time, or both the average *value* and maximum *value1* (:option:`log_window_value`
+is set to both) is recorded. The log file format when both the values are reported
+takes this form:
+
+ *time* (`msec`), *value*, *value1*, *data direction*, *block size* (`bytes`),
+ *offset* (`bytes`), *command priority*
+
+
+Each *data direction* seen within the window period will aggregate its values in a
+separate row. Further, when using windowed logging the *block size* and *offset*
+entries will always contain 0.
Client/Server