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 <sitsofe@yahoo.com>

diff --git a/HOWTO b/HOWTO
index 83583028ae70ffdd330e26f82e42860d17a72e0b..f151350ce39b221246316848c4648b80b7a9b1c0 100644 (file)
--- 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 023d6efc60acb226576c4b48e44a60fb95c07e81..198b9d85f872a4b959fd997dca43326a9f5b5ff4 100644 (file)
--- 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