X-Git-Url: https://git.kernel.dk/?a=blobdiff_plain;f=HOWTO;h=ef8f9599942bd08e63a96c8f32a24c6f176892e7;hb=76867621c76ce561c315cd9c8d6b055eddd75d88;hp=b47d7335e30cb68f90ea2881803503755770d290;hpb=0408c206697a60255383a4412391e8375f290f11;p=fio.git diff --git a/HOWTO b/HOWTO index b47d7335..ef8f9599 100644 --- a/HOWTO +++ b/HOWTO @@ -244,6 +244,7 @@ irange Integer range with suffix. Allows value range to be given, such 1k:4k. If the option allows two sets of ranges, they can be specified with a ',' or '/' delimiter: 1k-4k/8k-32k. Also see int. +float_list A list of floating numbers, separated by a ':' character. With the above in mind, here follows the complete list of fio job parameters. @@ -266,7 +267,7 @@ filename=str Fio normally makes up a filename based on the job name, files between threads in a job or several jobs, specify a filename for each of them to override the default. If the ioengine used is 'net', the filename is the host, port, - and protocol to use in the format of =host/port/protocol. + and protocol to use in the format of =host,port,protocol. See ioengine=net for more. If the ioengine is file based, you can specify a number of files by separating the names with a ':' colon. So if you wanted a job to open /dev/sda and /dev/sdb @@ -318,8 +319,12 @@ rw=str Type of io pattern. Accepted values are: a number of IO's to do before getting a new offset, this is one by appending a ':' to the end of the string given. For a random read, it would look like 'rw=randread:8' for - passing in an offset modifier with a value of 8. See the - 'rw_sequencer' option. + passing in an offset modifier with a value of 8. If the + postfix is used with a sequential IO pattern, then the value + specified will be added to the generated offset for each IO. + For instance, using rw=write:4k will skip 4k for every + write. It turns sequential IO into sequential IO with holes. + See the 'rw_sequencer' option. rw_sequencer=str If an offset modifier is given by appending a number to the rw= line, then this option controls how that @@ -476,6 +481,13 @@ refill_buffers If this option is given, fio will refill the IO buffers isn't specified, naturally. If data verification is enabled, refill_buffers is also automatically enabled. +scramble_buffers=bool If refill_buffers is too costly and the target is + using data deduplication, then setting this option will + slightly modify the IO buffer contents to defeat normal + de-dupe attempts. This is not enough to defeat more clever + block compression attempts, but it will stop naive dedupe of + blocks. Default: true. + 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 @@ -512,6 +524,16 @@ ioengine=str Defines how the job issues io to the file. The following libaio Linux native asynchronous io. Note that Linux may only support queued behaviour with non-buffered IO (set direct=1 or buffered=0). + This engine also has a sub-option, + userspace_reap. To set it, use + ioengine=libaio:userspace_reap. Normally, with + the libaio engine in use, fio will use the + io_getevents system call to reap newly returned + events. With this flag turned on, the AIO ring + will be read directly 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). posixaio glibc posix asynchronous io. @@ -569,9 +591,9 @@ ioengine=str Defines how the job issues io to the file. The following for more info on GUASI. rdma The RDMA I/O engine supports both RDMA - memory semantic(RDMA_WRITE/RDMA_READ) and - channel semantic(Send/Recv) in InfiniBand, RoCE - and iWarp environment. + memory semantics (RDMA_WRITE/RDMA_READ) and + channel semantics (Send/Recv) for the + InfiniBand, RoCE and iWARP protocols. external Prefix to specify loading an external IO engine object file. Append the engine @@ -842,6 +864,9 @@ exitall When one job finishes, terminate the rest. The default is bwavgtime=int Average the calculated bandwidth over the given time. Value is specified in milliseconds. +iopsavgtime=int Average the calculated IOPS over the given time. Value + is specified in milliseconds. + create_serialize=bool If true, serialize the file creating for the jobs. This may be handy to avoid interleaving of data files, which may greatly depend on the filesystem @@ -1082,6 +1107,9 @@ write_lat_log=str Same as write_bw_log, except that this option stores io 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. + 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. @@ -1120,6 +1148,18 @@ disable_slat=bool Disable measurements of submission latency numbers. See disable_bw=bool Disable measurements of throughput/bandwidth numbers. See disable_lat. +clat_percentiles=bool Enable the reporting of percentiles of + completion latencies. + +percentile_list=float_list Overwrite the default list of percentiles + for completion latencies. 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 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. + gtod_reduce=bool Enable all of the gettimeofday() reducing options (disable_clat, disable_slat, disable_bw) plus reduce precision of the timeout somewhat to really shrink @@ -1320,27 +1360,43 @@ signify that change. Split up, the format is as follows: - version, jobname, groupid, error + terse version, fio version, jobname, groupid, error READ status: - KB IO, bandwidth (KB/sec), runtime (msec) + Total IO (KB), bandwidth (KB/sec), IOPS, runtime (msec) Submission latency: min, max, mean, deviation Completion latency: min, max, mean, deviation + Completion latency percentiles: 20 fields (see below) Total latency: min, max, mean, deviation Bw: min, max, aggregate percentage of total, mean, deviation WRITE status: - KB IO, bandwidth (KB/sec), runtime (msec) + Total IO (KB), bandwidth (KB/sec), IOPS, runtime (msec) Submission latency: min, max, mean, deviation Completion latency: min, max, mean, deviation + Completion latency percentiles: 20 fields (see below) Total latency: min, max, mean, deviation Bw: min, max, aggregate percentage of total, mean, deviation CPU usage: user, system, context switches, major faults, minor faults IO depths: <=1, 2, 4, 8, 16, 32, >=64 IO latencies microseconds: <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000 IO latencies milliseconds: <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000, 2000, >=2000 + Disk utilization: Disk name, Read ios, write ios, + 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 (dependant 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: + + 1.00%=6112 + +which is the Xth percentile, and the usec latency associated with it. + +For disk utilization, all disks used by fio are shown. So for each disk +there will be a disk utilization section. + 8.0 Trace file format ---------------------