HOWTO: make it clear that deviation is standard deviation

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 0808cc3a07e0f53a62c3476b6789f47426917829..b823eaed24a5b84b30bbf2d19ab5f4ef9f089ae0 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -435,6 +435,7 @@ unified_rw_reporting=bool   Fio normally reports statistics on a per
 
 randrepeat=bool        For random IO workloads, seed the generator in a predictable
                way so that results are repeatable across repetitions.
 
 randrepeat=bool        For random IO workloads, seed the generator in a predictable
                way so that results are repeatable across repetitions.

+               Defaults to true.

 
 randseed=int   Seed the random number generators based on this seed value, to
                be able to control what sequence of output is being generated.
 
 randseed=int   Seed the random number generators based on this seed value, to
                be able to control what sequence of output is being generated.


@@ -960,6 +961,8 @@ random_generator=str        Fio supports the following engines for generating
 
                tausworthe      Strong 2^88 cycle random number generator
                lfsr            Linear feedback shift register generator
 
                tausworthe      Strong 2^88 cycle random number generator
                lfsr            Linear feedback shift register generator

+               tausworthe64    Strong 64-bit 2^258 cycle random number
+                               generator

 
                Tausworthe is a strong random number generator, but it
                requires tracking on the side if we want to ensure that
 
                Tausworthe is a strong random number generator, but it
                requires tracking on the side if we want to ensure that


@@ -1198,6 +1201,17 @@ create_only=bool If true, fio will only run the setup phase of the job.
                        that will be done. The actual job contents are not
                        executed.
 
                        that will be done. The actual job contents are not
                        executed.
 

+allow_file_create=bool If true, fio is permitted to create files as part
+               of its workload. This is the default behavior. If this
+               option is false, then fio will error out if the files it
+               needs to use don't already exist. Default: true.
+
+allow_mounted_write=bool       If this isn't set, fio will abort jobs that
+               are destructive (eg that write) to what appears to be a
+               mounted device or partition. This should help catch creating
+               inadvertently destructive tests, not realizing that the test
+               will destroy data on the mounted file system. Default: false.
+

 pre_read=bool  If this is given, files will be pre-read into memory before
                starting the given IO operation. This will also clear
                the 'invalidate' flag, since it is pointless to pre-read
 pre_read=bool  If this is given, files will be pre-read into memory before
                starting the given IO operation. This will also clear
                the 'invalidate' flag, since it is pointless to pre-read


@@ -1267,6 +1281,12 @@ verify=str       If writing to a file, fio can verify the file contents
                                verified for workloads that write data.
                                See also verify_pattern.
 
                                verified for workloads that write data.
                                See also verify_pattern.
 

+                       pattern Verify a strict pattern. Normally fio includes
+                               a header with some basic information and
+                               checksumming, but if this option is set, only
+                               the specific pattern set with 'verify_pattern'
+                               is verified.
+

                        null    Only pretend to verify. Useful for testing
                                internals with ioengine=null, not for much
                                else.
                        null    Only pretend to verify. Useful for testing
                                internals with ioengine=null, not for much
                                else.


@@ -1439,6 +1459,10 @@ replay_align=int Force alignment of IO offsets and lengths in a trace
 replay_scale=int       Scale sector offsets down by this factor when
                replaying traces.
 
 replay_scale=int       Scale sector offsets down by this factor when
                replaying traces.
 

+per_job_logs=bool      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.
+

 write_bw_log=str 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
 write_bw_log=str 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


@@ -1446,7 +1470,8 @@ write_bw_log=str If given, write a bandwidth log of the jobs in this job
                graphs. See write_lat_log for behaviour of given
                filename. For this option, the suffix is _bw.x.log, where
                x is the index of the job (1..N, where N is the number of
                graphs. See write_lat_log for behaviour of given
                filename. For this option, the suffix is _bw.x.log, where
                x is the index of the job (1..N, where N is the number of

-               jobs).
+               jobs). If 'per_job_logs' is false, then the filename will not
+               include the job index.

 
 write_lat_log=str Same as write_bw_log, except that this option stores io
                submission, completion, and total latencies instead. If no
 
 write_lat_log=str Same as write_bw_log, except that this option stores io
                submission, completion, and total latencies instead. If no


@@ -1459,13 +1484,17 @@ write_lat_log=str Same as write_bw_log, except that this option stores io
                The actual log names will be foo_slat.x.log, foo_clat.x.log,
                and foo_lat.x.log, where x is the index of the job (1..N,
                where N is the number of jobs). This helps fio_generate_plot
                The actual log names will be foo_slat.x.log, foo_clat.x.log,
                and foo_lat.x.log, where x is the index of the job (1..N,
                where N is the number of jobs). This helps fio_generate_plot

-               fine the logs automatically.
+               fine the logs automatically. If 'per_job_logs' is false, then
+               the filename will not include the job index.
+

 
 write_iops_log=str Same as write_bw_log, 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
 
 write_iops_log=str Same as write_bw_log, 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.
+               is given, fio will still append the type of log. If
+               'per_job_logs' is false, then the filename will not include
+               the job index.

 
 log_avg_msec=int By default, fio will log an entry in the iops, latency,
                or bw log for every IO that completes. When writing to the
 
 log_avg_msec=int By default, fio will log an entry in the iops, latency,
                or bw log for every IO that completes. When writing to the


@@ -1927,18 +1956,18 @@ Split up, the format is as follows:
        terse version, fio version, jobname, groupid, error
        READ status:
                Total IO (KB), bandwidth (KB/sec), IOPS, runtime (msec)
        terse version, fio version, jobname, groupid, error
        READ status:
                Total IO (KB), bandwidth (KB/sec), IOPS, runtime (msec)

-               Submission latency: min, max, mean, deviation (usec)
-               Completion latency: min, max, mean, deviation (usec)
+               Submission latency: min, max, mean, stdev (usec)
+               Completion latency: min, max, mean, stdev (usec)

                Completion latency percentiles: 20 fields (see below)
                Completion latency percentiles: 20 fields (see below)

-               Total latency: min, max, mean, deviation (usec)
-               Bw (KB/s): min, max, aggregate percentage of total, mean, deviation
+               Total latency: min, max, mean, stdev (usec)
+               Bw (KB/s): min, max, aggregate percentage of total, mean, stdev

        WRITE status:
                Total IO (KB), bandwidth (KB/sec), IOPS, runtime (msec)
        WRITE status:
                Total IO (KB), bandwidth (KB/sec), IOPS, runtime (msec)

-               Submission latency: min, max, mean, deviation (usec)
-               Completion latency: min, max, mean, deviation (usec)
+               Submission latency: min, max, mean, stdev (usec)
+               Completion latency: min, max, mean, stdev(usec)

                Completion latency percentiles: 20 fields (see below)
                Completion latency percentiles: 20 fields (see below)

-               Total latency: min, max, mean, deviation (usec)
-               Bw (KB/s): min, max, aggregate percentage of total, mean, deviation
+               Total latency: min, max, mean, stdev (usec)
+               Bw (KB/s): min, max, aggregate percentage of total, mean, stdev

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