SYNOPSIS
enumerate options for usage overview
DESCRIPTION
positional <file> argument as alternative to -i <file>
The indentation of 2n seems not enough for print output (PS/PDF)
and it generates the bullet dash on a separate line,
so just use the default indentation which just works.
dump-binary: used by iowatcher(1)
OPTIONS
batch: syntax fix, option argument formatting fix, description
input file: also accepts named pipe (FIFO)
format,format-spec:
* comma separator is not a replaceable argument but literal
* -F allows _individual_ output per event type [clarification]
* -f option is second, so its description goes second
dump-binary: used by iowatcher(1)
stopwatch: colon separator is not a replaceable but literal
TRACE ACTIONS:
* add missing requeued
* remove old duplicates for "front or back merge" (M), M is back merge
* remap: explicitly mention partitions as example, to avoid readers
only think of device-mapper or md when they see "stacked devices"
* add missing message
OUTPUT DESCRIPTION AND FORMATTING:
* mention that format string is similar to C printf, to set expectations
* clarify more details cross references for fields: action, RWBS
* specify formatted data type (string,(unsigned)int,...) for each field
* sequence number is per device and per CPU,
to explain why the output can contain duplicate numbers
* conditions for availability of elapsed time
* add missing description for calendar time %z
* explain field syntax from left to right for readability
* corner cases of using %
* supported escape sequences
* mention newline, which is not implicit
* use newline in example (closer to default output with one event per line)
ACTION IDENTIFIERS
drop confusing duplication of TRACE ACTIONS
DEFAULT OUTPUT => DEFAULT OUTPUT HEADER
* clarify in title that this is only about the HEADER, not PER ACTION
* default header ends with space character
* sequence number is per device and per CPU
* reset left margin before example [.PP], otherwise it looks like the
example only belongs to the description of the last default header field
* disambiguate where the default header ends in the example output
DEFAULT OUTPUT PER ACTION
* is appended to the default header
* default output ends with newline
* add missing actions: requeue (R), message (m), otherwise
* plural typo: parenthesis => parentheses
* missing condition: number of blocks only if not zero
* elapsed time only for I, D, C; describe respective interval, xref btt(1)
* "in either case" as separate paragraph as it applies to both previous
two paragraphs, not only to the second one
* remap (A):
** consistent terms: sector => starting sector, length => number of blocks
** add missing intervening plus (+) character
** add missing original values of remapping
EXAMPLES
* fix formatting in example text: regular not bold after replaceable
* fix blktrace output files names
* add new example for custom output with:
full option argument list resembling default output, limitations
SEE ALSO
* iowatcher(1) because of occurrence with option --dump-binary
Signed-off-by: Steffen Maier <maier@xxxxxxxxxxxxx>
---
doc/blkparse.1 | 301 +++++++++++++++++++++++++++++++++++----------------------
1 file changed, 187 insertions(+), 114 deletions(-)
diff --git a/doc/blkparse.1 b/doc/blkparse.1
index cb21fea52cf8..cedd08e2dc5b 100644
--- a/doc/blkparse.1
+++ b/doc/blkparse.1
@@ -6,7 +6,28 @@ blkparse \- produce formatted output of event streams of block devices
.SH SYNOPSIS
-.B blkparse [ \fIoptions\fR ]
+.B blkparse
+.IR "file ..." " |"
+.BI \-i " file"
+.RB [ \-A
+.IR hex-mask ]
+.RB [ \-a
+.IR mask ]
+.RB [ \-D
+.IR dir ]
+.RB [ \-b
+.IR batch ]
+.RB [ \-F
+.IR typ , fmt ]
+.RB [ \-f
+.IR fmt ]
+.RB [ \-o
+.IR file ]
+.RB [ \-d
+.IR file ]
+.RB [ \-w
+.IR span ]
+.RB [ \-MhOqstvV ]
.br
@@ -17,11 +38,15 @@ information. Specifically, it will take the (machine-readable) output of the
\fIblktrace\fR utility and convert it to a nicely formatted and human-readable
form.
+If one or more optional positional arguments \fIfile\fR are provided,
+they serve as device names of input files. See also \fB-i,--input\fR option
+in section OPTIONS below.
+
As with \fIblktrace\fR, some details concerning \fIblkparse\fR
will help in understanding the command line options presented below.
-.TP 2
+.TP
\-
By default, \fIblkparse\fR expects to run in a post-processing mode; one where
the trace events have been saved by a previous run of blktrace, and blkparse
@@ -33,18 +58,18 @@ An example would be:
% blktrace \-d /dev/sda \-o \- | blkparse \-i \-
-.TP 2
+.TP
\-
-You can set how many blkparse batches event reads via the \fB\-b\fR option, the
+You can set how many event reads blkparse batches via the \fB\-b\fR option, the
default is to handle events in batches of 512.
-.TP 2
+.TP
\-
If you have saved event traces in blktrace with different output names (via
the \fB\-o\fR option to blktrace), you must specify the same input name via the
\fB\-i\fR option.
-.TP 2
+.TP
\-
The format of the output data can be controlled via the \fB\-f\fR or \fB\-F\fR
options \-\- see OUTPUT DESCRIPTION AND FORMATTING for details.
@@ -52,7 +77,8 @@ options \-\- see OUTPUT DESCRIPTION AND FORMATTING for details.
.PP
By default, blkparse sends formatted data to standard output. This may
be changed via the \fB\-o\fR option, or text output can be disabled via the
-\fB\-O\fR option. A merged binary stream can be produced using the \fB\-d\fR
+\fB\-O\fR option. A merged binary stream used by iowatcher (1)
+can be produced using the \fB\-d\fR
option.
@@ -81,9 +107,11 @@ Prepend \fIdir\fR to input file names
\-b \fIbatch\fR
.br
-\-\-batch={batch}
+\-\-batch=\fIbatch\fR
.RS
-Standard input read batching
+Standard input read batching:
+How many events to read in one batch from stdin or from named pipe (FIFO).
+0 or less for default. Default is 512.
.RE
\-i \fIfile\fR
@@ -94,11 +122,12 @@ Specifies base name for input files \-\- default is \fIdevice\fR.blktrace.\fIcpu
As noted above, specifying \fB\-i \-\fR runs in live mode with blktrace
(reading data from standard in).
+You can also specify a named pipe (FIFO) as argument.
.RE
-\-F \fItyp,fmt\fR
+\-F \fItyp\fR,\fIfmt\fR
.br
-\-\-format=\fItyp,fmt\fR
+\-\-format=\fItyp\fR,\fIfmt\fR
.br
\-f \fIfmt\fR
.br
@@ -107,11 +136,11 @@ As noted above, specifying \fB\-i \-\fR runs in live mode with blktrace
Sets output format
(See OUTPUT DESCRIPTION AND FORMATTING for details.)
-The \-f form specifies a format for all events
-
-The \-F form allows one to specify a format for a specific
+The \-F form allows one to specify an individual format for a specific
event type. The single\-character \fItyp\fR field is one of the
-action specifiers described in ACTION IDENTIFIERS.
+action specifiers described in TRACE ACTIONS.
+
+The \-f form specifies a common format for all event types.
.RE
\-M
@@ -148,7 +177,7 @@ Do \fInot\fR produce text output, used for binary (\fB\-d\fR) only
.br
\-\-dump\-binary=\fIfile\fR
.RS
-Binary output file
+Binary output file used by iowatcher (1)
.RE
\-q
@@ -182,7 +211,7 @@ Display traces for the \fIspan\fR specified \-\- where span can be:
.br
or
.br
-\fIstart:end\-time\fR \-\- Display traces from time \fIstart\fR
+\fIstart\fR:\fIend\-time\fR \-\- Display traces from time \fIstart\fR
through end\-time (in ns).
.RE
@@ -242,10 +271,6 @@ begins, so the i/o scheduler can merge them together.
Same as the back merge, except this i/o ends where a previously inserted
requests starts.
-.HP 4
-\fBM -- front or back merge\fR
-One of the above.
-
.HP 4
\fBG -- get request\fR
To send any type of request to a block device, a \fIstruct request\fR
@@ -282,133 +307,117 @@ this and will clone lots of i/o.
.HP 4
\fBA -- remap\fR
-For stacked devices, incoming i/o is remapped to device below it in the i/o
+For stacked devices (incl. partitions),
+incoming i/o is remapped to device below it in the i/o
stack. The remap action details what exactly is being remapped to what.
.HP 4
\fBR -- requeue\fR
Put a request back on queue.
+.HP 4
+\fBm -- message\fR
+Text message generated via kernel call to blk_add_trace_msg()
+from e.g. CFQ I/O scheduler
+or written to /sys/kernel/debug/block/\fIdev\fR/msg
+
.SH "OUTPUT DESCRIPTION AND FORMATTING"
The output from blkparse can be tailored for specific use -- in particular, to ease
-parsing of output, and/or limit output fields to those the user wants to see. The
-data for fields which can be output include:
+parsing of output, and/or limit output fields to those the user wants to see.
+It accepts the following subset similar to a C printf format string.
+The data for fields which can be output include:
.IP \fBa\fR 4
-Action, a (small) string (1 or 2 characters) -- see table below for more details
+Action, a (small) string (1 or 2 characters) -- see section TRACE ACTIONS above for more details
.IP \fBc\fR 4
-CPU id
+CPU id, decimal integer
.IP \fBC\fR 4
-Command
+Command, a string with the process name
.IP \fBd\fR 4
-RWBS field, a (small) string (1-3 characters) -- see section below for more details
+RWBS field, a (small) string (1-3 characters) -- see section RWBS DESCRIPTION below for more details
.IP \fBD\fR 4
-7-character string containing the major and minor numbers of
+7-character string containing the decimal major and minor numbers of
the event's device (separated by a comma).
.IP \fBe\fR 4
-Error value
+Error value, decimal integer
.IP \fBm\fR 4
-Minor number of event's device.
+Minor number of event's device, decimal integer.
.IP \fBM\fR 4
-Major number of event's device.
+Major number of event's device, decimal integer.
.IP \fBn\fR 4
-Number of blocks
+Number of blocks, unsigned decimal integer
.IP \fBN\fR 4
-Number of bytes
+Number of bytes, unsigned decimal integer
.IP \fBp\fR 4
-Process ID
+Process ID, unsigned decimal integer
.IP \fBP\fR 4
-Display packet data \-\- series of hexadecimal values
+Display packet data \-\- series of hexadecimal digits
.IP \fBs\fR 4
-Sequence numbers
+Sequence number per device and per CPU, long decimal integer
.IP \fBS\fR 4
-Sector number
+Sector number, long long unsigned decimal integer
.IP \fBt\fR 4
-Time stamp (nanoseconds)
+Time stamp (nanoseconds), long unsigned decimal integer,
+default width 9 if no width specified
.IP \fBT\fR 4
-Time stamp (seconds)
+Time stamp (seconds), decimal integer
.IP \fBu\fR 4
-Elapsed value in microseconds (\fI\-t\fR command line option)
+Elapsed value in microseconds (\fB\-t\fR command line option),
+unsigned long long decimal integer. You can use this with \fB-F,--format\fR
+option and event types I, D, C (for insert, issue, complete) to provide
+intervals Q2I, I2D, D2C respectively [see also btt (1)]. Elapsed values are
+only provided for file system requests (fs) [see REQUEST TYPES in blktrace (8)].
+Otherwise blkparse exits with error once any other event type appears on the input.
.IP \fBU\fR 4
-Payload unsigned integer
+Payload, unsigned integer
+
+.IP \fBz\fR 4
+Calendar time of time stamp, string with format hh:mm:ss.uuuuuu
+relative to the user's time zone (localtime (3))
.PP
-Note that the user can optionally specify field display width, and optionally a
-left-aligned specifier. These precede field specifiers, with a '%' character,
-followed by the optional left-alignment specifier (\-) followed by the width (a
-decimal number) and then the field.
+Field specifiers start with a '%' character.
+Note that the user can optionally specify a left-alignment,
+and optionally specify a field display width.
+The optional left-alignment specifier (\-) is followed by the width (a
+decimal number).
+Finally, the mandatory field type is given by a character from the list above.
+If a field type character undefined above is used, the output just contains
+the one character, e.g. '%§' outputs '§'.
+Alternatively, '%%', or '%' at the end of the format string, produce one '%'
+in the output.
+
+The format string allows the following escape sequences:
+\&'\\b', '\\n', '\\r', '\\t'
+for backspace, newline, carriage return, or tabulator respectively.
+
+Don't forget a trailing newline character '\\n' if you expect each event
+on a separate output line.
Thus, to specify the command in a 12-character field that is left aligned:
- \-f "%\-12C"
-
-
-.SH "ACTION IDENTIFIERS"
-
-The following table shows the various actions which may be output:
-
-.IP A
-IO was remapped to a different device
-
-.IP B
-IO bounced
-
-.IP C
-IO completion
-
-.IP D
-IO issued to driver
-
-.IP F
-IO front merged with request on queue
-
-.IP G
-Get request
-
-.IP I
-IO inserted onto request queue
-
-.IP M
-IO back merged with request on queue
-
-.IP P
-Plug request
-
-.IP Q
-IO handled by request queue code
-
-.IP S
-Sleep request
-
-.IP T
-Unplug due to timeout
-
-.IP U
-Unplug request
-
-.IP X
-Split
+ \-f "%\-12C\\n"
.SH "RWBS DESCRIPTION"
@@ -418,11 +427,12 @@ for write, or 'D' for block discard operation), and optionally either
a 'B' (for barrier operations) or 'S' (for synchronous operations).
-.SH "DEFAULT OUTPUT"
+
+.SH "DEFAULT OUTPUT HEADER"
The standard header (or initial fields displayed) include:
- "%D %2c %8s %5T.%9t %5p %2a %3d"
+ "%D %2c %8s %5T.%9t %5p %2a %3d "
Breaking this down:
@@ -433,7 +443,7 @@ Displays the event's device major/minor as: %3d,%\-3d.
CPU ID (2-character field).
.IP \fB%8s\fR
-Sequence number
+Sequence number per device and per CPU
.IP \fB%5T.%9t\fR
5-character field for the seconds portion of the time stamp and a 9-character field for the nanoseconds in the time stamp.
@@ -447,26 +457,38 @@ Sequence number
.IP \fB%3d\fR
3-character field for the RWBS data.
+.PP
Seeing this in action:
8,0 3 1 0.000000000 697 G W 223490 + 8 [kjournald]
-The header is the data in this line up to the 223490 (starting block).
+The header is the data in this line to just before the 223490 (starting block).
The default output for all event types includes this header.
.SH "DEFAULT OUTPUT PER ACTION"
+The additional output described in the following is appended to the
+standard header from section DEFAULT OUTPUT HEADER above.
+The default output ends each event with a newline character '\\n'.
+
\fBC \-\- complete\fR
+.br
+\fBR \-\- requeue\fR
.RS 4
If a payload is present, this is presented between
-parenthesis following the header, followed by the error value.
+parentheses following the header.
-If no payload is present, the sector and number of blocks are presented
-(with an intervening plus (+) character). If the \fB\-t\fR option
-was specified, then the elapsed time is presented. In either case,
-it is followed by the error value for the completion.
+If no payload is present, the sector is presented. If the number of
+blocks is non-zero, an intervening plus (+) character and the number
+of blocks are presented, too. If the action is complete (C) and the
+\fB\-t\fR option was specified, then the elapsed time since issue (D)
+is presented (in parentheses) [see also D2C in btt (1)].
+
+In either case,
+it is followed by the error value for the completion
+(surrounded by square brackets).
.RE
\fBB \-\- bounced\fR
@@ -478,11 +500,15 @@ it is followed by the error value for the completion.
\fBQ \-\- queued\fR
.RS 4
If a payload is present, the number of payload bytes
-is output, followed by the payload in hexadecimal between parenthesis.
+is output, followed by the payload in hexadecimal between parentheses.
If no payload is present, the sector and number of blocks are presented
-(with an intervening plus (+) character). If the \fB\-t\fR option was
-specified, then the elapsed time is presented (in parenthesis). In
+(with an intervening plus (+) character) unless number of blocks is zero.
+If the action is inserted (I) or issued (D), and the \fB\-t\fR option was
+specified, then the elapsed time since queue (Q) or issue (I) respectively
+is presented (in parentheses) [see also Q2I or I2D in btt (1)].
+
+In
either case, it is followed by the command associated with the event
(surrounded by square brackets).
.RE
@@ -496,7 +522,8 @@ either case, it is followed by the command associated with the event
\fBS \-\- sleep\fR
.RS 4
The starting sector and number of blocks is output
-(with an intervening plus (+) character), followed by the command
+(with an intervening plus (+) character) unless number of blocks is zero,
+followed by the command
associated with the event (surrounded by square brackets).
.RE
@@ -518,19 +545,31 @@ requests outstanding.
\fBX \-\- split\fR
.RS 4
The original starting sector followed by the new
-sector (separated by a slash (/) is output, followed by the command
+sector (separated by a slash (/)) is output, followed by the command
associated with the event (surrounded by square brackets).
.RE
\fBA \-\- remap\fR
.RS 4
-Sector and length is output, along with the original
-device and sector offset.
+The starting sector and number of blocks is output
+(with an intervening plus (+) character), followed by a textual left arrow
+" <- " as well as original major and minor device number (in parentheses,
+separated by comma) and original sector offset.
+.RE
+
+\fBm \-\- message\fR
+.RS 4
+The message string.
+.RE
+
+otherwise
+.RS 4
+"Unknown action " followed by the action character.
.RE
.SH EXAMPLES
-To trace the i/o on the device \fI/dev/sda\fB and parse the output to human
+To trace the i/o on the device \fI/dev/sda\fR and parse the output to human
readable form, use the following command:
% blktrace \-d /dev/sda \-o \- | blkparse \-i \-
@@ -550,8 +589,9 @@ To trace the i/o on a device and save the output for later processing with
% blktrace /dev/sda /dev/sdb
This will trace i/o on the devices \fI/dev/sda\fR and \fI/dev/sdb\fR and save
-the recorded information in the files \fIsda\fR and \fIsdb\fR in the current
-directory, for the two different devices, respectively. This trace
+the recorded information in the files \fIsda\fR.blktrace.* and
+\fIsdb\fR.blktrace.* in the current
+directory, for the two different devices and per CPU, respectively. This trace
information can later be parsed by the \fIblkparse\fR utility:
% blkparse sda sdb
@@ -559,6 +599,38 @@ information can later be parsed by the \fIblkparse\fR utility:
which will output the previously recorded tracing information in human
readable form to stdout.
+To customize trace output formatting based on the defaults described in
+section DEFAULT OUTPUT HEADER and DEFAULT OUTPUT PER ACTION, start with
+the following and modify individual parts as you like:
+
+ % blkparse sda sdb -t \\
+ -F C,"%D %2c %8s %5T.%9t %5p %2a %3d %S + %n (%8u) (%P) [%e]\\n" \\
+ -F R,"%D %2c %8s %5T.%9t %5p %2a %3d %S + %n () (%P) [%e]\\n" \\
+ -F B,"%D %2c %8s %5T.%9t %5p %2a %3d %S + %n () %N (%P) [%C]\\n" \\
+ -F D,"%D %2c %8s %5T.%9t %5p %2a %3d %S + %n (%8u) %N (%P) [%C]\\n" \\
+ -F I,"%D %2c %8s %5T.%9t %5p %2a %3d %S + %n (%8u) %N (%P) [%C]\\n" \\
+ -F Q,"%D %2c %8s %5T.%9t %5p %2a %3d %S + %n () %N (%P) [%C]\\n" \\
+ -F F,"%D %2c %8s %5T.%9t %5p %2a %3d %S + %n [%C]\\n" \\
+ -F G,"%D %2c %8s %5T.%9t %5p %2a %3d %S + %n [%C]\\n" \\
+ -F M,"%D %2c %8s %5T.%9t %5p %2a %3d %S + %n [%C]\\n" \\
+ -F S,"%D %2c %8s %5T.%9t %5p %2a %3d %S + %n [%C]\\n" \\
+ -F P,"%D %2c %8s %5T.%9t %5p %2a %3d [%C]\\n" \\
+ -F U,"%D %2c %8s %5T.%9t %5p %2a %3d [%C] %U\\n" \\
+ -F T,"%D %2c %8s %5T.%9t %5p %2a %3d [%C] %U\\n" \\
+ -F X,"%D %2c %8s %5T.%9t %5p %2a %3d %S / %U [%C]\\n" \\
+ -F A,"%D %2c %8s %5T.%9t %5p %2a %3d %S + %n <- (\fIOmaj\fR,\fIOmin\fR) \fIOsec\fR\\n"
+
+The custom format syntax from section OUTPUT DESCRIPTION AND FORMATTING
+does not support conditional output. Thus, the example output differs
+by printing all information instead of skipping some based on conditions.
+
+Currently it is not possible to specify 'm' as custom type specifier
+for message events. A custom field for the message text as string does
+not exist, %P for a hexdump comes closest.
+Also, for remap events (A), the major and minor number of the original
+device as well as the original sector offset are currently not
+available as custom fields.
+
.SH AUTHORS
\fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This
@@ -583,5 +655,6 @@ On Debian systems, the text of the GNU General Public License can be found in
/usr/share/common\-licenses/GPL\-2.
.SH "SEE ALSO"
-btrace (8), blktrace (8), verify_blkparse (1), blkrawverify (1), btt (1)
+btrace (8), blktrace (8), verify_blkparse (1), blkrawverify (1), btt (1),
+iowatcher (1)
--
2.14.2
--
To unsubscribe from this list: send the line "unsubscribe linux-btrace" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
