server: fix bug in converting/storing clat percentiles

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 88bd5e6c14f0f1ff356fbab964fd0a12a0a63c61..2e4cdbdf146e17394a8ebcd481097e43846131ba 100644 (file)
--- 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.
        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.
 
 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,
                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
                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 ':<nr>' to the end of the string given.
                For a random read, it would look like 'rw=randread:8' for
                a number of IO's to do before getting a new offset, this is
                one by appending a ':<nr>' 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=<str> line, then this option controls how that
 
 rw_sequencer=str If an offset modifier is given by appending a number to
                the rw=<str> 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.
 
                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
 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).
                        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.
 
 
                        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
                                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
 
                        external Prefix to specify loading an external
                                IO engine object file. Append the engine


@@ -678,10 +700,10 @@ norandommap       Normally fio will cover every block of the file when doing
                blocksizes (via bsrange=) are used, since fio only tracks
                complete rewrites of blocks.
 
                blocksizes (via bsrange=) are used, since fio only tracks
                complete rewrites of blocks.
 

-softrandommap  See norandommap. If fio runs with the random block map enabled
-               and it fails to allocate the map, if this option is set it
-               will continue without a random block map. As coverage will
-               not be as complete as with random maps, this option is
+softrandommap=bool See norandommap. If fio runs with the random block map
+               enabled and it fails to allocate the map, if this option is
+               set it will continue without a random block map. As coverage
+               will not be as complete as with random maps, this option is

                disabled by default.
 
 nice=int       Run the job with the given nice value. See man nice(2).
                disabled by default.
 
 nice=int       Run the job with the given nice value. See man nice(2).


@@ -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.
 
 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
 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.
 
                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.
 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.
 
 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
 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


@@ -1322,13 +1362,13 @@ Split up, the format is as follows:
 
        version, jobname, groupid, error
        READ status:
 
        version, jobname, groupid, error
        READ status:

-               KB IO, bandwidth (KB/sec), runtime (msec)
+               Total IO (KB), bandwidth (KB/sec), runtime (msec)

                Submission latency: min, max, mean, deviation
                Completion latency: min, max, mean, deviation
                Total latency: min, max, mean, deviation
                Bw: min, max, aggregate percentage of total, mean, deviation
        WRITE status:
                Submission latency: min, max, mean, deviation
                Completion latency: min, max, mean, deviation
                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), runtime (msec)

                Submission latency: min, max, mean, deviation
                Completion latency: min, max, mean, deviation
                Total latency: min, max, mean, deviation
                Submission latency: min, max, mean, deviation
                Completion latency: min, max, mean, deviation
                Total latency: min, max, mean, deviation