[PATCH 08/31] blkparse: man: fix typos and formatting, complete and update information

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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



[Index of Archives]     [Netdev]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux