Merge branch 'fio-jsonplus-patches' of https://github.com/vincentkfu/fio
authorJens Axboe <axboe@kernel.dk>
Mon, 7 Aug 2017 19:44:01 +0000 (13:44 -0600)
committerJens Axboe <axboe@kernel.dk>
Mon, 7 Aug 2017 19:44:01 +0000 (13:44 -0600)
1  2 
HOWTO
fio.1

diff --combined HOWTO
index b535177c9abb13848346af93bc24b8a186ede983,27bee2c0065f7d40d855ed4b214a077dd68c61b0..6c69a0ecf7e8fac3c20d9867f9016a74ed1278a8
--- 1/HOWTO
--- 2/HOWTO
+++ b/HOWTO
@@@ -505,19 -505,19 +505,19 @@@ Parameter type
        prefixes.  To specify power-of-10 decimal values defined in the
        International System of Units (SI):
  
 -              * *Ki* -- means kilo (K) or 1000
 -              * *Mi* -- means mega (M) or 1000**2
 -              * *Gi* -- means giga (G) or 1000**3
 -              * *Ti* -- means tera (T) or 1000**4
 -              * *Pi* -- means peta (P) or 1000**5
 +              * *ki* -- means kilo (K) or 1000
 +              * *mi* -- means mega (M) or 1000**2
 +              * *gi* -- means giga (G) or 1000**3
 +              * *ti* -- means tera (T) or 1000**4
 +              * *pi* -- means peta (P) or 1000**5
  
        To specify power-of-2 binary values defined in IEC 80000-13:
  
                * *k* -- means kibi (Ki) or 1024
 -              * *M* -- means mebi (Mi) or 1024**2
 -              * *G* -- means gibi (Gi) or 1024**3
 -              * *T* -- means tebi (Ti) or 1024**4
 -              * *P* -- means pebi (Pi) or 1024**5
 +              * *m* -- means mebi (Mi) or 1024**2
 +              * *g* -- means gibi (Gi) or 1024**3
 +              * *t* -- means tebi (Ti) or 1024**4
 +              * *p* -- means pebi (Pi) or 1024**5
  
        With :option:`kb_base`\=1024 (the default), the unit prefixes are opposite
        from those specified in the SI and IEC 80000-13 standards to provide
  **float_list**
        A list of floating point numbers, separated by a ':' character.
  
 +With the above in mind, here follows the complete list of fio job parameters.
 +
  
  Units
  ~~~~~
                Bit based.
  
  
 -With the above in mind, here follows the complete list of fio job parameters.
 -
 -
  Job description
  ~~~~~~~~~~~~~~~
  
@@@ -1392,7 -1393,7 +1392,7 @@@ Block siz
        typically won't work with direct I/O, as that normally requires sector
        alignment.
  
 -.. option:: bs_is_seq_rand
 +.. option:: bs_is_seq_rand=bool
  
        If this option is set, fio will use the normal read,write blocksize settings
        as sequential,random blocksize settings instead. Any random read or write
@@@ -1529,7 -1530,6 +1529,7 @@@ Buffers and memor
  
                **cudamalloc**
                        Use GPU memory as the buffers for GPUDirect RDMA benchmark.
 +                      The ioengine must be rdma.
  
        The area allocated is a function of the maximum allowed bs size for the job,
        multiplied by the I/O depth given. Note that for **shmhuge** and
@@@ -1858,7 -1858,7 +1858,7 @@@ caveat that when used on the command li
  
     [libhdfs]
  
 -              the listening port of the HFDS cluster namenode.
 +              The listening port of the HFDS cluster namenode.
  
  .. option:: interface=str : [netsplice] [net]
  
        **0**
                Default. Preallocate donor's file on init.
        **1**
 -              Allocate space immediately inside defragment event,     and free right
 +              Allocate space immediately inside defragment event, and free right
                after event.
  
  .. option:: clustername=str : [rbd]
  
  .. option:: chunk_size : [libhdfs]
  
 -      the size of the chunk to use for each file.
 +      The size of the chunk to use for each file.
  
  
  I/O depth
