From 074f08170af15ca8ebd469c3a1fa09c38f29904e Mon Sep 17 00:00:00 2001 From: Sitsofe Wheeler Date: Sun, 29 Oct 2017 16:08:51 +0000 Subject: [PATCH] doc: rewrite write_*_log sections - Put the big example of how log files work in write_bw_log and make the other sections reference that option so there's less repetition. - Add a note that the write_hist_log depends on log_hist_msec. - Make a link from log_hist_coarseness to write_hist_log. Signed-off-by: Sitsofe Wheeler --- HOWTO | 68 +++++++++++++++++++++++++++++------------------------------ fio.1 | 68 +++++++++++++++++++++++++++++------------------------------ 2 files changed, 68 insertions(+), 68 deletions(-) diff --git a/HOWTO b/HOWTO index 83583028..f151350c 100644 --- a/HOWTO +++ b/HOWTO @@ -2722,47 +2722,46 @@ Measurements and reporting .. option:: write_bw_log=str If given, write a bandwidth log for this job. Can be used to store data of - the bandwidth of the jobs in their lifetime. The included - :command:`fio_generate_plots` script uses :command:`gnuplot` to turn these - text files into nice graphs. See :option:`write_lat_log` for behavior of - given filename. For this option, the postfix is :file:`_bw.x.log`, where `x` - is the index of the job (`1..N`, where `N` is the number of jobs). If - :option:`per_job_logs` is false, then the filename will not include the job - index. See `Log File Formats`_. + the bandwidth of the jobs in their lifetime. -.. option:: write_lat_log=str + If no str argument is given, the default filename of + :file:`jobname_type.x.log` is used. Even when the argument is given, fio + will still append the type of log. So if one specifies:: + + write_bw_log=foo - Same as :option:`write_bw_log`, except that this option stores I/O - submission, completion, and total latencies instead. If no filename is given - with this option, the default filename of :file:`jobname_type.log` is - used. Even if the filename is given, fio will still append the type of - log. So if one specifies:: + The actual log name will be :file:`foo_bw.x.log` where `x` is the index + of the job (`1..N`, where `N` is the number of jobs). If + :option:`per_job_logs` is false, then the filename will not include the + `.x` job index. - write_lat_log=foo + The included :command:`fio_generate_plots` script uses :command:`gnuplot` to turn these + text files into nice graphs. See `Log File Formats`_ for how data is + structured within the file. + +.. option:: write_lat_log=str - The actual log names will be :file:`foo_slat.x.log`, :file:`foo_clat.x.log`, - and :file:`foo_lat.x.log`, where `x` is the index of the job (`1..N`, where `N` - is the number of jobs). This helps :command:`fio_generate_plots` find the - logs automatically. If :option:`per_job_logs` is false, then the filename - will not include the job index. See `Log File Formats`_. + Same as :option:`write_bw_log`, except this option creates I/O + submission (e.g., `file:`name_slat.x.log`), completion (e.g., + `file:`name_clat.x.log`), and total (e.g., `file:`name_lat.x.log`) + latency files instead. See :option:`write_bw_log` for details about + the filename format and `Log File Formats`_ for how data is structured + within the files. .. option:: write_hist_log=str - Same as :option:`write_lat_log`, but writes I/O completion latency - histograms. If no filename is given with this option, the default filename - of :file:`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 :option:`per_job_logs` is false, - then the filename will not include the job index. See `Log File Formats`_. + Same as :option:`write_bw_log` but writes an I/O completion latency + histogram file (e.g., `file:`name_hist.x.log`) instead. Note that this + file will be empty unless :option:`log_hist_msec` has also been set. + See :option:`write_bw_log` for details about the filename format and + `Log File Formats`_ for how data is structured within the file. .. option:: write_iops_log=str - Same as :option:`write_bw_log`, but writes IOPS. If no filename is given - with this option, the default filename of :file:`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. If :option:`per_job_logs` is false, then the filename will not include - the job index. See `Log File Formats`_. + Same as :option:`write_bw_log`, but writes an IOPS file (e.g. + `file:`name_iops.x.log`) instead. See :option:`write_bw_log` for + details about the filename format and `Log File Formats`_ for how data + is structured within the file. .. option:: log_avg_msec=int @@ -2780,15 +2779,16 @@ Measurements and reporting :option:`log_avg_msec` is inaccurate. 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 - :option:`log_hist_coarseness` as well. Defaults to 0, meaning histogram - logging is disabled. + :option:`log_hist_coarseness` and :option:`write_hist_log` as well. + Defaults to 0, meaning histogram logging is disabled. .. option:: log_hist_coarseness=int Integer ranging from 0 to 6, defining the coarseness of the resolution of the histogram logs enabled with :option:`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`_. + histogram logs contain 1216 latency bins. See :option:`write_hist_log` + and `Log File Formats`_. .. option:: log_max_value=bool diff --git a/fio.1 b/fio.1 index 023d6efc..198b9d85 100644 --- a/fio.1 +++ b/fio.1 @@ -2420,48 +2420,48 @@ the final stat output. .TP .BI write_bw_log \fR=\fPstr If given, write a bandwidth log for this job. Can be used to store data of -the bandwidth of the jobs in their lifetime. The included -\fBfio_generate_plots\fR script uses gnuplot to turn these -text files into nice graphs. See \fBwrite_lat_log\fR for behavior of -given filename. For this option, the postfix is `_bw.x.log', where `x' -is the index of the job (1..N, where N is the number of jobs). If -\fBper_job_logs\fR is false, then the filename will not include the job -index. See \fBLOG FILE FORMATS\fR section. -.TP -.BI write_lat_log \fR=\fPstr -Same as \fBwrite_bw_log\fR, except that this option stores I/O -submission, completion, and total latencies instead. If no filename is given -with this option, the default filename of `jobname_type.log' is -used. Even if the filename is given, fio will still append the type of -log. So if one specifies: +the bandwidth of the jobs in their lifetime. .RS +.P +If no str argument is given, the default filename of +`jobname_type.x.log' is used. Even when the argument is given, fio +will still append the type of log. So if one specifies: .RS .P -write_lat_log=foo +write_bw_log=foo .RE .P -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 \fBfio_generate_plots\fR find the -logs automatically. If \fBper_job_logs\fR is false, then the filename -will not include the job index. See \fBLOG FILE FORMATS\fR section. +The actual log name will be `foo_bw.x.log' where `x' is the index +of the job (1..N, where N is the number of jobs). If +\fBper_job_logs\fR is false, then the filename will not include the +`.x` job index. +.P +The included \fBfio_generate_plots\fR script uses gnuplot to turn these +text files into nice graphs. See the \fBLOG FILE FORMATS\fR section for how data is +structured within the file. .RE .TP +.BI write_lat_log \fR=\fPstr +Same as \fBwrite_bw_log\fR, except this option creates I/O +submission (e.g., `name_slat.x.log'), completion (e.g., +`name_clat.x.log'), and total (e.g., `name_lat.x.log') latency +files instead. See \fBwrite_bw_log\fR for details about the +filename format and the \fBLOG FILE FORMATS\fR section for how data is structured +within the files. +.TP .BI write_hist_log \fR=\fPstr -Same as \fBwrite_lat_log\fR, 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 \fBper_job_logs\fR is false, -then the filename will not include the job index. See \fBLOG FILE FORMATS\fR section. +Same as \fBwrite_bw_log\fR but writes an I/O completion latency +histogram file (e.g., `name_hist.x.log') instead. Note that this +file will be empty unless \fBlog_hist_msec\fR has also been set. +See \fBwrite_bw_log\fR for details about the filename format and +the \fBLOG FILE FORMATS\fR section for how data is structured +within the file. .TP .BI write_iops_log \fR=\fPstr -Same as \fBwrite_bw_log\fR, 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. If \fBper_job_logs\fR is false, then the filename will not include -the job index. See \fBLOG FILE FORMATS\fR section. +Same as \fBwrite_bw_log\fR, but writes an IOPS file (e.g. +`name_iops.x.log') instead. See \fBwrite_bw_log\fR for +details about the filename format and the \fBLOG FILE FORMATS\fR section for how data +is structured within the file. .TP .BI log_avg_msec \fR=\fPint By default, fio will log an entry in the iops, latency, or bw log for every @@ -2477,8 +2477,8 @@ histograms. Computing latency percentiles from averages of intervals using \fBlog_avg_msec\fR is inaccurate. 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 -\fBlog_hist_coarseness\fR as well. Defaults to 0, meaning histogram -logging is disabled. +\fBlog_hist_coarseness\fR and \fBwrite_hist_log\fR as well. +Defaults to 0, meaning histogram logging is disabled. .TP .BI log_hist_coarseness \fR=\fPint Integer ranging from 0 to 6, defining the coarseness of the resolution of -- 2.25.1