From 5c2c0db4c5d9911f381546ae7d0d07d15b3ccc64 Mon Sep 17 00:00:00 2001 From: Mohamad Gebai Date: Thu, 7 Apr 2022 10:40:31 -0700 Subject: [PATCH] iolog: update man page for version 3 Add documentation for iolog version 3, mainly the differences between versions 2 and 3. Signed-off-by: Mohamad Gebai Link: https://lore.kernel.org/r/20220407174031.599117-4-mogeb@fb.com Signed-off-by: Jens Axboe --- 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 @@ -4398,7 +4398,9 @@ 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** @@ -4411,6 +4413,31 @@ given in bytes. The `action` can be one of these: 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 --------------------------- diff --git a/fio.1 b/fio.1 index 98410655..a2ec836f 100644 --- a/fio.1 +++ b/fio.1 @@ -4117,7 +4117,9 @@ given in bytes. The `action' can be one of these: .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'. @@ -4135,6 +4137,37 @@ Write `length' bytes beginning from `offset'. 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 -- 2.25.1