X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=fio.1;h=8d596fb19105df2e6b3aabcbda171cf462f3157e;hp=0bd1f55b9d39b66769c9996f3adf96f1a85e97b6;hb=3aea75b14510301a80744b417ac08840ccfcf5b3;hpb=29dbd1e5f1f7e3465acaa26a55cc29259f0eb61b diff --git a/fio.1 b/fio.1 index 0bd1f55b..8d596fb1 100644 --- a/fio.1 +++ b/fio.1 @@ -247,6 +247,11 @@ will be used if no other format specifier is given. .RE .P .TP +.BI unique_filename \fR=\fPbool +To avoid collisions between networked clients, fio defaults to prefixing +any generated filenames (with a directory specified) with the source of +the client connecting. To disable this behavior, set this option to 0. +.TP .BI lockfile \fR=\fPstr Fio defaults to not locking any files before it does IO to them. If a file or file descriptor is shared, fio can serialize IO to that file to make the end @@ -304,6 +309,7 @@ Trim and write mixed workload. Blocks will be trimmed first, then the same blocks will be written to. .RE .P +Fio defaults to read if the option is not specified. For mixed I/O, the default split is 50/50. For certain types of io the result may still be skewed a bit, since the speed may be different. It is possible to specify a number of IO's to do before getting a new offset, this is done by @@ -566,10 +572,24 @@ Round robin over opened files (default). .TP .B sequential Do each file in the set sequentially. +.TP +.B zipf +Use a zipfian distribution to decide what file to access. +.TP +.B pareto +Use a pareto distribution to decide what file to access. +.TP +.B gauss +Use a gaussian (normal) distribution to decide what file to access. .RE .P -The number of I/Os to issue before switching to a new file can be specified by -appending `:\fIint\fR' to the service type. +For \fBrandom\fR, \fBroundrobin\fR, and \fBsequential\fR, a postfix can be +appended to tell fio how many I/Os to issue before switching to a new file. +For example, specifying \fBfile_service_type=random:8\fR would cause fio to +issue \fI8\fR I/Os before selecting a new file at random. For the non-uniform +distributions, a floating point postfix can be given to influence how the +distribution is skewed. See \fBrandom_distribution\fR for a description of how +that would work. .RE .TP .BI ioengine \fR=\fPstr @@ -583,6 +603,7 @@ position the I/O location. .TP .B psync Basic \fBpread\fR\|(2) or \fBpwrite\fR\|(2) I/O. +Default on all supported operating systems except for Windows. .TP .B vsync Basic \fBreadv\fR\|(2) or \fBwritev\fR\|(2) I/O. Will emulate queuing by @@ -591,6 +612,9 @@ coalescing adjacent IOs into a single submission. .B pvsync Basic \fBpreadv\fR\|(2) or \fBpwritev\fR\|(2) I/O. .TP +.B pvsync2 +Basic \fBpreadv2\fR\|(2) or \fBpwritev2\fR\|(2) I/O. +.TP .B libaio Linux native asynchronous I/O. This ioengine defines engine specific options. .TP @@ -601,7 +625,7 @@ POSIX asynchronous I/O using \fBaio_read\fR\|(3) and \fBaio_write\fR\|(3). Solaris native asynchronous I/O. .TP .B windowsaio -Windows native asynchronous I/O. +Windows native asynchronous I/O. Default on Windows. .TP .B mmap File is memory mapped with \fBmmap\fR\|(2) and data copied using @@ -611,9 +635,6 @@ File is memory mapped with \fBmmap\fR\|(2) and data copied using \fBsplice\fR\|(2) is used to transfer the data and \fBvmsplice\fR\|(2) to transfer data from user-space to the kernel. .TP -.B syslet-rw -Use the syslet system calls to make regular read/write asynchronous. -.TP .B sg SCSI generic sg v3 I/O. May be either synchronous using the SG_IO ioctl, or if the target is an sg character device, we use \fBread\fR\|(2) and @@ -635,7 +656,8 @@ and send/receive. This ioengine defines engine specific options. .TP .B cpuio Doesn't transfer any data, but burns CPU cycles according to \fBcpuload\fR and -\fBcpucycles\fR parameters. +\fBcpuchunks\fR parameters. A job never finishes unless there is at least one +non-cpuio job. .TP .B guasi The GUASI I/O engine is the Generic Userspace Asynchronous Syscall Interface @@ -697,6 +719,9 @@ treated as erases. Depending on the underlying device type, the I/O may have to go in a certain pattern, e.g., on NAND, writing sequentially to erase blocks and discarding before overwriting. The writetrim mode works well for this constraint. +.TP +.B pmemblk +Read and write through the NVML libpmemblk interface. .RE .P .RE @@ -871,15 +896,51 @@ Zipf distribution .B pareto Pareto distribution .TP +.B gauss +Normal (gaussian) distribution +.TP +.B zoned +Zoned random distribution +.TP .RE -.P -When using a zipf or pareto distribution, an input value is also needed to -define the access pattern. For zipf, this is the zipf theta. For pareto, -it's the pareto power. Fio includes a test program, genzipf, that can be -used visualize what the given input values will yield in terms of hit rates. -If you wanted to use zipf with a theta of 1.2, you would use +When using a \fBzipf\fR or \fBpareto\fR distribution, an input value is also +needed to define the access pattern. For \fBzipf\fR, this is the zipf theta. +For \fBpareto\fR, it's the pareto power. Fio includes a test program, genzipf, +that can be used visualize what the given input values will yield in terms of +hit rates. If you wanted to use \fBzipf\fR with a theta of 1.2, you would use random_distribution=zipf:1.2 as the option. If a non-uniform model is used, -fio will disable use of the random map. +fio will disable use of the random map. For the \fBgauss\fR distribution, a +normal deviation is supplied as a value between 0 and 100. +.P +.RS +For a \fBzoned\fR distribution, fio supports specifying percentages of IO +access that should fall within what range of the file or device. For example, +given a criteria of: +.P +.RS +60% of accesses should be to the first 10% +.RE +.RS +30% of accesses should be to the next 20% +.RE +.RS +8% of accesses should be to to the next 30% +.RE +.RS +2% of accesses should be to the next 40% +.RE +.P +we can define that through zoning of the random accesses. For the above +example, the user would do: +.P +.RS +.B random_distribution=zoned:60/10:30/20:8/30:2/40 +.RE +.P +similarly to how \fBbssplit\fR works for setting ranges and percentages of block +sizes. Like \fBbssplit\fR, it's possible to specify separate zones for reads, +writes, and trims. If just one set is given, it'll apply to all of them. +.RE .TP .BI percentage_random \fR=\fPint For a random workload, set how big a percentage should be random. This defaults @@ -1091,7 +1152,7 @@ Allocation method for I/O unit buffer. Allowed values are: .RS .TP .B malloc -Allocate memory with \fBmalloc\fR\|(3). +Allocate memory with \fBmalloc\fR\|(3). Default memory type. .TP .B shm Use shared memory buffers allocated through \fBshmget\fR\|(2). @@ -1141,12 +1202,14 @@ Terminate all jobs if one job finishes in error. Default: wait for each job to finish. .TP .BI bwavgtime \fR=\fPint -Average bandwidth calculations over the given time in milliseconds. Default: -500ms. +Average bandwidth calculations over the given time in milliseconds. If the job +also does bandwidth logging through \fBwrite_bw_log\fR, then the minimum of +this option and \fBlog_avg_msec\fR will be used. Default: 500ms. .TP .BI iopsavgtime \fR=\fPint -Average IOPS calculations over the given time in milliseconds. Default: -500ms. +Average IOPS calculations over the given time in milliseconds. If the job +also does IOPS logging through \fBwrite_iops_log\fR, then the minimum of +this option and \fBlog_avg_msec\fR will be used. Default: 500ms. .TP .BI create_serialize \fR=\fPbool If true, serialize file creation for the jobs. Default: true. @@ -1183,6 +1246,9 @@ multiple times. Thus it will not work on eg network or splice IO. .BI unlink \fR=\fPbool Unlink job files when done. Default: false. .TP +.BI unlink_each_loop \fR=\fPbool +Unlink job files after each iteration or loop. Default: false. +.TP .BI loops \fR=\fPint Specifies the number of iterations (runs of the same workload) of this job. Default: 1. @@ -1402,7 +1468,8 @@ fio_generate_plots script uses gnuplot to turn these text files into nice graphs. See \fBwrite_lat_log\fR for behaviour of given filename. For this option, the postfix is _bw.x.log, where x is the index of the job (1..N, where N is the number of jobs). If \fBper_job_logs\fR is false, then the -filename will not include the job index. +filename will not include the job index. See the \fBLOG FILE FORMATS\fR +section. .TP .BI write_lat_log \fR=\fPstr Same as \fBwrite_bw_log\fR, but writes I/O completion latencies. If no @@ -1410,27 +1477,50 @@ filename is given with this option, the default filename of "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. If \fBper_job_logs\fR is false, then the filename will -not include the job index. +not include the job index. See the \fBLOG FILE FORMATS\fR section. +.TP +.BI write_hist_log \fR=\fPstr +Same as \fBwrite_lat_log\fR, but writes I/O completion latency histograms. If +no filename is given with this option, the default filename of +"jobname_clat_hist.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. If \fBper_job_logs\fR is false, then the filename will not +include the job index. See the \fBLOG FILE FORMATS\fR section. .TP .BI write_iops_log \fR=\fPstr Same as \fBwrite_bw_log\fR, but writes IOPS. If no filename is given with this option, the default filename of "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. If \fBper_job_logs\fR is false, -then the filename will not include the job index. +then the filename will not include the job index. See the \fBLOG FILE FORMATS\fR +section. .TP .BI log_avg_msec \fR=\fPint By default, fio will log an entry in the iops, latency, or bw log for every IO 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 -\fBlog_max\fR as well. Defaults to 0, logging all entries. +\fBlog_max_value\fR as well. Defaults to 0, logging all entries. .TP -.BI log_max \fR=\fPbool +.BI log_max_value \fR=\fPbool If \fBlog_avg_msec\fR 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. .TP +.BI log_hist_msec \fR=\fPint +Same as \fBlog_avg_msec\fR, but logs entries for completion latency histograms. +Computing latency percentiles from averages of intervals using \fBlog_avg_msec\fR +is innacurate. Setting this option makes fio log histogram entries over the +specified period of time, reducing log sizes for high IOPS devices while +retaining percentile accuracy. See \fBlog_hist_coarseness\fR as well. Defaults +to 0, meaning histogram logging is disabled. +.TP +.BI log_hist_coarseness \fR=\fPint +Integer ranging from 0 to 6, defining the coarseness of the resolution of the +histogram logs enabled with \fBlog_hist_msec\fR. For each increment in +coarseness, fio outputs half as many bins. Defaults to 0, for which histogram +logs contain 1216 latency bins. See the \fBLOG FILE FORMATS\fR section. +.TP .BI log_offset \fR=\fPbool If this is set, the iolog options will include the byte offset for the IO entry as well as the other data values. @@ -1456,6 +1546,11 @@ If set, fio will store the log files in a compressed format. They can be decompressed with fio, using the \fB\-\-inflate-log\fR command line parameter. The files will be stored with a \fB\.fz\fR suffix. .TP +.BI log_unix_epoch \fR=\fPbool +If set, fio will log Unix timestamps to the log files produced by enabling +\fBwrite_type_log\fR for each log type, instead of the default zero-based +timestamps. +.TP .BI block_error_percentiles \fR=\fPbool If set, record errors in trim block-sized units from writes and trims and output a histogram of how many trims it took to get to errors, and what kind of error @@ -1630,13 +1725,13 @@ Some parameters are only valid when a specific ioengine is in use. These are used identically to normal parameters, with the caveat that when used on the command line, they must come after the ioengine. .TP -.BI (cpu)cpuload \fR=\fPint +.BI (cpuio)cpuload \fR=\fPint Attempt to use the specified percentage of CPU cycles. .TP -.BI (cpu)cpuchunks \fR=\fPint +.BI (cpuio)cpuchunks \fR=\fPint Split the load into cycles of the given time. In microseconds. .TP -.BI (cpu)exit_on_io_done \fR=\fPbool +.BI (cpuio)exit_on_io_done \fR=\fPbool Detect when IO threads are done, then exit. .TP .BI (libaio)userspace_reap @@ -1647,6 +1742,10 @@ 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). .TP +.BI (pvsync2)hipri +Set RWF_HIPRI on IO, indicating to the kernel that it's of +higher priority than normal. +.TP .BI (net,netsplice)hostname \fR=\fPstr 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 @@ -1727,6 +1826,9 @@ Preallocate donor's file on init .BI 1: allocate space immediately inside defragment event, and free right after event .RE +.TP +.BI (rbd)clustername \fR=\fPstr +Specifies the name of the ceph cluster. .TP .BI (rbd)rbdname \fR=\fPstr Specifies the name of the RBD. @@ -1735,7 +1837,9 @@ Specifies the name of the RBD. Specifies the name of the Ceph pool containing the RBD. .TP .BI (rbd)clientname \fR=\fPstr -Specifies the username (without the 'client.' prefix) used to access the Ceph cluster. +Specifies the username (without the 'client.' prefix) used to access the Ceph +cluster. If the clustername is specified, the clientname shall be the full +type.id string. If no type. prefix is given, fio will add 'client.' by default. .TP .BI (mtd)skipbad \fR=\fPbool Skip operations against known bad blocks. @@ -1828,7 +1932,9 @@ and standard deviation. .TP .B cpu CPU usage statistics. Includes user and system time, number of context switches -this thread went through and number of major and minor page faults. +this thread went through and number of major and minor page faults. The CPU +utilization numbers are averages for the jobs in that reporting group, while +the context and fault counters are summed. .TP .B IO depths Distribution of I/O depths. Each depth includes everything less than (or equal) @@ -2011,7 +2117,7 @@ This format is not supported in Fio versions => 1.20-rc3. .B Trace file format v2 .RS 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 +It allows one 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: @@ -2145,7 +2251,7 @@ server# \fBfio \-\-server\fR and on the client, we'll fire off the workload: -localbox$ \fBfio \-\-client=server \-\-trigger\-file=/tmp/my\-trigger \-\-trigger-remote="bash \-c \\"echo b > /proc/sysrq-triger\\""\fR +localbox$ \fBfio \-\-client=server \-\-trigger\-file=/tmp/my\-trigger \-\-trigger-remote="bash \-c "echo b > /proc/sysrq-triger""\fR We set \fB/tmp/my-trigger\fR as the trigger file, and we tell fio to execute @@ -2176,6 +2282,65 @@ the files over and load them from there. .RE +.SH LOG FILE FORMATS + +Fio supports a variety of log file formats, for logging latencies, bandwidth, +and IOPS. The logs share a common format, which looks like this: + +.B time (msec), value, data direction, offset + +Time for the log entry is always in milliseconds. The value logged depends +on the type of log, it will be one of the following: + +.P +.PD 0 +.TP +.B Latency log +Value is in latency in usecs +.TP +.B Bandwidth log +Value is in KB/sec +.TP +.B IOPS log +Value is in IOPS +.PD +.P + +Data direction is one of the following: + +.P +.PD 0 +.TP +.B 0 +IO is a READ +.TP +.B 1 +IO is a WRITE +.TP +.B 2 +IO is a TRIM +.PD +.P + +The \fIoffset\fR is the offset, in bytes, from the start of the file, for that +particular IO. The logging of the offset can be toggled with \fBlog_offset\fR. + +If windowed logging is enabled though \fBlog_avg_msec\fR, then fio doesn't log +individual IOs. Instead of logs the average values over the specified +period of time. Since \fIdata direction\fR and \fIoffset\fR are per-IO values, +they aren't applicable if windowed logging is enabled. If windowed logging +is enabled and \fBlog_max_value\fR is set, then fio logs maximum values in +that window instead of averages. + +For histogram logging the logs look like this: + +.B time (msec), data direction, block-size, bin 0, bin 1, ..., bin 1215 + +Where 'bin i' gives the frequency of IO requests with a latency falling in +the i-th bin. See \fBlog_hist_coarseness\fR for logging fewer bins. + +.RE + .SH CLIENT / SERVER Normally you would run fio as a stand-alone application on the machine where the IO workload should be generated. However, it is also possible to @@ -2193,34 +2358,34 @@ for TCP/IP v4, 'ip6' for TCP/IP v6, or 'sock' for a local unix domain socket. 'hostname' is either a hostname or IP address, and 'port' is the port to listen to (only valid for TCP/IP, not a local socket). Some examples: -1) fio \-\-server +1) \fBfio \-\-server\fR Start a fio server, listening on all interfaces on the default port (8765). -2) fio \-\-server=ip:hostname,4444 +2) \fBfio \-\-server=ip:hostname,4444\fR Start a fio server, listening on IP belonging to hostname and on port 4444. -3) fio \-\-server=ip6:::1,4444 +3) \fBfio \-\-server=ip6:::1,4444\fR Start a fio server, listening on IPv6 localhost ::1 and on port 4444. -4) fio \-\-server=,4444 +4) \fBfio \-\-server=,4444\fR Start a fio server, listening on all interfaces on port 4444. -5) fio \-\-server=1.2.3.4 +5) \fBfio \-\-server=1.2.3.4\fR Start a fio server, listening on IP 1.2.3.4 on the default port. -6) fio \-\-server=sock:/tmp/fio.sock +6) \fBfio \-\-server=sock:/tmp/fio.sock\fR Start a fio server, listening on the local socket /tmp/fio.sock. When a server is running, you can connect to it from a client. The client is run with: -fio \-\-local-args \-\-client=server \-\-remote-args +\fBfio \-\-local-args \-\-client=server \-\-remote-args \fR where \-\-local-args are arguments that are local to the client where it is running, 'server' is the connect string, and \-\-remote-args and @@ -2228,12 +2393,12 @@ are sent to the server. The 'server' string follows the same format as it does on the server side, to allow IP/hostname/socket and port strings. You can connect to multiple clients as well, to do that you could run: -fio \-\-client=server2 \-\-client=server2 +\fBfio \-\-client=server2 \-\-client=server2 \fR If the job file is located on the fio server, then you can tell the server to load a local file as well. This is done by using \-\-remote-config: -fio \-\-client=server \-\-remote-config /path/to/file.fio +\fBfio \-\-client=server \-\-remote-config /path/to/file.fio\fR Then fio will open this local (to the server) job file instead of being passed one from the client. @@ -2248,7 +2413,7 @@ host2.your.dns.domain The fio command would then be: -fio \-\-client=host.list +\fBfio \-\-client=host.list \fR In this mode, you cannot input server-specific parameters or job files, and all servers receive the same job file.