tools/hist/fiologparser_hist.py.1

   1 .TH fiologparser_hist.py 1 "August 18, 2016"
   2 .SH NAME
   3 fiologparser_hist.py \- Calculate statistics from fio histograms
   4 .SH SYNOPSIS
   5 .B fiologparser_hist.py
   6 [\fIoptions\fR] [clat_hist_files]...
   7 .SH DESCRIPTION
   8 .B fiologparser_hist.py
   9 is a utility for converting *_clat_hist* files
  10 generated by fio into a CSV of latency statistics including minimum,
  11 average, maximum latency, and selectable percentiles.
  12 .SH EXAMPLES
  13 .PP
  14 .nf
  15 $ fiologparser_hist.py *_clat_hist*
  16 end-time, samples, min, avg, median, 90%, 95%, 99%, max
  17 1000, 15, 192, 1678.107, 1788.859, 1856.076, 1880.040, 1899.208, 1888.000
  18 2000, 43, 152, 1642.368, 1714.099, 1816.659, 1845.552, 1888.131, 1888.000
  19 4000, 39, 1152, 1546.962, 1545.785, 1627.192, 1640.019, 1691.204, 1744
  20 \[char46]..
  21 .fi
  22 .PP
  23
  24 .SH OPTIONS
  25 .TP
  26 .BR \-\-help
  27 Print these options.
  28 .TP
  29 .BR \-\-buff_size \fR=\fPint
  30 Number of samples to buffer into numpy at a time. Default is 10,000.
  31 This can be adjusted to help performance.
  32 .TP
  33 .BR \-\-max_latency \fR=\fPint
  34 Number of seconds of data to process at a time. Defaults to 20 seconds,
  35 in order to handle the 17 second upper bound on latency in histograms
  36 reported by fio. This should be increased if fio has been
  37 run with a larger maximum latency. Lowering this when a lower maximum
  38 latency is known can improve performance. See NOTES for more details.
  39 .TP
  40 .BR \-i ", " \-\-interval \fR=\fPint
  41 Interval at which statistics are reported. Defaults to 1000 ms. This
  42 should be set a minimum of the value for \fBlog_hist_msec\fR as given
  43 to fio.
  44 .TP
  45 .BR \-\-noweight
  46 Do not perform weighting of samples between output intervals. Default is False.
  47 .TP
  48 .BR \-d ", " \-\-divisor \fR=\fPint
  49 Divide statistics by this value. Defaults to 1. Useful if you want to
  50 convert latencies from milliseconds to seconds (\fBdivisor\fR=\fP1000\fR).
  51 .TP
  52 .BR \-\-warn
  53 Enables warning messages printed to stderr, useful for debugging.
  54 .TP
  55 .BR \-\-group_nr \fR=\fPint
  56 Set this to the value of \fIFIO_IO_U_PLAT_GROUP_NR\fR as defined in
  57 \fPstat.h\fR if fio has been recompiled. Defaults to 19, the
  58 current value used in fio. See NOTES for more details.
  59 .TP
  60 .BR \-\-percentiles \fR=\fPstr
  61 Pass desired list of comma or colon separated percentiles to print.
  62 The default is "90.0:95.0:99.0", but min, median(50%) and max percentiles are always printed
  63 .TP
  64 .BR \-\-usbin
  65 Use to indicate to parser that histogram bin latencies values are in microseconds.
  66 The default is to use nanoseconds, but histogram logs from fio versions <= 2.99 are in microseconds.
  67 .TP
  68 .BR \-\-directions \fR=\fPstr
  69 By default, all directions (e.g read and write) histogram bins are combined
  70 producing one 'mixed' result.
  71 To produce independent directional results, pass some combination of
  72 \'rwtm\' characters with the \-\-directions\fR=\fPrwtm option.
  73 A \'dir\' column is added indicating the result direction for a row.
  74
  75 .SH NOTES
  76 end-times are calculated to be uniform increments of the \fB\-\-interval\fR value given,
  77 regardless of when histogram samples are reported. Of note:
  78
  79 .RS
  80 Intervals with no samples are omitted. In the example above this means
  81 "no statistics from 2 to 3 seconds" and "39 samples influenced the statistics
  82 of the interval from 3 to 4 seconds".
  83 .LP
  84 Intervals with a single sample will have the same value for all statistics
  85 .RE
  86
  87 .PP
  88 The number of samples is unweighted, corresponding to the total number of samples
  89 which have any effect whatsoever on the interval.
  90
  91 Min statistics are computed using value of the lower boundary of the first bin
  92 (in increasing bin order) with non-zero samples in it. Similarly for max,
  93 we take the upper boundary of the last bin with non-zero samples in it.
  94 This is semantically identical to taking the 0th and 100th percentiles with a
  95 50% bin-width buffer (because percentiles are computed using mid-points of
  96 the bins). This enforces the following nice properties:
  97
  98 .RS
  99 min <= 50th <= 90th <= 95th <= 99th <= max
 100 .LP
 101 min and max are strict lower and upper bounds on the actual
 102 min / max seen by fio (and reported in *_clat.* with averaging turned off).
 103 .RE
 104
 105 .PP
 106 Average statistics use a standard weighted arithmetic mean.
 107
 108 When --noweights option is false (the default)
 109 percentile statistics are computed using the weighted percentile method as
 110 described here: \fIhttps://en.wikipedia.org/wiki/Percentile#Weighted_percentile\fR.
 111 See weights() method for details on how weights are computed for individual
 112 samples. In process_interval() we further multiply by the height of each bin
 113 to get weighted histograms.
 114
 115 We convert files given on the command line, assumed to be fio histogram files,
 116 An individual histogram file can contain the
 117 histograms for multiple different r/w directions (notably when \fB\-\-rw\fR=\fPrandrw\fR). This
 118 is accounted for by tracking each r/w direction separately. In the statistics
 119 reported we ultimately merge *all* histograms (regardless of r/w direction).
 120
 121 The value of *_GROUP_NR in \fIstat.h\fR (and *_BITS) determines how many latency bins
 122 fio outputs when histogramming is enabled. Namely for the current default of
 123 GROUP_NR=19, we get 1,216 bins with a maximum latency of approximately 17
 124 seconds. For certain applications this may not be sufficient. With GROUP_NR=24
 125 we have 1,536 bins, giving us a maximum latency of 541 seconds (~ 9 minutes). If
 126 you expect your application to experience latencies greater than 17 seconds,
 127 you will need to recompile fio with a larger GROUP_NR, e.g. with:
 128
 129 .RS
 130 .PP
 131 .nf
 132 sed -i.bak 's/^#define FIO_IO_U_PLAT_GROUP_NR 19\n/#define FIO_IO_U_PLAT_GROUP_NR 24/g' stat.h
 133 make fio
 134 .fi
 135 .PP
 136 .RE
 137
 138 .PP
 139 Quick reference table for the max latency corresponding to a sampling of
 140 values for GROUP_NR:
 141
 142 .RS
 143 .PP
 144 .nf
 145 GROUP_NR | # bins | max latency bin value
 146 19       | 1216   | 16.9 sec
 147 20       | 1280   | 33.8 sec
 148 21       | 1344   | 67.6 sec
 149 22       | 1408   | 2  min, 15 sec
 150 23       | 1472   | 4  min, 32 sec
 151 24       | 1536   | 9  min, 4  sec
 152 25       | 1600   | 18 min, 8  sec
 153 26       | 1664   | 36 min, 16 sec
 154 .fi
 155 .PP
 156 .RE
 157
 158 .PP
 159 At present this program automatically detects the number of histogram bins in
 160 the log files, and adjusts the bin latency values accordingly. In particular if
 161 you use the \fB\-\-log_hist_coarseness\fR parameter of fio, you get output files with
 162 a number of bins according to the following table (note that the first
 163 row is identical to the table above):
 164
 165 .RS
 166 .PP
 167 .nf
 168 coarse \\ GROUP_NR
 169         19     20    21     22     23     24     25     26
 170    -------------------------------------------------------
 171   0  [[ 1216,  1280,  1344,  1408,  1472,  1536,  1600,  1664],
 172   1   [  608,   640,   672,   704,   736,   768,   800,   832],
 173   2   [  304,   320,   336,   352,   368,   384,   400,   416],
 174   3   [  152,   160,   168,   176,   184,   192,   200,   208],
 175   4   [   76,    80,    84,    88,    92,    96,   100,   104],
 176   5   [   38,    40,    42,    44,    46,    48,    50,    52],
 177   6   [   19,    20,    21,    22,    23,    24,    25,    26],
 178   7   [  N/A,    10,   N/A,    11,   N/A,    12,   N/A,    13],
 179   8   [  N/A,     5,   N/A,   N/A,   N/A,     6,   N/A,   N/A]]
 180 .fi
 181 .PP
 182 .RE
 183
 184 .PP
 185 For other values of GROUP_NR and coarseness, this table can be computed like this:
 186
 187 .RS
 188 .PP
 189 .nf
 190 bins = [1216,1280,1344,1408,1472,1536,1600,1664]
 191 max_coarse = 8
 192 fncn = lambda z: list(map(lambda x: z/2**x if z % 2**x == 0 else nan, range(max_coarse + 1)))
 193 np.transpose(list(map(fncn, bins)))
 194 .fi
 195 .PP
 196 .RE
 197
 198 .PP
 199 If you have not adjusted GROUP_NR for your (high latency) application, then you
 200 will see the percentiles computed by this tool max out at the max latency bin
 201 value as in the first table above, and in this plot (where GROUP_NR=19 and thus we see
 202 a max latency of ~16.7 seconds in the red line):
 203
 204 .RS
 205 \fIhttps://www.cronburg.com/fio/max_latency_bin_value_bug.png
 206 .RE
 207
 208 .PP
 209 Motivation for, design decisions, and the implementation process are
 210 described in further detail here:
 211
 212 .RS
 213 \fIhttps://www.cronburg.com/fio/cloud-latency-problem-measurement/
 214 .RE
 215
 216 .SH AUTHOR
 217 .B fiologparser_hist.py
 218 and this manual page were written by Karl Cronburg <karl.cronburg@gmail.com>.
 219 .SH "REPORTING BUGS"
 220 Report bugs to the \fBfio\fR mailing list <fio@vger.kernel.org>.