Merge branch 'master' of ssh://git.kernel.dk/data/git/blktrace

[blktrace.git] / btt / README

blktrace Timeline
-----------------

Alan D. Brunelle (initial version)

Usage
-----

Usage: btt
	[ -d <seconds>     | --range-delta=<seconds> ]
	[ -D <dev;...>     | --devices=<dev;...> ]
	[ -e <exe,...>     | --exes=<exe,...>  ]
	[ -h               | --help ]
	[ -i <input name>  | --input-file=<input name> ]
	[ -I <output name> | --iostat=<output name> ]
	[ -l <output name> | --d2c-latencies=<output name> ]
	[ -M <dev map>     | --dev-maps=<dev map>
	[ -o <output name> | --output-file=<output name> ]
	[ -p <output name> | --per-io-dump=<output name> ]
	[ -q <output name> | --q2c-latencies=<output name> ]
	[ -s <output name> | --seeks=<output name> ]
	[ -S <interval>    | --iostat-interval=<interval> ]
	[ -t <sec>         | --time-start=<sec> ]
	[ -T <sec>         | --time-end=<sec> ]
	[ -V               | --version ]
	[ -v               | --verbose ]

You are required to specify an input file (-i)

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 occuring to
signify inactivity. The larger the number, the fewer ranges output --
the default is 0.1 seconds.

The -D option supplies the devices which should be looked at when
analyzing 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).

The -e option supplies the list of executables that will have I/Os
analyzed.

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. The -S option specifies the interval to use between data
output, it defaults to once per second.

The -l and -q options allow one to output per-IO D2C and Q2C latencies
respectively. The supplied argument provides the basis for the output
name for each device.

The -M option takes in a file generated by the provided script
(gen_disk_info.py), and allows for better output of device names.

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).

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.

The -t/-T options allow one to set a start and/or end time for analyzing
- analyzing 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.)

Overview
--------

btt will take in binary dump data from blkparse, and analyze 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.

Resources
---------

vger hosts a mailing list dedicated to btrace discussion and development.
The list is called linux-btrace@vger.kernel.org, subscribe by sending
a mail to majordomo@vger.kernel.org with 'subscribe linux-btrace' in
the mail body.

2006-09_18, Alan D. Brunelle <alan.brunelle@hp.com>