From 98eee4e48b9461a04c2461a856c9592d504a6fb1 Mon Sep 17 00:00:00 2001 From: Jens Axboe Date: Tue, 24 Jul 2007 16:02:28 +0200 Subject: [PATCH] Add man pages Thanks to Bas Zoetekouw for providing these! And shame on me for forgetting to add them to the git repo. Signed-off-by: Jens Axboe --- Makefile | 3 + doc/blkparse.1 | 565 ++++++++++++++++++++++++++++++++++++++++++ doc/blkrawverify.1 | 47 ++++ doc/blktrace.8 | 255 +++++++++++++++++++ doc/btrace.8 | 84 +++++++ doc/btt.1 | 192 ++++++++++++++ doc/verify_blkparse.1 | 44 ++++ 7 files changed, 1190 insertions(+) create mode 100644 doc/blkparse.1 create mode 100644 doc/blkrawverify.1 create mode 100644 doc/blktrace.8 create mode 100644 doc/btrace.8 create mode 100644 doc/btt.1 create mode 100644 doc/verify_blkparse.1 diff --git a/Makefile b/Makefile index d7bffcd..1cd5a70 100644 --- a/Makefile +++ b/Makefile @@ -39,6 +39,7 @@ depend: INSTALL = install prefix = /usr/local bindir = $(prefix)/bin +mandir = $(prefix)/man RPMBUILD = rpmbuild TAR = tar @@ -63,6 +64,8 @@ install: $(PROGS) $(SCRIPTS) $(INSTALL) -m755 -d $(DESTDIR)$(bindir) $(INSTALL) $(PROGS) $(SCRIPTS) $(DESTDIR)$(bindir) $(INSTALL) btt/btt $(DESTDIR)$(bindir) + $(INSTALL) doc/*.1 $(DESTDIR)$(mandir)/man1 + $(INSTALL) doc/*.8 $(DESTDIR)$(mandir)/man8 ifneq ($(wildcard .depend),) include .depend diff --git a/doc/blkparse.1 b/doc/blkparse.1 new file mode 100644 index 0000000..825ca36 --- /dev/null +++ b/doc/blkparse.1 @@ -0,0 +1,565 @@ +.TH BLKTPARSE 1 "March 6, 2007" "blktrace git\-20070306202522" "" + + +.SH NAME +blkparse \- produce formatted output of event streams of block devices + + +.SH SYNOPSIS +.B blkparse [ \fIoptions\fR ] +.br + + +.SH DESCRIPTION +The \fIblkparse\fR utility will attempt to combine streams of events for +various devices on various CPUs, and produce a formatted output of the event +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. + +As with \fIblktrace\fR, some details concerning \fIblkparse\fR +will help in understanding the command line options presented below. + + +.TP 2 +\- +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 +is combining event streams and dumping formatted data. + +blkparse may be run in a live manner concurrently with blktrace by specifying +\fB\-i \-\fR to blkparse, and combining it with the live option for blktrace. +An example would be: + + % blktrace \-d /dev/sda \-o \- | blkparse \-i \- + +.TP 2 +\- +You can set how many blkparse batches event reads via the \fB\-b\fR option, the +default is to handle events in batches of 512. + +.TP 2 +\- +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 +\- +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. + +.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 +option. + + + +.SH OPTIONS + +\-b \fIbatch\fR +.br +\-\-batch={batch} +.RS +Standard input read batching +.RE + +\-i \fIfile\fR +.br +\-\-input=\fIfile\fR +.RS +Specifies base name for input files \-\- default is \fIdevice\fR.blktrace.\fIcpu\fR. + +As noted above, specifying \fB\-i \-\fR runs in live mode with blktrace +(reading data from standard in). +.RE + +\-F \fItyp,fmt\fR +.br +\-\-format=\fItyp,fmt\fR +.br +\-f \fIfmt\fR +.br +\-\-format\-spec=\fIfmt\fR +.RS +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 +event type. The single\-character \fItyp\fR field is one of the +action specifiers described in ACTION IDENTIFIERS. +.RE + +\-m +.br +\-\-missing +.RS +Print missing entries +.RE + +\-h +.br +\-\-hash\-by\-name +.RS +Hash processes by name, not by PID +.RE + +\-o \fIfile\fR +.br +\-\-output=\fIfile\fR +.RS +Output file +.RE + +\-O +.br +\-\-no\-text\-output +.RS +Do \fInot\fR produce text output, used for binary (\fB\-d\fR) only +.RE + +\-d \fIfile\fR +.br +\-\-dump\-binary=\fIfile\fR +.RS +Binary output file +.RE + +\-q +.br +\-\-quiet +.RS +Quiet mode +.RE + +\-s +.br +\-\-per\-program\-stats +.RS +Displays data sorted by program +.RE + +\-t +.br +\-\-track\-ios +.RS +Display time deltas per IO +.RE + +\-w \fIspan\fR +.br +\-\-stopwatch=\fIspan\fR +.RS +Display traces for the \fIspan\fR specified \-\- where span can be: +.br +\fIend\-time\fR \-\- Display traces from time 0 through \fIend\-time\fR (in ns) +.br +or +.br +\fIstart:end\-time\fR \-\- Display traces from time \fIstart\fR +through end\-time (in ns). +.RE + +\-v +.br +\-\-verbose +.RS +More verbose marginal on marginal errors +.RE + +\-V +.br +\-\-version +.RS +Display version +.RE + + +.SH "TRACE ACTIONS" +The following trace actions are recognised: + +.HP 4 +\fBC -- complete\fR +A previously issued request has been completed. The output will detail the +sector and size of that request, as well as the success or failure of it. + +.HP 4 +\fBD -- issued\fR +A request that previously resided on the block layer queue or in the i/o +scheduler has been sent to the driver. + +.HP 4 +\fBI -- inserted\fR +A request is being sent to the i/o scheduler for addition to the internal queue +and later service by the driver. The request is fully formed at this time. + +.HP 4 +\fBQ -- queued\fR +This notes intent to queue i/o at the given location. No real requests exists +yet. + +.HP 4 +\fBB -- bounced\fR +The data pages attached to this \fIbio\fR are not reachable by the hardware +and must be bounced to a lower memory location. This causes a big slowdown in +i/o performance, since the data must be copied to/from kernel buffers. Usually +this can be fixed with using better hardware -- either a better i/o controller, +or a platform with an IOMMU. + +.HP 4 +\fBM -- back merge\fR +A previously inserted request exists that ends on the boundary of where this i/o +begins, so the i/o scheduler can merge them together. + +.HP 4 +\fBF -- front merge\fR +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 +\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 +container must be allocated first. + +.HP 4 +\fBS -- sleep\fR +No available request structures were available, so the issuer has to wait for +one to be freed. + +.HP 4 +\fBP -- plug\fR +When i/o is queued to a previously empty block device queue, Linux will plug the +queue in anticipation of future ios being added before this data is needed. + +.HP 4 +\fBU -- unplug\fR +Some request data already queued in the device, start sending requests to the +driver. This may happen automatically if a timeout period has passed (see next +entry) or if a number of requests have been added to the queue. + +.HP 4 +\fBT -- unplug due to timer\fR +If nobody requests the i/o that was queued after plugging the queue, Linux will +automatically unplug it after a defined period has passed. + +.HP 4 +\fBX -- split\fR +On raid or device mapper setups, an incoming i/o may straddle a device or +internal zone and needs to be chopped up into smaller pieces for service. This +may indicate a performance problem due to a bad setup of that raid/dm device, +but may also just be part of normal boundary conditions. dm is notably bad at +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 +stack. The remap action details what exactly is being remapped to what. + + + + +.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: + +.IP \fBa\fR 4 +Action, a (small) string (1 or 2 characters) -- see table below for more details + +.IP \fBc\fR 4 +CPU id + +.IP \fBC\fR 4 +Command + +.IP \fBd\fR 4 +RWBS field, a (small) string (1-3 characters) -- see section below for more details + +.IP \fBD\fR 4 +7-character string containing the major and minor numbers of +the event's device (separated by a comma). + +.IP \fBe\fR 4 +Error value + +.IP \fBm\fR 4 +Minor number of event's device. + +.IP \fBM\fR 4 +Major number of event's device. + +.IP \fBn\fR 4 +Number of blocks + +.IP \fBN\fR 4 +Number of bytes + +.IP \fBp\fR 4 +Process ID + +.IP \fBP\fR 4 +Display packet data \-\- series of hexadecimal values + +.IP \fBs\fR 4 +Sequence numbers + +.IP \fBS\fR 4 +Sector number + +.IP \fBt\fR 4 +Time stamp (nanoseconds) + +.IP \fBT\fR 4 +Time stamp (seconds) + +.IP \fBu\fR 4 +Elapsed value in microseconds (\fI\-t\fR command line option) + +.IP \fBU\fR 4 +Payload unsigned integer + +.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. + +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 + + +.SH "RWBS DESCRIPTION" + +This is a small string containing at least one character ('R' for read, 'W' for +write operation), and optionally either a 'B' (for barrier operations) or 'S' (for +synchronous operations). + + +.SH "DEFAULT OUTPUT" + +The standard header (or initial fields displayed) include: + + "%D %2c %8s %5T.%9t %5p %2a %3d" + +Breaking this down: + +.IP \fB%D\fR +Displays the event's device major/minor as: %3d,%\-3d. + +.IP \fB%2c\fR +CPU ID (2-character field). + +.IP \fB%8s\fR +Sequence number + +.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. + +.IP \fB%5p\fR +5-character field for the process ID. + +.IP \fB%2a\fR +2-character field for one of the actions. + +.IP \fB%3d\fR +3-character field for the RWBS data. + +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 default output for all event types includes this header. + + + +.SH "DEFAULT OUTPUT PER ACTION" + +\fBC \-\- complete\fR +.RS 4 +If a payload is present, this is presented between +parenthesis following the header, followed by the error value. + +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. +.RE + +\fBB \-\- bounced\fR +.br +\fBD \-\- issued\fR +.br +\fBI \-\- inserted\fR +.br +\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. + +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 +either case, it is followed by the command associated with the event +(surrounded by square brackets). +.RE + +\fBF \-\- front merge\fR +.br +\fBG \-\- get request\fR +.br +\fBM \-\- back merge\fR +.br +\fBS \-\- sleep\fR +.RS 4 +The starting sector and number of blocks is output +(with an intervening plus (+) character), followed by the command +associated with the event (surrounded by square brackets). +.RE + +\fBP \-\- plug\fR +.RS 4 +The command associated with the event (surrounded by +square brackets) is output. +.RE + +\fBU \-\- unplug\fR +.br +\fBT \-\- unplug due to timer\fR +.RS 4 +The command associated with the event +(surrounded by square brackets) is output, followed by the number of +requests outstanding. +.RE + +\fBX \-\- split\fR +.RS 4 +The original starting sector followed by the new +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. +.RE + + +.SH EXAMPLES +To trace the i/o on the device \fI/dev/hda\fB and parse the output to human +readable form, use the following command: + + % blktrace \-d /dev/sda \-o \- | blkparse \-i \- + +(see \fIblktrace\fR (8) for more information). +This same behaviour can be achieve with the convenience script \fIbtrace\fR. +The command + + % btrace /dev/sda + +has exactly the same effect as the previous command. See \fIbtrace\fR (8) for +more information. + +To trace the i/o on a device and save the output for later processing with +\fIblkparse\fR, use \fIblktrace\fR like this: + + % 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 +information can later be parsed by the \fIblkparse\fR utility: + + % blkparse sda sdb + +which will output the previously recorded tracing information in human +readable form to stdout. + + +.SH AUTHORS +\fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This +man page was created from the \fIblktrace\fR documentation by Bas Zoetekouw. + + +.SH "REPORTING BUGS" +Report bugs to + +.SH COPYRIGHT +Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott. +.br +This is free software. You may redistribute copies of it under the terms of +the GNU General Public License . +There is NO WARRANTY, to the extent permitted by law. +.br +This manual page was created for Debian by Bas Zoetekouw. It was derived from +the documentation provided by the authors and it may be used, distributed and +modified under the terms of the GNU General Public License, version 2. +.br +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) + diff --git a/doc/blkrawverify.1 b/doc/blkrawverify.1 new file mode 100644 index 0000000..1c52292 --- /dev/null +++ b/doc/blkrawverify.1 @@ -0,0 +1,47 @@ +.TH BLKRAWVERIFY 1 "March 6, 2007" "blktrace git\-20070306202522" "" + + +.SH NAME +blkrawverify \- verifies an output file produced by blkparse + + +.SH SYNOPSIS +.B verify_blkparse <\fIdev\fR> [<\fIdev\fR>...] +.br + + +.SH DESCRIPTION + +The \fIblkrawverify\fR utility can be used to verify data retrieved via +\fIblktrace\fR. It will check for valid event formats, forward progressing +sequence numbers and time stamps, also does reasonable checks for other +potential issues within individual events. + +Errors found will be tracked in <\fIdev\fR>.verify.out. + + +.SH AUTHORS +\fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This +man page was created from the \fIblktrace\fR documentation by Bas Zoetekouw. + + +.SH "REPORTING BUGS" +Report bugs to + +.SH COPYRIGHT +Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott. +.br +This is free software. You may redistribute copies of it under the terms of +the GNU General Public License . +There is NO WARRANTY, to the extent permitted by law. +.br +This manual page was created for Debian by Bas Zoetekouw. It was derived from +the documentation provided by the authors and it may be used, distributed and +modified under the terms of the GNU General Public License, version 2. +.br +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), blkparse (1), verify_blkparse (1), btt (1) + diff --git a/doc/blktrace.8 b/doc/blktrace.8 new file mode 100644 index 0000000..99383f1 --- /dev/null +++ b/doc/blktrace.8 @@ -0,0 +1,255 @@ +.TH BLKTRACE 8 "March 6, 2007" "blktrace git\-20070306202522" "" + + +.SH NAME +blktrace \- generate traces of the i/o traffic on block devices + + +.SH SYNOPSIS +.B blktrace \-d \fIdev\fR [ \-r \fIdebugfs_path\fR ] [ \-o \fIoutput\fR ] [\-k ] [ \-w \fItime\fR ] [ \-a \fIaction\fR ] [ \-A \fIaction_mask\fR ] [ \-v ] +.br + + +.SH DESCRIPTION +blktrace is a block layer IO tracing mechanism which provides detailed +information about request queue operations up to user space. There are three +major components: a kernel component, a utility to record the i/o trace +information for the kernel to user space, and utilities to analyse and view the +trace information. This man page describes blktrace, which records the i/o event +trace information for a specific block device to a file. + +The \fBblktrace\fR utility extracts event traces from the kernel (via +the relaying through the debug file system). Some background details +concerning the run\-time behaviour of blktrace will help to understand some +of the more arcane command line options: + +.TP 2 +\- +blktrace receives data from the kernel in buffers passed up through the +debug file system (relay). Each device being traced has a file created in +the mounted directory for the debugfs, which defaults to +\fI/sys/kernel/debug\fR \-\- this can be overridden with the \fB\-r\fR command +line argument. + +.TP 2 +\- +blktrace defaults to collecting all events that can be traced. To +limit the events being captured, you can specify one or more filter masks +via the \fB\-a\fR option. + +Alternatively, one may specify the entire mask utilising a hexadecimal +value that is version\-specific. (Requires understanding of the internal +representation of the filter mask.) + +.TP 2 +\- +As noted above, the events are passed up via a series of buffers stored +into debugfs files. The size and number of buffers can be specified via +the \fB\-b\fR and \fB\-n\fR arguments respectively. + +.TP 2 +\- +blktrace stores the extracted data into files stored in the +local directory. The format of the file names is (by default) +\fBdevice\fR.\fBblktrace\fR.\fBcpu\fR, where \fBdevice\fR is the base +device name (e.g, if we are tracing /dev/sda, the base device name would +be \fBsda\fR); and \fBcpu\fR identifies a CPU for the event stream. + +The \fBdevice\fR portion of the event file name can be changed via +the \fB\-o\fR option. + +.TP 2 +\- +blktrace may also be run concurrently with blkparse to produce +\fBlive\fR output \-\- to do this specify \fB\-o \-\fR for blktrace. + +.TP 2 +\- +The default behaviour for blktrace is to run forever until explicitly +killed by the user (via a control-C, or kill utility invocation). +There are two ways to modify this: + +.TP 5 + 1. +You may utilise the blktrace utility itself to kill +a running trace -- via the \fB\-k\fR option. + +.TP 5 + 2. +You can specify a run-time duration for blktrace via the +\fB\-w\fR option -- then blktrace will run for the specified number +of seconds, and then halt. + + +.SH OPTIONS + +\-A \fIhex-mask\fR +.br +\-\-set-mask=\fIhex-mask\fR +.RS +Set filter mask to \fIhex-mask\fR (see below for masks) +.RE + +\-a \fImask\fR +.br +\-\-act-mask=\fImask\fR +.RS +Add \fImask\fR to current filter (see below for masks) +.RE + +\-b \fIsize\fR +.br +\-\-buffer\-size=\fIsize\fR +.RS +Specifies buffer size for event extraction (scaled by 1024) +.RE + +\-d \fIdev\fR +.br +\-\-dev=\fIdev\fR +.RS +Adds \fIdev\fR as a device to trace +.RE + +\-I \fIfile\fR +.br +\-\-input-devs=\fIfile\fR +.RS +Adds the devices found in \fIfile\fR as devices to trace + +\-k +.br +\-\-kill +.RS +Kill on-going trace +.RE + +\-n \fInum\-sub\fR +.br +\-\-num\-sub=\fInum-sub\fR +.RS +Specifies number of buffers to use +.RE + +\-o \fIfile\fR +.br +\-\-output=\fIfile\fR +.RS +Prepend \fIfile\fR to output file name(s) +.RE + +\-r \fIrel-path\fR +.br +\-\-relay=\fIrel-path\fR +.RS +Specifies debugfs mount point +.RE + +\-V +.br +\-\-version +Outputs version +.RE + +\-w \fIseconds\fR +.br +\-\-stopwatch=\fIseconds\fR +.RS +Sets run time to the number of seconds specified +.RE + + +.SH FILTER MASKS +The following masks may be passed with the \fI\-a\fR command line +option, multiple filters may be combined via multiple \fI\-a\fR command +line options. + +.RS +\fIbarrier\fR: barrier attribute +.br +\fIcomplete\fR: completed} by driver +.br +\fIfs\fR: requests +.br +\fIissue\fR: issued to driver +.br +\fIpc\fR: packet command events +.br +\fIqueue\fR: queue operations +.br +\fIread\fR: read traces +.br +\fIrequeue\fR: requeue operations +.br +\fIsync\fR: synchronous attribute +.br +\fIwrite\fR: write traces +.RE + + +.SH REQUEST TYPES +blktrace distinguishes between two types of block layer requests, file system +and SCSI commands. The former are dubbed \fBfs\fR requests, the latter +\fBpc\fR requests. File system requests are normal read/write operations, i.e. +any type of read or write from a specific disk location at a given size. These +requests typically originate from a user process, but they may also be +initiated by the vm flushing dirty data to disk or the file system syncing a +super or journal block to disk. \fBpc\fR requests are SCSI commands. blktrace +sends the command data block as a payload so that blkparse can decode it. + + +.SH EXAMPLES +To trace the i/o on the device \fI/dev/hda\fB and parse the output to human +readable form, use the following command: + + % blktrace \-d /dev/sda \-o \- | blkparse \-i \- + +This same behaviour can be achieve with the convenience script \fIbtrace\fR. +The command + + % btrace /dev/sda + +has exactly the same effect as the previous command. See \fIbtrace\fR (8) for +more information. + +To trace the i/o on a device and save the output for later processing with +\fIblkparse\fR, use \fIblktrace\fR like this: + + % 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 +information can later be parsed by the \fIblkparse\fR utility: + + % blkparse sda sdb + +which will output the previously recorded tracing information in human +readable form to stdout. See \fIblkparse\fR (1) for more information. + + +.SH AUTHORS +blktrace was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This +man page was created from the blktrace documentation by Bas Zoetekouw. + + +.SH "REPORTING BUGS" +Report bugs to + +.SH COPYRIGHT +Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott. +.br +This is free software. You may redistribute copies of it under the terms of +the GNU General Public License . +There is NO WARRANTY, to the extent permitted by law. +.br +This manual page was created for Debian by Bas Zoetekouw. It was derived from +the documentation provided by the authors and it may be used, distributed and +modified under the terms of the GNU General Public License, version 2. +.br +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), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1) + diff --git a/doc/btrace.8 b/doc/btrace.8 new file mode 100644 index 0000000..dc99a59 --- /dev/null +++ b/doc/btrace.8 @@ -0,0 +1,84 @@ +.TH BTRACE 8 "March 6, 2007" "blktrace git\-20070306202522" "" + + +.SH NAME +btrace \- verifies an output file produced by blkparse + + +.SH SYNOPSIS +.B Usage: btrace [\-s] [\-t] [\-w \fIN\fN] [\-n \fIN\fR] [\-b \fIN\fR] [\-a <\fItrace\fR>...] <\fIdev\fR>... +.br + + +.SH DESCRIPTION + +The \fIbtrace\fR script provides a quick and easy way to to live tracing of +block devices. All it does is calling \fIblktrace\fR on the specified devices +and piping its output through \fIblkparse\fR for formatting. See blktrace (8) +for more in-depth information about how \fIblktrace\fR works. + +.SH OPTIONS + +.HP 4 +.B \-s +Displays data sorted by program (see \fIblkparse\fR (1)). + +.HP 4 +.B \-t +Display time deltas per IO (see \fIblkparse\fR (1)). + +.HP 4 +.B \-w \fIN\fR +Sets run time to the number of seconds specified (see \fIblktrace\fR (8)). + +.HP 4 +.B \-n \fIN\fR +Specifies the number of buffers to use (see \fIblktrace\fR (8)). + +.HP 4 +.B \-b \fIN\fR +Specifies buffer size for event extraction (scaled by 1024) (see +\fIblktrace\fR (8)). + +.HP 4 +.B \-a <\fItrace\fR>... +Add mask to current filter (see \fIblktrace\fR (8)). + +.HP 4 +.B <\fIdev\fR> +Specifies the device to trace. + + +.SH EXAMPLE +Simply running + + % blktrace /dev/sda + +will show a trace of the device \fI/dev/sda\fR. + + +.SH AUTHORS +\fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This +man page was created from the \fIblktrace\fR documentation by Bas Zoetekouw. + + +.SH "REPORTING BUGS" +Report bugs to + +.SH COPYRIGHT +Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott. +.br +This is free software. You may redistribute copies of it under the terms of +the GNU General Public License . +There is NO WARRANTY, to the extent permitted by law. +.br +This manual page was created for Debian by Bas Zoetekouw. It was derived from +the documentation provided by the authors and it may be used, distributed and +modified under the terms of the GNU General Public License, version 2. +.br +On Debian systems, the text of the GNU General Public License can be found in +/usr/share/common\-licenses/GPL\-2. + +.SH "SEE ALSO" +blktrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1) + diff --git a/doc/btt.1 b/doc/btt.1 new file mode 100644 index 0000000..febf784 --- /dev/null +++ b/doc/btt.1 @@ -0,0 +1,192 @@ +.TH BTT 1 "March 06, 2007" "blktrace git\-20070306202522" "" + + +.SH NAME +btt \- analyse block i/o traces produces by blktrace + + +.SH SYNOPSIS +.B btt [options] \-i <\fIinput file\fR> +.br +.B btt \-h | \-\-help +.br +.B btt \-V | \-\-version +.br + + +.SH DESCRIPTION + +btt will take in binary dump data from blkparse, and analyse the events, +producing a series of output from the analysis. It will also build .dat +files containing "range data" -- showing things like Q activity (periods +of time while Q events are being produced), C activity (likewise for +command completions), and etc. + + +.SH OPTIONS + +.B \-h +.br +.B \-\-help +.RS 4 +Shows a short summary of possible command line option +.RE + +.B \-V +.br +.B \-\-version +.RS 4 +Shows the version of btt. +.RE + +.B \-i +.br +.RS 4 +Specifies the input file to analyse. This should be a trace file as produces +by \fIblktrace\fR (8). +.RE + +.B \-d <\fIseconds\fR> +.br +.B \-\-range\-delta=<\fIseconds\fR> +.RS 4 +The \-d option allows you to specify the granularity which determines +"activity" with regard to the .dat files \-\- this specific the time +(in seconds) that must elapse without a particular event occurring to +signify inactivity. The larger the number, the fewer ranges output \-\- +the default is 0.1 seconds. +.RE + +.B \-D <\fIdev;...\fR> +.br +.B \-\-devices=<\fIdev;...\fR> +.RS 4 +The \-D option supplies the devices which should be looked at when +analysing the input. This is a ":" separated list of devices, devices are +specified by a mjr,mnr tuple (e.g.: \-D "8,0:8,8" specifies two devices +with major 8 and minor 0 and 8 respectively). +.RE + +.B \-e <\fIexe,...\fR> +.br +.B \-\-exes=<\fIexe,...\fR> +.RS 4 +The \-e option supplies the list of executables that will have I/Os +analysed. +.RE + +.B \-I <\fIoutput name\fR> +.br +.B \-\-iostat=<\fIoutput name\fR> +.RS 4 +The \-I option directs btt to output iostat\-like data to the specified +file. Refer to the iostat (sysstat) documentation for details on the +data columns. +.RE + +.B \-l <\fIoutput name\fR> +.br +.B \-\-d2c\-latencies=<\fIoutput name\fR> +.RS 4 +The \-l option allows one to output per\-IO D2C latencies +respectively. The supplied argument provides the basis for the output +name for each device. +.RE + +.B \-M <\fIdev map\fR> +.br +.B \-\-dev\-maps=<\fIdev map\fR> +.RS 4 +The \-M option takes in a file generated by the provided script +(gen_disk_info.py), and allows for better output of device names. +.RE + +.B \-o <\fIoutput name\fR> +.br +.B \-\-output\-file=<\fIoutput name\fR> +.RS 4 +Specifies the output file name. +.RE + +.B \-p <\fIoutput name\fR> +.br +.B \-\-per\-io\-dump=<\fIoutput name\fR> +.RS 4 +The \-p option will generate a file that contains a list of all IO +"sequences" \- showing the parts of each IO (Q, A, I/M, D, & C). +.RE + +.B \-q <\fIoutput name\fR> +.br +.B \-\-q2c\-latencies=<\fIoutput name\fR> +.RS 4 +The \-q option allows one to output per\-IO Q2C latencies +respectively. The supplied argument provides the basis for the output +name for each device. +.RE + +.B \-s <\fIoutput name\fR> +.br +.B \-\-seeks=<\fIoutput name\fR> +.RS 4 +The \-s option instructs btt to output seek data, the argument provided +is the basis for file names output. There are two files per device, +read seeks and write seeks. +.RE + +.B \-S <\fIinterval\fR> +.br +.B \-\-iostat\-interval=<\fIinterval\fR> +.RS 4 +The \-S option specifies the interval to use between data +output, it defaults to once per second. +.RE + +.B \-t <\fIsec\fR> +.br +.B \-\-time\-start=<\fIsec\fR> +.br +.B \-T <\fIsec\fR> +.br +.B \-\-time\-end=<\fIsec\fR> +.RS 4 +The \-t/\-T options allow one to set a start and/or end time for analysing +\- analysing will only be done for traces after \-t's argument and before +\-T's argument. (\-t and \-T are optional, so if you specify just \-t, +analysis will occur for all traces after the time specified. Similarly, +if only \-T is specified, analysis stops after \-T's seconds.) +.RE + +.B \-v +.br +.B \-\-verbose +.RS 4 +Requests a more verbose output. +.RE + + +.SH AUTHORS +\fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This +man page was created from the \fIblktrace\fR documentation by Bas Zoetekouw. + + +.SH "REPORTING BUGS" +Report bugs to + +.SH COPYRIGHT +Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott. +.br +This is free software. You may redistribute copies of it under the terms of +the GNU General Public License . +There is NO WARRANTY, to the extent permitted by law. +.br +This manual page was created for Debian by Bas Zoetekouw. It was derived from +the documentation provided by the authors and it may be used, distributed and +modified under the terms of the GNU General Public License, version 2. +.br +On Debian systems, the text of the GNU General Public License can be found in +/usr/share/common\-licenses/GPL\-2. + +.SH "SEE ALSO" +blktrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1) + diff --git a/doc/verify_blkparse.1 b/doc/verify_blkparse.1 new file mode 100644 index 0000000..c209ef8 --- /dev/null +++ b/doc/verify_blkparse.1 @@ -0,0 +1,44 @@ +.TH VERIFY_BLKPARSE 1 "March 6, 2007" "blktrace git\-20070306202522" "" + + +.SH NAME +verify_blkparse \- verifies an output file produced by blkparse + + +.SH SYNOPSIS +.B verify_blkparse <\fIfilename\fR> +.br + + +.SH DESCRIPTION + +Verifies an output file from blkparse. All it does is check if the events in +the file are correctly time ordered. If an entry is found that isn't ordered, +it's dumped to stdout. + + +.SH AUTHORS +\fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This +man page was created from the \fIblktrace\fR documentation by Bas Zoetekouw. + + +.SH "REPORTING BUGS" +Report bugs to + +.SH COPYRIGHT +Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott. +.br +This is free software. You may redistribute copies of it under the terms of +the GNU General Public License . +There is NO WARRANTY, to the extent permitted by law. +.br +This manual page was created for Debian by Bas Zoetekouw. It was derived from +the documentation provided by the authors and it may be used, distributed and +modified under the terms of the GNU General Public License, version 2. +.br +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), blkparse (1), blkrawverify (1), btt (1) + -- 2.25.1