From 5a83478fc279abe98ce17182e1569246e99bbcec Mon Sep 17 00:00:00 2001 From: Sitsofe Wheeler Date: Tue, 18 Jul 2017 07:46:52 +0100 Subject: [PATCH] doc: add block size to log file format Commit a3ae5b057588f555a1544ec749167a44c5a071aa ("Update documentation on log file formats") added documentation for the log format but left out the block size column so let's add it here. While we're here clean up some formatting in log_offset, add a reference to Log File Formats and mention that it defaults to off. Signed-off-by: Sitsofe Wheeler --- HOWTO | 21 ++++++++++++--------- fio.1 | 18 ++++++++++-------- 2 files changed, 22 insertions(+), 17 deletions(-) diff --git a/HOWTO b/HOWTO index f62a5170..67888e7c 100644 --- a/HOWTO +++ b/HOWTO @@ -2761,7 +2761,8 @@ Measurements and reporting .. option:: log_offset=int If this is set, the iolog options will include the byte offset for the I/O - entry as well as the other data values. + entry as well as the other data values. Defaults to 0 meaning that + offsets are not present in logs. Also see `Log File Formats`_. .. option:: log_compression=int @@ -3531,9 +3532,10 @@ Log File Formats Fio supports a variety of log file formats, for logging latencies, bandwidth, and IOPS. The logs share a common format, which looks like this: - *time* (`msec`), *value*, *data direction*, *offset* + *time* (`msec`), *value*, *data direction*, *block size* (`bytes`), + *offset* (`bytes`) -Time for the log entry is always in milliseconds. The *value* logged depends +*Time* for the log entry is always in milliseconds. The *value* logged depends on the type of log, it will be one of the following: **Latency log** @@ -3552,16 +3554,17 @@ on the type of log, it will be one of the following: **2** I/O is a TRIM -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 toggled with -:option:`log_offset`. +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 +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 +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' and -'offset' are per-I/O values, they aren't applicable if windowed logging is enabled. +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. Client/Server ------------- diff --git a/fio.1 b/fio.1 index 768b2096..b5694371 100644 --- a/fio.1 +++ b/fio.1 @@ -1794,7 +1794,8 @@ logs contain 1216 latency bins. See the \fBLOG FILE FORMATS\fR section. .TP .BI log_offset \fR=\fPbool If this is set, the iolog options will include the byte offset for the IO -entry as well as the other data values. +entry as well as the other data values. Defaults to 0 meaning that offsets are +not present in logs. See the \fBLOG FILE FORMATS\fR section. .TP .BI log_compression \fR=\fPint If this is set, fio will compress the IO logs as it goes, to keep the memory @@ -2581,7 +2582,7 @@ the files over and load them from there. Fio supports a variety of log file formats, for logging latencies, bandwidth, and IOPS. The logs share a common format, which looks like this: -.B time (msec), value, data direction, offset +.B time (msec), value, data direction, block size (bytes), offset (bytes) Time for the log entry is always in milliseconds. The value logged depends on the type of log, it will be one of the following: @@ -2616,15 +2617,16 @@ IO is a TRIM .PD .P -The \fIoffset\fR is the offset, in bytes, from the start of the file, for that -particular IO. The logging of the offset can be toggled with \fBlog_offset\fR. +The entry's *block size* is always in bytes. The \fIoffset\fR is the offset, in +bytes, from the start of the file, for that particular IO. The logging of the +offset can be toggled with \fBlog_offset\fR. If windowed logging is enabled through \fBlog_avg_msec\fR, then fio doesn't log individual IOs. Instead of logs the average values over the specified -period of time. Since \fIdata direction\fR and \fIoffset\fR are per-IO values, -they aren't applicable if windowed logging is enabled. If windowed logging -is enabled and \fBlog_max_value\fR is set, then fio logs maximum values in -that window instead of averages. +period of time. Since \fIdata direction\fR, \fIblock size\fR and \fIoffset\fR +are per-IO values, if windowed logging is enabled they aren't applicable and +will be 0. If windowed logging is enabled and \fBlog_max_value\fR is set, then +fio logs maximum values in that window instead of averages. For histogram logging the logs look like this: -- 2.25.1