@@@ -2166,7 -2166,7 +2166,7 @@@ I/O repla
        replay, the file needs to be turned into a blkparse binary data file first
        (``blkparse <device> -o /dev/null -d file_for_fio.bin``).
  
 -.. option:: replay_no_stall=int
 +.. option:: replay_no_stall=bool
  
        When replaying I/O with :option:`read_iolog` the default behavior is to
        attempt to respect the timestamps within the log and replay them with the
@@@ -2487,7 -2487,7 +2487,7 @@@ Verificatio
  
  .. option:: verifysort_nr=int
  
 -   Pre-load and sort verify blocks for a read workload.
 +      Pre-load and sort verify blocks for a read workload.
  
  .. option:: verify_offset=int
  
  
  .. option:: trim_backlog=int
  
 -      Verify that trim/discarded blocks are returned as zeros.
 +      Trim after this number of blocks are written.
  
  .. option:: trim_backlog_batch=int
  
@@@ -2680,7 -2680,7 +2680,7 @@@ Measurements and reportin
        all jobs in a file will be part of the same reporting group, unless
        separated by a :option:`stonewall`.
  
 -.. option:: stats
 +.. option:: stats=bool
  
        By default, fio collects and shows final output results for all jobs
        that run. If this option is set to 0, then fio will ignore it in
        you instead want to log the maximum value, set this option to 1. Defaults to
        0, meaning that averaged values are logged.
  
 -.. option:: log_offset=int
 +.. option:: log_offset=bool
  
        If this is set, the iolog options will include the byte offset for the I/O
        entry as well as the other data values. Defaults to 0 meaning that
@@@ -3363,6 -3363,27 +3363,27 @@@ minimal output v3, separated by semicol
        terse_version_3;fio_version;jobname;groupid;error;read_kb;read_bandwidth;read_iops;read_runtime_ms;read_slat_min;read_slat_max;read_slat_mean;read_slat_dev;read_clat_min;read_clat_max;read_clat_mean;read_clat_dev;read_clat_pct01;read_clat_pct02;read_clat_pct03;read_clat_pct04;read_clat_pct05;read_clat_pct06;read_clat_pct07;read_clat_pct08;read_clat_pct09;read_clat_pct10;read_clat_pct11;read_clat_pct12;read_clat_pct13;read_clat_pct14;read_clat_pct15;read_clat_pct16;read_clat_pct17;read_clat_pct18;read_clat_pct19;read_clat_pct20;read_tlat_min;read_lat_max;read_lat_mean;read_lat_dev;read_bw_min;read_bw_max;read_bw_agg_pct;read_bw_mean;read_bw_dev;write_kb;write_bandwidth;write_iops;write_runtime_ms;write_slat_min;write_slat_max;write_slat_mean;write_slat_dev;write_clat_min;write_clat_max;write_clat_mean;write_clat_dev;write_clat_pct01;write_clat_pct02;write_clat_pct03;write_clat_pct04;write_clat_pct05;write_clat_pct06;write_clat_pct07;write_clat_pct08;write_clat_pct09;write_clat_pct10;write_clat_pct11;write_clat_pct12;write_clat_pct13;write_clat_pct14;write_clat_pct15;write_clat_pct16;write_clat_pct17;write_clat_pct18;write_clat_pct19;write_clat_pct20;write_tlat_min;write_lat_max;write_lat_mean;write_lat_dev;write_bw_min;write_bw_max;write_bw_agg_pct;write_bw_mean;write_bw_dev;cpu_user;cpu_sys;cpu_csw;cpu_mjf;cpu_minf;iodepth_1;iodepth_2;iodepth_4;iodepth_8;iodepth_16;iodepth_32;iodepth_64;lat_2us;lat_4us;lat_10us;lat_20us;lat_50us;lat_100us;lat_250us;lat_500us;lat_750us;lat_1000us;lat_2ms;lat_4ms;lat_10ms;lat_20ms;lat_50ms;lat_100ms;lat_250ms;lat_500ms;lat_750ms;lat_1000ms;lat_2000ms;lat_over_2000ms;disk_name;disk_read_iops;disk_write_iops;disk_read_merges;disk_write_merges;disk_read_ticks;write_ticks;disk_queue_time;disk_util
  
  
