From 15417073c6d295839a33505a559204c1af0c2fb5 Mon Sep 17 00:00:00 2001 From: Sitsofe Wheeler Date: Sat, 2 Sep 2017 12:14:19 +0100 Subject: [PATCH] doc: update Log File Formats and write_iops_log sections Make it clearer when various log entries will be always set to 0, move "IOPS value is 1 without windowed logging" warning to write_iops_log option description, change offset definition to position, add some formatting. Signed-off-by: Sitsofe Wheeler --- HOWTO | 25 +++++++++++++------------ fio.1 | 25 +++++++++++++------------ 2 files changed, 26 insertions(+), 24 deletions(-) diff --git a/HOWTO b/HOWTO index 16c5ae31..844c46e5 100644 --- a/HOWTO +++ b/HOWTO @@ -2915,9 +2915,11 @@ Measurements and reporting .. option:: write_iops_log=str 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. + :file:`name_iops.x.log`) instead. Because fio defaults to individual + I/O logging, the value entry in the IOPS log will be 1 unless windowed + logging (see :option:`log_avg_msec`) has been enabled. 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 @@ -3802,17 +3804,16 @@ on the type of log, it will be one of the following: **2** I/O is a TRIM -The entry's *block size* is always in bytes. The *offset* is the offset, in bytes, -from the start of the file, for that particular I/O. The logging of the offset can be +The entry's *block size* is always in bytes. The *offset* is the position in bytes +from the start of the file for that particular I/O. The logging of the offset can be toggled with :option:`log_offset`. -Fio defaults to logging every individual I/O. When IOPS are logged for individual -I/Os the *value* entry will always be 1. If windowed logging is enabled through -:option:`log_avg_msec`, fio logs the average values over the specified period of time. -If windowed logging is enabled and :option:`log_max_value` is set, then fio logs -maximum values in that window instead of averages. Since *data direction*, *block -size* and *offset* are per-I/O values, if windowed logging is enabled they -aren't applicable and will be 0. +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. Client/Server ------------- diff --git a/fio.1 b/fio.1 index 4386f857..a16f6e62 100644 --- a/fio.1 +++ b/fio.1 @@ -2608,9 +2608,11 @@ within the file. .TP .BI write_iops_log \fR=\fPstr 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. +`name_iops.x.log`) instead. Because fio defaults to individual +I/O logging, the value entry in the IOPS log will be 1 unless windowed +logging (see \fBlog_avg_msec\fR) has been enabled. See +\fBwrite_bw_log\fR for details about the filename format and \fBLOG +FILE FORMATS\fR 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 @@ -3527,17 +3529,16 @@ I/O is a WRITE I/O is a TRIM .RE .P -The entry's `block size' is always in bytes. The `offset' is the offset, in bytes, -from the start of the file, for that particular I/O. The logging of the offset can be +The entry's `block size' is always in bytes. The `offset' is the position in bytes +from the start of the file for that particular I/O. The logging of the offset can be toggled with \fBlog_offset\fR. .P -Fio defaults to logging every individual I/O. When IOPS are logged for individual -I/Os the `value' entry will always be 1. If windowed logging is enabled through -\fBlog_avg_msec\fR, fio logs the average values over the specified period of time. -If windowed logging is enabled and \fBlog_max_value\fR is set, then fio logs -maximum values in that window instead of averages. Since `data direction', `block size' -and `offset' are per\-I/O values, if windowed logging is enabled they -aren't applicable and will be 0. +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. .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 -- 2.25.1