README
1Block IO Tracing
2----------------
3
4Written by Jens Axboe <axboe@kernel.dk> (initial version and kernel support),
5Alan D. Brunelle (threading and splitup into two seperate programs),
6Nathan Scott <nathans@sgi.com> (bug fixes, process names, multiple devices)
7Also thanks to Tom Zanussi <zanussi@us.ibm.com> for good input and
8patches.
9
10
11Requirements
12------------
13
14blktrace was integrated into the mainline kernel between 2.6.16 and 2.6.17-rc1.
15The target trace needs to run on a kernel at least that new.
16
17git://git.kernel.dk/blktrace.git
18
19If you don't have git, you can get hourly snapshots from:
20
21http://brick.kernel.dk/snaps/
22
23The snapshots include the full git object database as well. kernel.org has
24excessively long mirror times, so if you have git installed, you can pull
25the master tree from:
26
27git://git.kernel.dk/blktrace.git
28
29For browsing the repo over http and viewing history etc, you can direct
30your browser to:
31
32http://git.kernel.dk/
33
34
35Usage
36-----
37
38$ blktrace -d <dev> [ -r debug_path ] [ -o output ] [ -k ] [ -w time ]
39 [ -a action ] [ -A action mask ]
40
41 -d Use specified device. May also be given last after options.
42 -r Path to mounted debugfs, defaults to /sys/kernel/debug.
43 -o File(s) to send output to.
44 -D Directory to prepend to output file names.
45 -k Kill running trace.
46 -w Stop after defined time, in seconds.
47 -a Only trace specific actions (use more -a options to add actions).
48 Available actions are:
49
50 READ
51 WRITE
52 BARRIER
53 SYNC
54 QUEUE
55 REQUEUE
56 ISSUE
57 COMPLETE
58 FS
59 PC
60
61 -A Give the trace mask directly as a number.
62
63 -b Sub buffer size in KiB.
64 -n Number of sub buffers.
65 -l Run in network listen mode (blktrace server)
66 -h Run in network client mode, connecting to the given host
67 -p Network port to use (default 8462)
68 -s Disable network client use of sendfile() to transfer data
69 -V Print program version info.
70
71$ blkparse -i <input> [ -o <output> ] [ -b rb_batch ] [ -s ] [ -t ] [ -q ]
72 [ -w start:stop ] [ -f output format ] [ -F format spec ]
73 [ -d <binary> ]
74
75 -i Input file containing trace data, or '-' for stdin.
76 -D Directory to prepend to input file names.
77 -o Output file. If not given, output is stdout.
78 -b stdin read batching.
79 -s Show per-program io statistics.
80 -h Hash processes by name, not pid.
81 -t Track individual ios. Will tell you the time a request took to
82 get queued, to get dispatched, and to get completed.
83 -q Quiet. Don't display any stats at the end of the trace.
84 -w Only parse data between the given time interval in seconds. If
85 'start' isn't given, blkparse defaults the start time to 0.
86 -d Dump sorted data in binary format
87 -f Output format. Customize the output format. The format field
88 identifiers are:
89
90 %a - Action
91 %c - CPU ID
92 %C - Task command (process) name
93 %d - Direction (r/w)
94 %D - Device number
95 %e - Error number
96 %M - Major
97 %m - Minor
98 %N - Number of bytes
99 %n - Number of sectors
100 %p - PID
101 %P - PDU
102 %s - Sequence number
103 %S - Sector number
104 %t - Time (wallclock - nanoseconds)
105 %T - Time (wallclock - seconds)
106 %u - Time (processing - microseconds)
107 %U - Unplug depth
108
109 -F Format specification. The individual specifiers are:
110
111 A - Remap
112 B - Bounce
113 C - Complete
114 D - Issue
115 M - Back merge
116 F - Front merge
117 G - Get request
118 I - Insert
119 P - Plug
120 Q - Queue
121 R - Requeue
122 S - Sleep requests
123 T - Unplug timer
124 U - Unplug IO
125 W - Bounce
126 X - Split
127
128 -v More verbose for marginal errors.
129 -V Print program version info.
130
131$ verify_blkparse filename
132
133 Verifies an output file from blkparse. All it does is check if
134 the events in the file are correctly time ordered. If an entry
135 is found that isn't ordered, it's dumped to stdout.
136
137$ blkrawverify <dev> [<dev>...]
138
139 The blkrawverify utility can be used to verify data retrieved
140 via blktrace. It will check for valid event formats, forward
141 progressing sequence numbers and time stamps, also does reasonable
142 checks for other potential issues within invidividual events.
143
144 Errors found will be tracked in <dev>.verify.out.
145
146If you want to do live tracing, you can pipe the data between blktrace
147and blkparse:
148
149% blktrace -d <device> -o - | blkparse -i -
150
151This has a small risk of displaying some traces a little out of sync, since
152it will do batch sorts of input events. Similarly, you can do traces over
153the network. The network 'server' must run:
154
155% blktrace -l
156
157to listen to incoming blktrace connections, while the client should use
158
159% blktrace -d /dev/sda -h <server hostname>
160
161to connect and transfer data over the network.
162
163
164Documentation
165-------------
166
167A users guide is distributed with the source. It is in latex, a
168'make docs' will build a PDF in doc/. You need tetex and latex installed
169to build the document.
170
171
172Resources
173---------
174
175vger hosts a mailing list dedicated to btrace discussion and development.
176The list is called linux-btrace@vger.kernel.org, subscribe by sending
177a mail to majordomo@vger.kernel.org with 'subscribe linux-btrace' in
178the mail body.
179
180
181
1822006-09-05, Jens Axboe <axboe@kernel.dk>
183
184