+ JSON+ output
+ ------------
+ The `json+` output format is identical to the `json` output format except that it
+ adds a full dump of the completion latency bins. Each `bins` object contains a
+ set of (key, value) pairs where keys are latency durations and values count how
+ many I/Os had completion latencies of the corresponding duration. For example,
+ consider:
+       "bins" : { "87552" : 1, "89600" : 1, "94720" : 1, "96768" : 1, "97792" : 1, "99840" : 1, "100864" : 2, "103936" : 6, "104960" : 534, "105984" : 5995, "107008" : 7529, ... }
+ This data indicates that one I/O required 87,552ns to complete, two I/Os required
+ 100,864ns to complete, and 7529 I/Os required 107,008ns to complete.
+ Also included with fio is a Python script `fio_jsonplus_clat2csv` that takes
+ json+ output and generates CSV-formatted latency data suitable for plotting.
+ The latency durations actually represent the midpoints of latency intervals.
+ For details refer to stat.h.
  Trace file format
  -----------------
  
diff --combined fio.1
index 093889ed3cb62ecb9e5080d29b1e2c7ce267e2ee,b20030fe28e5baae6e274a4491e19b72c7e2eed1..ab978ab3aeb2914ac9d48e2f6cbb5ca2a728132c
--- 1/fio.1
--- 2/fio.1
+++ b/fio.1
@@@ -223,130 -223,84 +223,130 @@@ hours, 'm' for minutes, 's' for seconds
  .I int
  Integer. A whole number value, which may contain an integer prefix
  and an integer suffix.
 -
 +.RS
 +.RS
 +.P
  [*integer prefix*] **number** [*integer suffix*]
 -
 +.RE
 +.P
  The optional *integer prefix* specifies the number's base. The default
  is decimal. *0x* specifies hexadecimal.
 -
 +.P
  The optional *integer suffix* specifies the number's units, and includes an
  optional unit prefix and an optional unit. For quantities of data, the
  default unit is bytes. For quantities of time, the default unit is seconds
  unless otherwise specified.
 -
 -With \fBkb_base=1000\fR, fio follows international standards for unit
 +.P
 +With `kb_base=1000', fio follows international standards for unit
  prefixes. To specify power-of-10 decimal values defined in the
  International System of Units (SI):
 -
 -.nf
 +.RS
 +.P
  ki means kilo (K) or 1000
 +.RE
 +.RS
  mi means mega (M) or 1000**2
 +.RE
 +.RS
  gi means giga (G) or 1000**3
 +.RE
 +.RS
  ti means tera (T) or 1000**4
 +.RE
 +.RS
  pi means peta (P) or 1000**5
 -.fi
 -
 +.RE
 +.P
  To specify power-of-2 binary values defined in IEC 80000-13:
 -
 -.nf
 +.RS
 +.P
  k means kibi (Ki) or 1024
 +.RE
 +.RS
  m means mebi (Mi) or 1024**2
 +.RE
 +.RS
  g means gibi (Gi) or 1024**3
 +.RE
 +.RS
  t means tebi (Ti) or 1024**4
 +.RE
 +.RS
  p means pebi (Pi) or 1024**5
 -.fi
 -
 -With \fBkb_base=1024\fR (the default), the unit prefixes are opposite
 +.RE
 +.P
 +With `kb_base=1024' (the default), the unit prefixes are opposite
  from those specified in the SI and IEC 80000-13 standards to provide
  compatibility with old scripts. For example, 4k means 4096.
 -
 +.P
  For quantities of data, an optional unit of 'B' may be included
  (e.g., 'kB' is the same as 'k').
 -
 +.P
  The *integer suffix* is not case sensitive (e.g., m/mi mean mebi/mega,
  not milli). 'b' and 'B' both mean byte, not bit.
 -
 -Examples with \fBkb_base=1000\fR:
 -
 -.nf
 +.P
 +Examples with `kb_base=1000':
 +.RS
 +.P
  4 KiB: 4096, 4096b, 4096B, 4k, 4kb, 4kB, 4K, 4KB
 +.RE
 +.RS
  1 MiB: 1048576, 1m, 1024k
 +.RE
 +.RS
  1 MB: 1000000, 1mi, 1000ki
 +.RE
 +.RS
  1 TiB: 1073741824, 1t, 1024m, 1048576k
 +.RE
 +.RS
  1 TB: 1000000000, 1ti, 1000mi, 1000000ki
 -.fi
 -
 -Examples with \fBkb_base=1024\fR (default):
 -
 -.nf
 +.RE
 +.P
 +Examples with `kb_base=1024' (default):
 +.RS
 +.P
  4 KiB: 4096, 4096b, 4096B, 4k, 4kb, 4kB, 4K, 4KB
 +.RE
 +.RS
  1 MiB: 1048576, 1m, 1024k
 +.RE
 +.RS
  1 MB: 1000000, 1mi, 1000ki
 +.RE
 +.RS
  1 TiB: 1073741824, 1t, 1024m, 1048576k
 +.RE
 +.RS
  1 TB: 1000000000, 1ti, 1000mi, 1000000ki
 -.fi
 -
 +.RE
 +.P
  To specify times (units are not case sensitive):
 -
 -.nf
 +.RS
 +.P
  D means days
 +.RE
 +.RS
  H means hours
 +.RE
 +.RS
  M mean minutes
 +.RE
 +.RS
  s or sec means seconds (default)
 +.RE
 +.RS
  ms or msec means milliseconds
 +.RE
 +.RS
  us or usec means microseconds
 -.fi
 -
 +.RE
 +.P
  If the option accepts an upper and lower range, use a colon ':' or
  minus '-' to separate such values. See `irange` parameter type.
  If the lower value specified happens to be larger than the upper value
  the two values are swapped.
 +.RE
  .TP
  .I bool
  Boolean. Usually parsed as an integer, however only defined for
