HOWTO: update to include iolog replay
[fio.git] / HOWTO
diff --git a/HOWTO b/HOWTO
index d18d59b4b824d498104143ff25553d8769cf8ba3..3f8acee15221f321a8838fa907759d3d96455e2e 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -1066,6 +1066,10 @@ random_generator=str     Fio supports the following engines for generating
 
 nice=int       Run the job with the given nice value. See man nice(2).
 
+     On Windows, values less than -15 set the process class to "High";
+     -1 through -15 set "Above Normal"; 1 through 15 "Below Normal";
+     and above 15 "Idle" priority class.
+
 prio=int       Set the io priority value of this job. Linux limits us to
                a positive value between 0 and 7, with 0 being the highest.
                See man ionice(1). Refer to an appropriate manpage for
@@ -1295,7 +1299,7 @@ iopsavgtime=int   Average the calculated IOPS over the given time. Value
                through 'write_iops_log', then the minimum of this option and
                'log_avg_msec' will be used.  Default: 500ms.
 
-create_serialize=bool  If true, serialize the file creating for the jobs.
+create_serialize=bool  If true, serialize the file creation for the jobs.
                        This may be handy to avoid interleaving of data
                        files, which may greatly depend on the filesystem
                        used and even the number of processors in the system.
@@ -1334,6 +1338,8 @@ unlink=bool       Unlink the job files when done. Not the default, as repeated
                runs of that job would then waste time recreating the file
                set again and again.
 
+unlink_each_loop=bool  Unlink job files after each iteration or loop.
+
 loops=int      Run the specified number of iterations of this job. Used
                to repeat the same workload a given number of times. Defaults
                to 1.
@@ -1552,10 +1558,10 @@ read_iolog=str  Open an iolog with the specified file name and replay the
 
 replay_no_stall=int When replaying I/O with read_iolog the default behavior
                is to attempt to respect the time stamps within the log and
-               replay them with the appropriate delay between IOPS.  By
+               replay them with the appropriate delay between IOPS. By
                setting this variable fio will not respect the timestamps and
                attempt to replay them as fast as possible while still
-               respecting ordering.  The result is the same I/O pattern to a
+               respecting ordering. The result is the same I/O pattern to a
                given device, but different timings.
 
 replay_redirect=str While replaying I/O patterns using read_iolog the
@@ -1567,13 +1573,14 @@ replay_redirect=str While replaying I/O patterns using read_iolog the
                mapping.  Replay_redirect causes all IOPS to be replayed onto
                the single specified device regardless of the device it was
                recorded from. i.e. replay_redirect=/dev/sdc would cause all
-               IO in the blktrace to be replayed onto /dev/sdc.  This means
-               multiple devices will be replayed onto a single, if the trace
-               contains multiple devices.  If you want multiple devices to be
-               replayed concurrently to multiple redirected devices you must
-               blkparse your trace into separate traces and replay them with
-               independent fio invocations.  Unfortuantely this also breaks
-               the strict time ordering between multiple device accesses.
+               IO in the blktrace or iolog to be replayed onto /dev/sdc.
+               This means multiple devices will be replayed onto a single
+               device, if the trace contains multiple devices. If you want
+               multiple devices to be replayed concurrently to multiple
+               redirected devices you must blkparse your trace into separate
+               traces and replay them with independent fio invocations.
+               Unfortuantely this also breaks the strict time ordering
+               between multiple device accesses.
 
 replay_align=int       Force alignment of IO offsets and lengths in a trace
                to this power of 2 value.
@@ -1610,6 +1617,14 @@ write_lat_log=str Same as write_bw_log, except that this option stores io
                the filename will not include the job index. See 'Log File
                Formats'.
 
+write_hist_log=str Same as write_lat_log, 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 per_job_logs is false, then the filename will not include the
+               job index. See 'Log File Formats'.
+
 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
@@ -1625,6 +1640,20 @@ log_avg_msec=int By default, fio will log an entry in the iops, latency,
                specified period of time, reducing the resolution of the log.
                See log_max_value as well. Defaults to 0, logging all entries.
 
+log_hist_msec=int Same as log_avg_msec, but logs entries for completion
+               latency histograms. Computing latency percentiles from averages of
+               intervals using log_avg_msec 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 log_hist_coarseness as well. Defaults to 0, meaning histogram
+               logging is disabled.
+
+log_hist_coarseness=int Integer ranging from 0 to 6, defining the coarseness
+               of the resolution of the histogram logs enabled with log_hist_msec. For
+               each increment in coarseness, fio outputs half as many bins. Defaults to
+               0, for which histogram logs contain 1216 latency bins. See
+               'Log File Formats'.
+
 log_max_value=bool     If log_avg_msec 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
@@ -1657,6 +1686,10 @@ log_store_compressed=bool        If set, fio will store the log files in a
                the --inflate-log command line parameter. The files will be
                stored with a .fz suffix.
 
+log_unix_epoch=bool    If set, fio will log Unix timestamps to the log
+               files produced by enabling write_type_log for each log type, instead
+               of the default zero-based timestamps.
+
 block_error_percentiles=bool   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
@@ -1927,7 +1960,7 @@ be the starting port number since fio will use a range of ports.
 [mtd] skip_bad=bool    Skip operations against known bad blocks.
 
 [libhdfs] hdfsdirectory        libhdfs will create chunk in this HDFS directory
-[libhdfs] chunck_size  the size of the chunck to use for each file.
+[libhdfs] chunk_size   the size of the chunk to use for each file.
 
 
 6.0 Interpreting the output