diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/blkiomon.8 | 11 | ||||
| -rw-r--r-- | doc/blkparse.1 | 22 | ||||
| -rw-r--r-- | doc/blktrace.8 | 87 | ||||
| -rw-r--r-- | doc/blktrace.tex | 5 | ||||
| -rw-r--r-- | doc/btrecord.8 | 2 | ||||
| -rw-r--r-- | doc/btreplay.8 | 7 | ||||
| -rw-r--r-- | doc/btt.1 | 31 | ||||
| -rw-r--r-- | doc/iowatcher.1 | 162 |
8 files changed, 297 insertions, 30 deletions
diff --git a/doc/blkiomon.8 b/doc/blkiomon.8 index dbed0df..34fbba8 100644 --- a/doc/blkiomon.8 +++ b/doc/blkiomon.8 @@ -7,7 +7,7 @@ blkiomon \- monitor block device I/O based o blktrace data .SH SYNOPSIS .B blkiomon \-I \fIinterval\fR [ \-h \fIfile\fR ] [ \-b \fIfile\fR ] -[ \-D \fIfile\fR ] [ \-Q \fIpath_name\fR +[ \-d \fIfile\fR ] [ \-D \fIfile\fR ] [ \-Q \fIpath_name\fR \-q \fImsg_queue_id\fR \-m \fImsg_id\fR ] [ \-V ] .br @@ -17,6 +17,8 @@ blkiomon is a block device I/O monitor. It periodically generates per-device request size and request latency statistics from blktrace data. It provides histograms as well as data that can be used to calculate min, max, average and variance. For this purpose, it consumes D and C traces read from stdin. +Note, that this doesn't work for logical volumes, as high-level drivers +don't see the completion of the events (C). There are options for binary output and human-readable output to files and stdout. Output to a message queue is supported as well. @@ -48,6 +50,13 @@ Human-readable output file. Use '\-' for stdout. Binary output file. Use '\-' for stdout. .RE +\-d \fIfile\fR +.br +\-\-dump-lldd=\fIfile\fR +.RS +Output file for data emitted by low level device driver. +.RE + \-D \fIfile\fR .br \-\-debug=\fIfile\fR diff --git a/doc/blkparse.1 b/doc/blkparse.1 index 11dab65..be9b34b 100644 --- a/doc/blkparse.1 +++ b/doc/blkparse.1 @@ -58,6 +58,26 @@ option. .SH OPTIONS +\-A \fIhex-mask\fR +.br +\-\-set-mask=\fIhex-mask\fR +.RS +Set filter mask to \fIhex-mask\fR, see blktrace (8) for masks +.RE + +\-a \fImask\fR +.br +\-\-act-mask=\fImask\fR +.RS +Add \fImask\fR to current filter, see blktrace (8) for masks +.RE + +\-D \fIdir\fR +.br +\-\-input-directory=\fIdir\fR +.RS +Prepend \fIdir\fR to input file names +.RE \-b \fIbatch\fR .br @@ -510,7 +530,7 @@ device and sector offset. .SH EXAMPLES -To trace the i/o on the device \fI/dev/hda\fB and parse the output to human +To trace the i/o on the device \fI/dev/sda\fB and parse the output to human readable form, use the following command: % blktrace \-d /dev/sda \-o \- | blkparse \-i \- diff --git a/doc/blktrace.8 b/doc/blktrace.8 index 58e8f90..820b03a 100644 --- a/doc/blktrace.8 +++ b/doc/blktrace.8 @@ -6,7 +6,7 @@ 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 ] +.B blktrace \-d \fIdev\fR [ \-r \fIdebugfs_path\fR ] [ \-o \fIoutput\fR ] [ \-w \fItime\fR ] [ \-a \fIaction\fR ] [ \-A \fIaction_mask\fR ] [ \-v ] .br @@ -66,19 +66,10 @@ blktrace may also be run concurrently with blkparse to produce .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. +killed by the user (via a control-C, or sending SIGINT signal to the +process via invocation the kill (1) utility). Also 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 @@ -114,30 +105,62 @@ Adds \fIdev\fR as a device to trace \-I \fIfile\fR .br -\-\-input-devs=\fIfile\fR +\-\-input\-devs=\fIfile\fR .RS Adds the devices found in \fIfile\fR as devices to trace .RE -\-k +\-n \fInum\-sub\fR .br -\-\-kill +\-\-num\-sub\-buffers=\fInum-sub\fR .RS -Kill on-going trace +Specifies number of buffers to use. blktrace defaults to 4 sub buffers. .RE -\-n \fInum\-sub\fR +\-l .br -\-\-num\-sub=\fInum-sub\fR +\-\-listen .RS -Specifies number of buffers to use. blktrace defaults to 4 sub buffers. +Run in network listen mode (blktrace server) +.RE + +\-h \fIhostname\fR +.br +\-\-host=\fIhostname\fR +.RS +Run in network client mode, connecting to the given host +.RE + +\-p \fInumber\fR +.br +\-\-port=\fInumber\fR +.RS +Network port to use (default 8462) +.RE + +\-s +.br +\-\-no\-sendfile +.RS +Make the network client NOT use sendfile() to transfer data +.RE + +\-o \fIbasename\fR +.br +\-\-output=\fIbasename\fR +.RS +Specifies base name for input files. Default is device.blktrace.cpu. +Specifying -o - runs in live mode with blkparse (writing data to standard out). .RE -\-o \fIfile\fR +\-D \fIdir\fR .br -\-\-output=\fIfile\fR +\-\-output\-dir=\fIdir\fR .RS -Prepend \fIfile\fR to output file name(s) +Prepend \fIfile\fR to output file name(s) + +This only works when supplying a single device, or when piping the output +via "-o -" with multiple devices. .RE \-r \fIrel-path\fR @@ -147,9 +170,17 @@ Prepend \fIfile\fR to output file name(s) Specifies debugfs mount point .RE +\-v +.br +\-\-version +.RS +Outputs version +.RE + \-V .br -\-\-version +\-\-version +.RS Outputs version .RE @@ -171,6 +202,8 @@ line options. .br \fIcomplete\fR: completed by driver .br +\fIdiscard\fR: discard / trim traces +.br \fIfs\fR: requests .br \fIissue\fR: issued to driver @@ -188,6 +221,8 @@ line options. \fIwrite\fR: write traces .br \fInotify\fR: trace messages +.br +\fIdrv_data\fR: additional driver specific trace .RE @@ -203,7 +238,7 @@ 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\fR 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 \- diff --git a/doc/blktrace.tex b/doc/blktrace.tex index 54fe451..4d8278e 100644 --- a/doc/blktrace.tex +++ b/doc/blktrace.tex @@ -389,7 +389,10 @@ Short & Long & Description \\ \hline\hline -d \emph{dev} & --dev=\emph{dev} & Adds \emph{dev} as a device to trace \\ \hline -k & --kill & Kill on-going trace \\ \hline -n \emph{num-sub} & --num-sub=\emph{num-sub} & Specifies number of buffers to use \\ \hline --o \emph{file} & --output=\emph{file} & Prepend \emph{file} to output file name(s) \\ \hline +-o \emph{file} & --output=\emph{file} & Prepend \emph{file} to output file name(s) \\ + & & \textbf{This only works when using a single device} \\ + & & \textbf{or when piping the output via \texttt{-o -}} \\ + & & \textbf{with multiple devices.} \\ \hline -r \emph{rel-path} & --relay=\emph{rel-path} & Specifies debugfs mount point \\ \hline -V & --version & Outputs version \\ \hline -w \emph{seconds} & --stopwatch=\emph{seconds} & Sets run time to the number of seconds specified \\ \hline diff --git a/doc/btrecord.8 b/doc/btrecord.8 index c0655ab..dd92396 100644 --- a/doc/btrecord.8 +++ b/doc/btrecord.8 @@ -107,7 +107,7 @@ Show version number and exit. \-m <\fInanoseconds\fR> .br -\-\-input\-base=<\fInanoseconds\fR> +\-\-max\-bunch\-time=<\fInanoseconds\fR> .RS The \fI\-m\fR option requires a single parameter which specifies an amount of time (in nanoseconds) to include in any one bunch of IOs that diff --git a/doc/btreplay.8 b/doc/btreplay.8 index 1efcd0d..118dc10 100644 --- a/doc/btreplay.8 +++ b/doc/btreplay.8 @@ -168,6 +168,13 @@ When specified on the command line, all pre-bunch stall indicators will be ignored. IOs will be replayed without inter-bunch delays. .RE +\-x <\fIfactor\fR> +.br +\-\-acc\-factor=<\fIfactor\fR> +.RS +Specify acceleration factor. Default value is 1 (no acceleration). +.RE + \-v .br \-\-verbose @@ -30,6 +30,8 @@ btt \- analyse block i/o traces produces by blktrace .br [ \-L <\fIfreq\fR> | \-\-periodic\-latencies=<\fIfreq\fR> ] .br +[ \-m <\fIoutput name\fR> | \-\-seeks\-per\-second=<\fIoutput name\fR> ] +.br [ \-M <\fIdev map\fR> | \-\-dev\-maps=<\fIdev map\fR> .br [ \-o <\fIoutput name\fR> | \-\-output\-file=<\fIoutput name\fR> ] @@ -58,7 +60,11 @@ btt \- analyse block i/o traces produces by blktrace .br [ \-V | \-\-version ] .br +[ \-X | \-\-easy\-parse\-avgs ] +.br [ \-z <\fIoutput name\fR> | \-\-q2d\-latencies=<\fIoutput name\fR> ] +.br +[ \-Z | \-\-do\-active ] .SH DESCRIPTION @@ -199,6 +205,15 @@ Q2C and D2C latencies. The frequency specified will regulate how often an average latency is output -- a floating point value expressing seconds. .RE +.B \-m <\fIoutput name\fR> +.br +.B \-\-seeks\-per\-second=<\fIoutput name\fR> +.RS 4 +Trigger btt to output seeks-per-second information. The first column will +contain a time value (seconds), and the second column will indicate the +number of seeks per second at that point. +.RE + .B \-M <\fIdev map\fR> .br .B \-\-dev\-maps=<\fIdev map\fR> @@ -330,6 +345,14 @@ Shows the version of btt. Requests a more verbose output. .RE +.B \-X +.br +.B \-\-easy\-parse\-avgs +.RS 4 +Provide data in an easy-to-parse form and write it to a file +with .avg exentsion +.RE + .B \-z <\fIoutput name\fR> .br .B \-\-q2d\-latencies=<\fIoutput name\fR> @@ -339,6 +362,14 @@ respectively. The supplied argument provides the basis for the output name for each device. .RE +.B \-Z +.br +.B \-\-do\-active +.RS 4 +The \-Z will output files containing data which can be plotted showing +per\-device (and total system) I/O activity. +.RE + .SH AUTHORS \fIbtt\fR was written by Alan D. Brunelle. This man page was created diff --git a/doc/iowatcher.1 b/doc/iowatcher.1 new file mode 100644 index 0000000..3044abf --- /dev/null +++ b/doc/iowatcher.1 @@ -0,0 +1,162 @@ +.TH iowatcher "1" "April 2014" "iowatcher" "User Commands" + +.SH NAME +iowatcher - Create visualizations from blktrace results + +.SH SYNOPSIS +.B iowatcher +\fI[options]\fR [--] \fI[program arguments ...]\fR + +.SH DESCRIPTION +iowatcher graphs the results of a blktrace run. It can graph the result of an existing blktrace, start a new blktrace, or start a new blktrace and a benchmark run. It can then create an image or movie of the IO from a given trace. iowatcher can produce either SVG files or movies in mp4 format (with ffmpeg) or ogg format (with png2theora). + +.SH OPTIONS +.TP +\fB--help\fP +Print a brief usage summary. +.TP +\fB-d, --device\fP \fIdevice\fP +Controls which device you are tracing. You can only trace one device at a time for now. It is sent directly to blktrace, and only needed when you are making a new trace. +.TP +\fB-D, --blktrace-destination\fP \fIdestination\fP +Destination for blktrace. +.TP +\fB-p, --prog\fP +Run a program while blktrace is run. The program and its arguments must be +specified after all other options. Note that this option previously required +the program to be given as a single argument but it now tells \fBiowatcher\fP +to expect extra arguments which it should be run during the trace. +.TP +\fB--\fP +End option parsing. If \fB--prog\fP is specified, everything after \fB--\fP is +the program to be run. This can be useful if the program name could otherwise +be mistaken for an option. +.TP +\fB-K, --keep-movie-svgs\fP +Keep the SVG files generated for movie mode. +.TP +\fB-t, --trace\fP \fIpath\fP +Specify the name of the file or directory in which blktrace output is located. +\fBiowatcher\fP uses a dump from blkparse, so this option tries to guess the +name of the corresponding per-CPU blktrace data files if the dump file doesn't +already exist. To add multiple traces to a given graph, you can specify +\fB--trace\fP more than once. If \fIpath\fP is a directory, \fBiowatcher\fP +will use the name of the directory as the base name of the dump file and all +trace files found inside the directory will be processed. +.TP +\fB-l, --label\fP \fIlabel\fP +Sets a label in the graph for a trace file. The labels are added in the same order as the trace files. +.TP +\fB-m, --movie\fP \fI[style]\fP +Create a movie. The file format depends on the extension used in the \fB-o\fP +\fIfile\fP option. If you specify an .ogv or .ogg extension, the result will +be Ogg Theora video, if png2theora is available. If you use an .mp4 extension, +the result will be an mp4 video if ffmpeg is available. You can use any other +extension, but the end result will be an mp4. The accepted \fIstyle\fP values +are \fBspindle\fP for a circular disc-like effect (default) or \fBrect\fP for a +rectangular graph style. +.TP +\fB-T, --title\fP \fItitle\fP +Set a \fItitle\fP to be placed at the top of the graph. +.TP +\fB-o, --output\fP \fIfile\fP +Output filename for the SVG image or video. The video format used will depend +on the file name extension. See \fB--movie\fP for details. +.TP +\fB-r, --rolling\fP \fIseconds\fP +Control the duration for the rolling average. \fBiowatcher\fP tries to smooth out bumpy graphs by averaging the current second with seconds from the past. Larger numbers here give you flatter graphs. +.TP +\fB-h, --height\fP \fIheight\fP +Set the height of each graph +.TP +\fB-w, --width\fP \fIwidth\fP +Set the width of each graph +.TP +\fB-c, --columns\fP \fIcolumns\fP +Number of columns in graph output +.TP +\fB-x, --xzoom\fP \fImin:max\fP +Limit processed time range to \fImin:max\fP. +.TP +\fB-y, --yzoom\fP \fImin:max\fP +Limit processed sectors to \fImin:max\fP. +.TP +\fB-a, --io-plot-action\fP \fIaction\fP +Plot \fIaction\fP (one of Q, D, or C) in the IO graph. +.TP +\fB-P, --per-process-io\fP +Distinguish between processes in the IO graph. +.TP +\fB-O, --only-graph\fP \fIgraph\fP +Add a single graph to the output (see section \fBGRAPHS\fP for options). By +default all graphs are included. Use \fB-O\fP to generate only the required +graphs. \fB-O\fP may be used more than once. +.TP +\fB-N, --no-graph\fP \fItype\fP +Remove a single graph from the output (see section \fBGRAPHS\fP for options). +This option may be used more than once. +.SH GRAPHS +Values accepted by the \fB-O\fP and \fB-N\fP options are: + + io, tput, latency, queue_depth, iops, cpu-sys, cpu-io, cpu-irq, cpu-user, cpu-soft + +.SH EXAMPLES +Generate graph from the existing trace.dump: +.PP +.RS +# iowatcher -t trace +.RE +.PP +Skip the IO graph: +.PP +.RS +# iowatcher -t trace.dump -o trace.svg -N io +.RE +.PP +Only graph tput and latency: +.PP +.RS +# iowatcher -t trace.dump -o trace.svg -O tput -O latency +.RE +.PP +Generate a graph from two runs, and label them: +.PP +.RS +# iowatcher -t ext4.dump -t xfs.dump -l Ext4 -l XFS -o trace.svg +.RE +.PP +Run a fio benchmark and store the trace in trace.dump, add a title to the top, use /dev/sda for blktrace: +.PP +.RS +# iowatcher -d /dev/sda -t trace.dump -T 'Fio Benchmark' -p fio some_job_file +.RE +.PP +Make a movie from an existing trace: +.PP +.RS +# iowatcher -t trace --movie -o trace.mp4 +.RE + +.SH AUTHORS +iowatcher was created and is maintained by Chris Mason. + +This man page was largely written by Andrew Price based on Chris's original README. + +.SH COPYRIGHT +This program is free software; you can redistribute it and/or modify it under +the terms of the GNU General Public License v2 as published by the Free +Software Foundation. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with +this program; if not, write to the Free Software Foundation, Inc., 51 Franklin +Street, Fifth Floor, Boston, MA 02110-1301 USA + +.SH "SEE ALSO" +.BR blktrace (8), +.BR blkparse (1), +.BR fio (1), +.BR mpstat (1) |