From: Mohamad Gebai <mogeb@fb.com>
To: <fio@vger.kernel.org>
Cc: Mohamad Gebai <mogeb@fb.com>
Subject: [PATCH v3 3/3] iolog: update man page for version 3
Date: Thu, 7 Apr 2022 10:40:31 -0700 [thread overview]
Message-ID: <20220407174031.599117-4-mogeb@fb.com> (raw)
In-Reply-To: <20220407174031.599117-1-mogeb@fb.com>
Add documentation for iolog version 3, mainly the differences between
versions 2 and 3.
Signed-off-by: Mohamad Gebai <mogeb@fb.com>
---
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
next prev parent reply other threads:[~2022-04-07 17:40 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-04-07 17:40 [PATCH v3 0/3] iolog: add version 3 with timestamp support Mohamad Gebai
2022-04-07 17:40 ` [PATCH v3 1/3] iolog: add version 3 to support timestamp-based replay Mohamad Gebai
2022-04-07 17:40 ` [PATCH v3 2/3] iolog: add iolog_write for version 3 Mohamad Gebai
2022-04-07 17:40 ` Mohamad Gebai [this message]
2022-04-08 18:32 ` [PATCH v3 0/3] iolog: add version 3 with timestamp support Jens Axboe
2022-04-08 18:33 ` Jens Axboe
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220407174031.599117-4-mogeb@fb.com \
--to=mogeb@fb.com \
--cc=fio@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.