docs: update fio man page for log_window_value

Signed-off-by: Ankit Kumar <ankit.kumar@samsung.com>
Link: https://lore.kernel.org/r/20240125110124.55137-3-ankit.kumar@samsung.com
Signed-off-by: Vincent Fu <vincent.fu@samsung.com>

diff --git a/HOWTO.rst b/HOWTO.rst
index d0ba802173d135188f046cf60b488e103c525154..dcea1ea15fd2cd4df2267a4365e4dd5182fab855 100644 (file)
--- a/HOWTO.rst
+++ b/HOWTO.rst
@@ -4067,7 +4067,7 @@ Measurements and reporting
        I/O that completes. When writing to the disk log, that can quickly grow to a
        very large size. Setting this option makes fio average the each log entry
        over the specified period of time, reducing the resolution of the log.  See
        I/O that completes. When writing to the disk log, that can quickly grow to a
        very large size. Setting this option makes fio average the each log entry
        over the specified period of time, reducing the resolution of the log.  See

-       :option:`log_max_value` as well. Defaults to 0, logging all entries.
+       :option:`log_window_value` as well. Defaults to 0, logging all entries.

        Also see `Log File Formats`_.
 
 .. option:: log_hist_msec=int
        Also see `Log File Formats`_.
 
 .. option:: log_hist_msec=int


@@ -4088,11 +4088,28 @@ Measurements and reporting
        histogram logs contain 1216 latency bins. See :option:`write_hist_log`
        and `Log File Formats`_.
 
        histogram logs contain 1216 latency bins. See :option:`write_hist_log`
        and `Log File Formats`_.
 

-.. option:: log_max_value=bool
+.. option:: log_window_value=int, log_max_value=int

 
 

