X-Git-Url: https://git.kernel.dk/?a=blobdiff_plain;f=HOWTO;h=8cf8d6506b219e0f9933813616a7d682218adb24;hb=1e7fa601e884ec37014cfaecab3d4b587f0dd395;hp=89f6ee826d08fecbb9d7a5286ea141e336a8e077;hpb=2c870598ec063b3574d0e992d521cae615aa1c73;p=fio.git diff --git a/HOWTO b/HOWTO index 89f6ee82..8cf8d650 100644 --- a/HOWTO +++ b/HOWTO @@ -1996,6 +1996,11 @@ I/O engine 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. + **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 @@ -2029,21 +2034,30 @@ In addition, there are some parameters which are only valid when a specific with the caveat that when used on the command line, they must come after the :option:`ioengine` that defines them is selected. -.. option:: hipri : [io_uring] +.. option:: cmdprio_percentage=int : [io_uring] [libaio] - If this option is set, fio will attempt to use polled IO completions. - Normal IO completions generate interrupts to signal the completion of - IO, polled completions do not. Hence they are require active reaping - by the application. The benefits are more efficient IO for high IOPS - scenarios, and lower latencies for low queue depth IO. + Set the percentage of I/O that will be issued with higher priority by setting + the priority bit. Non-read I/O is likely unaffected by ``cmdprio_percentage``. + This option cannot be used with the `prio` or `prioclass` options. For this + option to set the priority bit properly, NCQ priority must be supported and + enabled and :option:`direct`\=1 option must be used. fio must also be run as + the root user. .. option:: fixedbufs : [io_uring] - If fio is asked to do direct IO, then Linux will map pages for each - IO call, and release them when IO is done. If this option is set, the - pages are pre-mapped before IO is started. This eliminates the need to - map and release for each IO. This is more efficient, and reduces the - IO latency as well. + If fio is asked to do direct IO, then Linux will map pages for each + IO call, and release them when IO is done. If this option is set, the + pages are pre-mapped before IO is started. This eliminates the need to + map and release for each IO. This is more efficient, and reduces the + IO latency as well. + +.. option:: hipri : [io_uring] + + If this option is set, fio will attempt to use polled IO completions. + Normal IO completions generate interrupts to signal the completion of + IO, polled completions do not. Hence they are require active reaping + by the application. The benefits are more efficient IO for high IOPS + scenarios, and lower latencies for low queue depth IO. .. option:: registerfiles : [io_uring] @@ -2083,6 +2097,26 @@ with the caveat that when used on the command line, they must come after the When hipri is set this determines the probability of a pvsync2 I/O being high priority. The default is 100%. +.. option:: nowait : [pvsync2] [libaio] [io_uring] + + By default if a request cannot be executed immediately (e.g. resource starvation, + waiting on locks) it is queued and the initiating process will be blocked until + the required resource becomes free. + + This option sets the RWF_NOWAIT flag (supported from the 4.14 Linux kernel) and + the call will return instantly with EAGAIN or a partial result rather than waiting. + + It is useful to also use ignore_error=EAGAIN when using this option. + + Note: glibc 2.27, 2.28 have a bug in syscall wrappers preadv2, pwritev2. + They return EOPNOTSUP instead of EAGAIN. + + For cached I/O, using this option usually means a request operates only with + cached data. Currently the RWF_NOWAIT flag does not supported for cached write. + + For direct I/O, requests will only succeed if cache invalidation isn't required, + file blocks are fully allocated and the disk request could be issued immediately. + .. option:: cpuload=int : [cpuio] Attempt to use the specified percentage of CPU cycles. This is a mandatory @@ -2248,6 +2282,11 @@ with the caveat that when used on the command line, they must come after the multiple paths exist between the client and the server or in certain loopback configurations. +.. option:: stat_type=str : [filestat] + + Specify stat system call type to measure lookup/getattr performance. + Default is **stat** for :manpage:`stat(2)`. + .. option:: readfua=bool : [sg] With readfua option set to 1, read operations include @@ -2533,6 +2572,13 @@ I/O latency defaults to 100.0, meaning that all I/Os must be equal or below to the value set by :option:`latency_target`. +.. option:: latency_run=bool + + Used with :option:`latency_target`. If false (default), fio will find + the highest queue depth that meets :option:`latency_target` and exit. If + true, fio will continue running and try to meet :option:`latency_target` + by adjusting queue depth. + .. option:: max_latency=time If set, fio will exit the job with an ETIMEDOUT error if it exceeds this @@ -2687,11 +2733,15 @@ Threads, processes and job synchronization Set the I/O priority value of this job. Linux limits us to a positive value between 0 and 7, with 0 being the highest. See man :manpage:`ionice(1)`. Refer to an appropriate manpage for other operating - systems since meaning of priority may differ. + systems since meaning of priority may differ. For per-command priority + setting, see I/O engine specific `cmdprio_percentage` and `hipri_percentage` + options. .. option:: prioclass=int - Set the I/O priority class. See man :manpage:`ionice(1)`. + Set the I/O priority class. See man :manpage:`ionice(1)`. For per-command + priority setting, see I/O engine specific `cmdprio_percentage` and + `hipri_percentage` options. .. option:: cpus_allowed=str @@ -3325,27 +3375,28 @@ Measurements and reporting Disable measurements of throughput/bandwidth numbers. See :option:`disable_lat`. +.. option:: slat_percentiles=bool + + Report submission latency percentiles. Submission latency is not recorded + for synchronous ioengines. + .. option:: clat_percentiles=bool - Enable the reporting of percentiles of completion latencies. This - option is mutually exclusive with :option:`lat_percentiles`. + Report completion latency percentiles. .. option:: lat_percentiles=bool - Enable the reporting of percentiles of I/O latencies. This is similar - to :option:`clat_percentiles`, except that this includes the - submission latency. This option is mutually exclusive with - :option:`clat_percentiles`. + Report total latency percentiles. Total latency is the sum of submission + latency and completion latency. .. option:: percentile_list=float_list - Overwrite the default list of percentiles for completion latencies and - the block error histogram. 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 + Overwrite the default list of percentiles for latencies and the block error + histogram. Each number is a floating point number in the range (0,100], and + the maximum length of the list is 20. Use ``:`` to separate the numbers. 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. + latency durations below which 99.5% and 99.9% of the observed latencies fell, + respectively. .. option:: significant_figures=int @@ -3991,7 +4042,7 @@ only file passed to :option:`read_iolog`. An example would look like:: $ fio --read_iolog=":" --merge_blktrace_file="" Creating only the merged file can be done by passing the command line argument -:option:`merge-blktrace-only`. +:option:`--merge-blktrace-only`. Scaling traces can be done to see the relative impact of any particular trace being slowed down or sped up. :option:`merge_blktrace_scalars` takes in a colon @@ -4114,7 +4165,7 @@ Fio supports a variety of log file formats, for logging latencies, bandwidth, and IOPS. The logs share a common format, which looks like this: *time* (`msec`), *value*, *data direction*, *block size* (`bytes`), - *offset* (`bytes`) + *offset* (`bytes`), *command priority* *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: @@ -4139,6 +4190,9 @@ The entry's *block size* is always in bytes. The *offset* is the position in byt from the start of the file for that particular I/O. The logging of the offset can be toggled with :option:`log_offset`. +*Command priority* is 0 for normal priority and 1 for high priority. This is controlled +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