Add documentation for iolog version 3, mainly the differences between
versions 2 and 3.
Signed-off-by: Mohamad Gebai <mogeb@xxxxxx>
---
HOWTO.rst | 29 ++++++++++++++++++++++++++++-
fio.1 | 35 ++++++++++++++++++++++++++++++++++-
2 files changed, 62 insertions(+), 2 deletions(-)
diff --git a/HOWTO.rst b/HOWTO.rst
index 0978879c..a5fa432e 100644
--- a/HOWTO.rst
+++ b/HOWTO.rst
@@ -4391,33 +4391,60 @@ The `filename` is given as an absolute path. The `action` can be one of these:
The file I/O action format::
filename action offset length
The `filename` is given as an absolute path, and has to have been added and
opened before it can be used with this format. The `offset` and `length` are
given in bytes. The `action` can be one of these:
**wait**
Wait for `offset` microseconds. Everything below 100 is discarded.
- The time is relative to the previous `wait` statement.
+ The time is relative to the previous `wait` statement. Note that
+ action `wait` is not allowed as of version 3, as the same behavior
+ can be achieved using timestamps.
**read**
Read `length` bytes beginning from `offset`.
**write**
Write `length` bytes beginning from `offset`.
**sync**
:manpage:`fsync(2)` the file.
**datasync**
:manpage:`fdatasync(2)` the file.
**trim**
Trim the given file from the given `offset` for `length` bytes.
+Trace file format v3
+~~~~~~~~~~~~~~~~~~~~
+
+The third version of the trace file format was added in fio version 3.31. It
+forces each action to have a timestamp associated with it.
+
+The first line of the trace file has to be::
+
+ fio version 3 iolog
+
+Following this can be lines in two different formats, which are described below.
+
+The file management format::
+
+ timestamp filename action
+
+The file I/O action format::
+
+ timestamp filename action offset length
+
+The `timestamp` is relative to the beginning of the run (ie starts at 0). The
+`filename`, `action`, `offset` and `length` are identical to version 2, except
+that version 3 does not allow the `wait` action.
+
+
I/O Replay - Merging Traces
---------------------------
Colocation is a common practice used to get the most out of a machine.
Knowing which workloads play nicely with each other and which ones don't is
a much harder task. While fio can replay workloads concurrently via multiple
jobs, it leaves some variability up to the scheduler making results harder to
reproduce. Merging is a way to make the order of events consistent.
Merging is integrated into I/O replay and done when a
diff --git a/fio.1 b/fio.1
index 98410655..a2ec836f 100644
--- a/fio.1
+++ b/fio.1
@@ -4110,38 +4110,71 @@ The file I/O action format:
.RS
filename action offset length
.P
The `filename' is given as an absolute path, and has to have been \fBadd\fRed and
\fBopen\fRed before it can be used with this format. The `offset' and `length' are
given in bytes. The `action' can be one of these:
.RS
.TP
.B wait
Wait for `offset' microseconds. Everything below 100 is discarded.
-The time is relative to the previous `wait' statement.
+The time is relative to the previous `wait' statement. Note that action `wait`
+is not allowed as of version 3, as the same behavior can be achieved using
+timestamps.
.TP
.B read
Read `length' bytes beginning from `offset'.
.TP
.B write
Write `length' bytes beginning from `offset'.
.TP
.B sync
\fBfsync\fR\|(2) the file.
.TP
.B datasync
\fBfdatasync\fR\|(2) the file.
.TP
.B trim
Trim the given file from the given `offset' for `length' bytes.
.RE
.RE
+.RE
+.TP
+.B Trace file format v3
+The third version of the trace file format was added in fio version 3.31. It
+forces each action to have a timestamp associated with it.
+.RS
+.P
+The first line of the trace file has to be:
+.RS
+.P
+"fio version 3 iolog"
+.RE
+.P
+Following this can be lines in two different formats, which are described below.
+.P
+.B
+The file management format:
+.RS
+timestamp filename action
+.P
+.RE
+.B
+The file I/O action format:
+.RS
+timestamp filename action offset length
+.P
+The `timestamp` is relative to the beginning of the run (ie starts at 0). The
+`filename`, `action`, `offset` and `length` are identical to version 2, except
+that version 3 does not allow the `wait` action.
+.RE
+.RE
.SH I/O REPLAY \- MERGING TRACES
Colocation is a common practice used to get the most out of a machine.
Knowing which workloads play nicely with each other and which ones don't is
a much harder task. While fio can replay workloads concurrently via multiple
jobs, it leaves some variability up to the scheduler making results harder to
reproduce. Merging is a way to make the order of events consistent.
.P
Merging is integrated into I/O replay and done when a \fBmerge_blktrace_file\fR
is specified. The list of files passed to \fBread_iolog\fR go through the merge
process and output a single file stored to the specified file. The output file is
--
2.30.2
