X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=fio.1;h=7363a375432f351c031fbeb9e4e243808def8c71;hp=73fdee643af5ec3904064f1edf1015508eaba392;hb=169c098dd3e2081679cf42978ea926e8dac62801;hpb=3bf80dad77448afcb18148e72dc6cfe04bcf7e57 diff --git a/fio.1 b/fio.1 index 73fdee64..7363a375 100644 --- a/fio.1 +++ b/fio.1 @@ -30,7 +30,7 @@ dump of the latency buckets. Limit run time to \fIruntime\fR seconds. .TP .B \-\-bandwidth\-log -Generate per-job bandwidth logs. +Generate aggregate bandwidth logs. .TP .B \-\-minimal Print statistics in a terse, semicolon-delimited format. @@ -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 @@ -282,7 +287,7 @@ Sequential reads. Sequential writes. .TP .B trim -Sequential trim (Linux block devices only). +Sequential trims (Linux block devices only). .TP .B randread Random reads. @@ -291,7 +296,7 @@ Random reads. Random writes. .TP .B randtrim -Random trim (Linux block devices only). +Random trims (Linux block devices only). .TP .B rw, readwrite Mixed sequential reads and writes. @@ -300,10 +305,11 @@ Mixed sequential reads and writes. Mixed random reads and writes. .TP .B trimwrite -Trim and write mixed workload. Blocks will be trimmed first, then the same -blocks will be written to. +Sequential 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 @@ -347,7 +353,7 @@ reasons. Allowed values are 1024 or 1000, with 1024 being the default. .TP .BI unified_rw_reporting \fR=\fPbool Fio normally reports statistics on a per data direction basis, meaning that -read, write, and trim are accounted and reported separately. If this option is +reads, writes, and trims are accounted and reported separately. If this option is set fio sums the results and reports them as "mixed" instead. .TP .BI randrepeat \fR=\fPbool @@ -390,9 +396,27 @@ available on Linux. If using ZFS on Solaris this must be set to 'none' because ZFS doesn't support it. Default: 'posix'. .RE .TP -.BI fadvise_hint \fR=\fPbool +.BI fadvise_hint \fR=\fPstr Use \fBposix_fadvise\fR\|(2) to advise the kernel what I/O patterns -are likely to be issued. Default: true. +are likely to be issued. Accepted values are: +.RS +.RS +.TP +.B 0 +Backwards compatible hint for "no hint". +.TP +.B 1 +Backwards compatible hint for "advise with fio workload type". This +uses \fBFADV_RANDOM\fR for a random workload, and \fBFADV_SEQUENTIAL\fR +for a sequential workload. +.TP +.B sequential +Advise using \fBFADV_SEQUENTIAL\fR +.TP +.B random +Advise using \fBFADV_RANDOM\fR +.RE +.RE .TP .BI fadvise_stream \fR=\fPint Use \fBposix_fadvise\fR\|(2) to advise the kernel what stream ID the @@ -566,10 +590,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 +621,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 @@ -604,7 +643,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 @@ -614,9 +653,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 @@ -638,7 +674,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 @@ -698,8 +735,14 @@ properly. Read, write and erase an MTD character device (e.g., /dev/mtd0). Discards are 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 +and discarding before overwriting. The trimwrite mode works well for this constraint. +.TP +.B pmemblk +Read and write through the NVML libpmemblk interface. +.TP +.B dev-dax +Read and write through a DAX device exposed from persistent memory. .RE .P .RE @@ -742,7 +785,7 @@ Example #1: \fBiodepth_batch_complete_max\fR= .RE -which means that we will retrieve at leat 1 IO and up to the +which means that we will retrieve at least 1 IO and up to the whole submitted queue depth. If none of IO has been completed yet, we will wait. @@ -1117,6 +1160,50 @@ logging results, thus minimizing the runtime required for stable results. Note that the \fBramp_time\fR is considered lead in time for a job, thus it will increase the total runtime if a special timeout or runtime is specified. .TP +.BI steadystate \fR=\fPstr:float "\fR,\fP ss" \fR=\fPstr:float +Define the criterion and limit for assessing steady state performance. The +first parameter designates the criterion whereas the second parameter sets the +threshold. When the criterion falls below the threshold for the specified +duration, the job will stop. For example, iops_slope:0.1% will direct fio +to terminate the job when the least squares regression slope falls below 0.1% +of the mean IOPS. If group_reporting is enabled this will apply to all jobs in +the group. All assessments are carried out using only data from the rolling +collection window. Threshold limits can be expressed as a fixed value or as a +percentage of the mean in the collection window. Below are the available steady +state assessment criteria. +.RS +.RS +.TP +.B iops +Collect IOPS data. Stop the job if all individual IOPS measurements are within +the specified limit of the mean IOPS (e.g., iops:2 means that all individual +IOPS values must be within 2 of the mean, whereas iops:0.2% means that all +individual IOPS values must be within 0.2% of the mean IOPS to terminate the +job). +.TP +.B iops_slope +Collect IOPS data and calculate the least squares regression slope. Stop the +job if the slope falls below the specified limit. +.TP +.B bw +Collect bandwidth data. Stop the job if all individual bandwidth measurements +are within the specified limit of the mean bandwidth. +.TP +.B bw_slope +Collect bandwidth data and calculate the least squares regression slope. Stop +the job if the slope falls below the specified limit. +.RE +.RE +.TP +.BI steadystate_duration \fR=\fPtime "\fR,\fP ss_dur" \fR=\fPtime +A rolling window of this duration will be used to judge whether steady state +has been reached. Data will be collected once per second. The default is 0 +which disables steady state detection. +.TP +.BI steadystate_ramp_time \fR=\fPtime "\fR,\fP ss_ramp" \fR=\fPtime +Allow the job to run for the specified duration before beginning data collection +for checking the steady state job termination criterion. The default is 0. +.TP .BI invalidate \fR=\fPbool Invalidate buffer-cache for the file prior to starting I/O. Default: true. .TP @@ -1130,7 +1217,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). @@ -1180,12 +1267,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. @@ -1222,6 +1311,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. @@ -1297,7 +1389,7 @@ fio will fill 1/2/3/4 bytes of the buffer at the time(it can be either a decimal or a hex number). The verify_pattern if larger than a 32-bit quantity has to be a hex number that starts with either "0x" or "0X". Use with \fBverify\fP=str. Also, verify_pattern supports %o format, which means that for -each block offset will be written and then verifyied back, e.g.: +each block offset will be written and then verified back, e.g.: .RS .RS \fBverify_pattern\fR=%o @@ -1435,13 +1527,13 @@ 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. .TP .BI write_bw_log \fR=\fPstr -If given, write a bandwidth log of the jobs in this job file. Can be used to -store data of the bandwidth of the jobs in their lifetime. The included -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. See the \fBLOG FILE FORMATS\fR +If given, write a bandwidth log for this job. Can be used to store data of the +bandwidth of the jobs in their lifetime. The included 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. +See the \fBLOG FILE FORMATS\fR section. .TP .BI write_lat_log \fR=\fPstr @@ -1452,6 +1544,14 @@ 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_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 @@ -1472,6 +1572,20 @@ 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. @@ -1497,6 +1611,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 @@ -1671,13 +1790,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 @@ -1688,7 +1807,7 @@ 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 (psyncv2)hipri +.BI (pvsync2)hipri Set RWF_HIPRI on IO, indicating to the kernel that it's of higher priority than normal. .TP @@ -2063,7 +2182,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: @@ -2271,13 +2390,20 @@ IO is a TRIM 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 +If windowed logging is enabled through \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