@@@ -1510,7 -1464,7 +1510,7 @@@ Should be a multiple of 1MiB. Default: 
  .B exitall
  Terminate all jobs when one finishes.  Default: wait for each job to finish.
  .TP
 -.B exitall_on_error \fR=\fPbool
 +.B exitall_on_error
  Terminate all jobs if one job finishes in error.  Default: wait for each job
  to finish.
  .TP
@@@ -1566,7 -1520,7 +1566,7 @@@ Unlink job files after each iteration o
  Specifies the number of iterations (runs of the same workload) of this job.
  Default: 1.
  .TP
 -.BI verify_only \fR=\fPbool
 +.BI verify_only
  Do not perform the specified workload, only verify data still matches previous
  invocation of this workload. This option allows one to check data multiple
  times at a later date without overwriting it. This option makes sense only for
@@@ -1756,7 -1710,7 +1756,7 @@@ corrupt
  Replay the I/O patterns contained in the specified file generated by
  \fBwrite_iolog\fR, or may be a \fBblktrace\fR binary file.
  .TP
 -.BI replay_no_stall \fR=\fPint
 +.BI replay_no_stall \fR=\fPbool
  While replaying I/O patterns using \fBread_iolog\fR the default behavior
  attempts to respect timing information between I/Os.  Enabling
  \fBreplay_no_stall\fR causes I/Os to be replayed as fast as possible while
@@@ -2120,7 -2074,7 +2120,7 @@@ For TCP network connections, tell fio t
  connections rather than initiating an outgoing connection. The
  hostname must be omitted if this option is used.
  .TP
 -.BI (net,netsplice)pingpong \fR=\fPbool
 +.BI (net,netsplice)pingpong
  Normally a network writer will just continue writing data, and a network reader
  will just consume packets. If pingpong=1 is set, a writer will send its normal
  payload to the reader, then wait for the reader to send the same payload back.