-       If :option:`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 logged.
+       If :option:`log_avg_msec` is set, fio by default logs the average over that
+       window. This option determines whether fio logs the average, maximum or
+       both the values over the window. This only affects the latency logging,
+       as both average and maximum values for iops or bw log will be same.
+       Accepted values are:
+
+               **avg**
+                       Log average value over the window. The default.
+
+               **max**
+                       Log maximum value in the window.
+
+               **both**
+                       Log both average and maximum value over the window.
+
+               **0**
+                       Backward-compatible alias for **avg**.
+
+               **1**
+                       Backward-compatible alias for **max**.

 
 .. option:: log_offset=bool
 
 
 .. option:: log_offset=bool
 


@@ -5061,11 +5078,19 @@ toggled with :option:`log_offset`.
 by the ioengine specific :option:`cmdprio_percentage`.
 
 Fio defaults to logging every individual I/O but when windowed logging is set
 by the ioengine specific :option:`cmdprio_percentage`.
 
 Fio defaults to logging every individual I/O but when windowed logging is set

-through :option:`log_avg_msec`, either the average (by default) or the maximum
-(:option:`log_max_value` is set) *value* seen over the specified period of time
-is recorded. Each *data direction* seen within the window period will aggregate
-its values in a separate row. Further, when using windowed logging the *block
-size* and *offset* entries will always contain 0.
+through :option:`log_avg_msec`, either the average (by default), the maximum
+(:option:`log_window_value` is set to max) *value* seen over the specified period
+of time, or both the average *value* and maximum *value1* (:option:`log_window_value`
+is set to both) is recorded. The log file format when both the values are reported
+takes this form:
+
+    *time* (`msec`), *value*, *value1*, *data direction*, *block size* (`bytes`),
+    *offset* (`bytes`), *command priority*
+
+
+Each *data direction* seen within the window period will aggregate its values in a
+separate row. Further, when using windowed logging the *block size* and *offset*
+entries will always contain 0.

 
 
 Client/Server
 
 
 Client/Server

diff --git a/fio.1 b/fio.1
index 8f659f1dbde7db4250598c6f8d41308b069bf97b..718aed80ead6ba5ec5b9afe08bf2a4d617b1d4bb 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -3764,7 +3764,7 @@ By default, fio will log an entry in the iops, latency, or bw log for every
 I/O that completes. When writing to the disk log, that can quickly grow to a
 very large size. Setting this option makes fio average the each log entry
 over the specified period of time, reducing the resolution of the log. See
 I/O that completes. When writing to the disk log, that can quickly grow to a
 very large size. Setting this option makes fio average the each log entry
 over the specified period of time, reducing the resolution of the log. See

-\fBlog_max_value\fR as well. Defaults to 0, logging all entries.
+\fBlog_window_value\fR as well. Defaults to 0, logging all entries.

 Also see \fBLOG FILE FORMATS\fR section.
 .TP
 .BI log_hist_msec \fR=\fPint
 Also see \fBLOG FILE FORMATS\fR section.
 .TP
 .BI log_hist_msec \fR=\fPint


@@ -3782,10 +3782,28 @@ the histogram logs enabled with \fBlog_hist_msec\fR. For each increment
 in coarseness, fio outputs half as many bins. Defaults to 0, for which
 histogram logs contain 1216 latency bins. See \fBLOG FILE FORMATS\fR section.
 .TP
 in coarseness, fio outputs half as many bins. Defaults to 0, for which
 histogram logs contain 1216 latency bins. See \fBLOG FILE FORMATS\fR section.
 .TP

-.BI log_max_value \fR=\fPbool
-If \fBlog_avg_msec\fR 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 logged.
+.BI log_window_value \fR=\fPint "\fR,\fP log_max_value" \fR=\fPint
+If \fBlog_avg_msec\fR is set, fio by default logs the average over that window.
+This option determines whether fio logs the average, maximum or both the
+values over the window. This only affects the latency logging, as both average
+and maximum values for iops or bw log will be same. Accepted values are:
+.RS
+.TP
+.B avg
+Log average value over the window. The default.
+.TP
+.B max
+Log maximum value in the window.
+.TP
+.B both
+Log both average and maximum value over the window.
+.TP
+.B 0
+Backward-compatible alias for \fBavg\fR.
+.TP
+.B 1
+Backward-compatible alias for \fBmax\fR.
+.RE

 .TP
 .BI log_offset \fR=\fPbool
 If this is set, the iolog options will include the byte offset for the I/O
 .TP
 .BI log_offset \fR=\fPbool
 If this is set, the iolog options will include the byte offset for the I/O


@@ -4797,11 +4815,20 @@ number with the lowest 13 bits indicating the priority value (\fBprio\fR and
 (\fBprioclass\fR and \fBcmdprio_class\fR options).
 .P
 Fio defaults to logging every individual I/O but when windowed logging is set
 (\fBprioclass\fR and \fBcmdprio_class\fR options).
 .P
 Fio defaults to logging every individual I/O but when windowed logging is set

-through \fBlog_avg_msec\fR, either the average (by default) or the maximum
-(\fBlog_max_value\fR is set) `value' seen over the specified period of time
-is recorded. Each `data direction' seen within the window period will aggregate
-its values in a separate row. Further, when using windowed logging the `block
-size' and `offset' entries will always contain 0.
+through \fBlog_avg_msec\fR, either the average (by default), the maximum
+(\fBlog_window_value\fR is set to max) `value' seen over the specified period of
+time, or both the average `value' and maximum `value1' (\fBlog_window_value\fR is
+set to both) is recorded. The log file format when both the values are reported
+takes this form:
+.RS
+.P
+time (msec), value, value1, data direction, block size (bytes), offset (bytes),
+command priority
+.RE
+.P
+Each `data direction' seen within the window period will aggregate its values
+in a separate row. Further, when using windowed logging the `block size' and
+`offset' entries will always contain 0.

 .SH CLIENT / SERVER
 Normally fio is invoked as a stand-alone application on the machine where the
 I/O workload should be generated. However, the backend and frontend of fio can
 .SH CLIENT / SERVER
 Normally fio is invoked as a stand-alone application on the machine where the
 I/O workload should be generated. However, the backend and frontend of fio can