@@@ -2163,7 -2117,7 +2163,7 @@@ Specifies the username (without the 'cl
  cluster. If the clustername is specified, the clientname shall be the full
  type.id string. If no type. prefix is given, fio will add 'client.' by default.
  .TP
 -.BI (mtd)skipbad \fR=\fPbool
 +.BI (mtd)skip_bad \fR=\fPbool
  Skip operations against known bad blocks.
  .SH OUTPUT
  While running, \fBfio\fR will display the status of the created jobs.  For
@@@ -2439,6 -2393,27 +2439,27 @@@ the minimal output v3, separated by sem
  terse_version_3;fio_version;jobname;groupid;error;read_kb;read_bandwidth;read_iops;read_runtime_ms;read_slat_min;read_slat_max;read_slat_mean;read_slat_dev;read_clat_max;read_clat_min;read_clat_mean;read_clat_dev;read_clat_pct01;read_clat_pct02;read_clat_pct03;read_clat_pct04;read_clat_pct05;read_clat_pct06;read_clat_pct07;read_clat_pct08;read_clat_pct09;read_clat_pct10;read_clat_pct11;read_clat_pct12;read_clat_pct13;read_clat_pct14;read_clat_pct15;read_clat_pct16;read_clat_pct17;read_clat_pct18;read_clat_pct19;read_clat_pct20;read_tlat_min;read_lat_max;read_lat_mean;read_lat_dev;read_bw_min;read_bw_max;read_bw_agg_pct;read_bw_mean;read_bw_dev;write_kb;write_bandwidth;write_iops;write_runtime_ms;write_slat_min;write_slat_max;write_slat_mean;write_slat_dev;write_clat_max;write_clat_min;write_clat_mean;write_clat_dev;write_clat_pct01;write_clat_pct02;write_clat_pct03;write_clat_pct04;write_clat_pct05;write_clat_pct06;write_clat_pct07;write_clat_pct08;write_clat_pct09;write_clat_pct10;write_clat_pct11;write_clat_pct12;write_clat_pct13;write_clat_pct14;write_clat_pct15;write_clat_pct16;write_clat_pct17;write_clat_pct18;write_clat_pct19;write_clat_pct20;write_tlat_min;write_lat_max;write_lat_mean;write_lat_dev;write_bw_min;write_bw_max;write_bw_agg_pct;write_bw_mean;write_bw_dev;cpu_user;cpu_sys;cpu_csw;cpu_mjf;pu_minf;iodepth_1;iodepth_2;iodepth_4;iodepth_8;iodepth_16;iodepth_32;iodepth_64;lat_2us;lat_4us;lat_10us;lat_20us;lat_50us;lat_100us;lat_250us;lat_500us;lat_750us;lat_1000us;lat_2ms;lat_4ms;lat_10ms;lat_20ms;lat_50ms;lat_100ms;lat_250ms;lat_500ms;lat_750ms;lat_1000ms;lat_2000ms;lat_over_2000ms;disk_name;disk_read_iops;disk_write_iops;disk_read_merges;disk_write_merges;disk_read_ticks;write_ticks;disk_queue_time;disk_util
  .fi
  .RE
+ .SH JSON+ OUTPUT
+ The \fBjson+\fR output format is identical to the \fBjson\fR output format except that it
+ adds a full dump of the completion latency bins. Each \fBbins\fR object contains a
+ set of (key, value) pairs where keys are latency durations and values count how
+ many I/Os had completion latencies of the corresponding duration. For example,
+ consider:
+ .RS
+ "bins" : { "87552" : 1, "89600" : 1, "94720" : 1, "96768" : 1, "97792" : 1, "99840" : 1, "100864" : 2, "103936" : 6, "104960" : 534, "105984" : 5995, "107008" : 7529, ... }
+ .RE
+ This data indicates that one I/O required 87,552ns to complete, two I/Os required
+ 100,864ns to complete, and 7529 I/Os required 107,008ns to complete.
+ Also included with fio is a Python script \fBfio_jsonplus_clat2csv\fR that takes
+ json+ output and generates CSV-formatted latency data suitable for plotting.
+ The latency durations actually represent the midpoints of latency intervals.
+ For details refer to stat.h.
  .SH TRACE FILE FORMAT
  There are two trace file format that you can encounter. The older (v1) format
  is unsupported since version 1.20-rc3 (March 2008). It will still be described