1BTT(1)                                                                  BTT(1)
2
3
4

NAME

6       btt - analyse block i/o traces produces by blktrace
7
8
9

SYNOPSIS

11       btt
12       [ -a               | --seek-absolute ]
13       [ -A               | --all-data ]
14       [ -B <output name> | --dump-blocknos=<output name> ]
15       [ -d <seconds>     | --range-delta=<seconds> ]
16       [ -D <dev;...>     | --devices=<dev;...> ]
17       [ -e <exe,...>     | --exes=<exe,...>  ]
18       [ -h               | --help ]
19       [ -i <input name>  | --input-file=<input name> ]
20       [ -I <output name> | --iostat=<output name> ]
21       [ -l <output name> | --d2c-latencies=<output name> ]
22       [ -L <freq>        | --periodic-latencies=<freq> ]
23       [ -m <output name> | --seeks-per-second=<output name> ]
24       [ -M <dev map>     | --dev-maps=<dev map>
25       [ -o <output name> | --output-file=<output name> ]
26       [ -p <output name> | --per-io-dump=<output name> ]
27       [ -P <output name> | --per-io-trees=<output name> ]
28       [ -q <output name> | --q2c-latencies=<output name> ]
29       [ -Q <output name> | --active-queue-depth=<output name> ]
30       [ -r               | --no-remaps ]
31       [ -s <output name> | --seeks=<output name> ]
32       [ -S <interval>    | --iostat-interval=<interval> ]
33       [ -t <sec>         | --time-start=<sec> ]
34       [ -T <sec>         | --time-end=<sec> ]
35       [ -u <output name> | --unplug-hist=<output name> ]
36       [ -v               | --verbose ]
37       [ -V               | --version ]
38       [ -X               | --easy-parse-avgs ]
39       [ -z <output name> | --q2d-latencies=<output name> ]
40       [ -Z               | --do-active ]
41
42
43

DESCRIPTION

45       btt  is  a  post-processing  tool  for  the block layer IO tracing tool
46       called blktrace(8).  As noted in its documentation, blktrace is a block
47       layer  IO  tracing  mechanism which provides detailed information about
48       request queue operations up to user space.
49
50       btt will take in binary  dump  data  from  blkparse,  and  analyse  the
51       events,  producing  a  series of output from the analysis. It will also
52       build .dat files containing "range  data"  --  showing  things  like  Q
53       activity  (periods of time while Q events are being produced), C activ‐
54       ity (likewise for command completions), and etc.
55
56       Included with  the  distribution  is  a  simple  3D  plotting  utility,
57       bno_plot, which can plot the block numbers btt outputs if the -B option
58       is specified. The display will display each IO generated, with the time
59       (seconds)  along  the X-axis, the block number (start) along the Y-axis
60       and the number of blocks transferred in the IO represented along the Z-
61       axis.
62
63
64

OPTIONS

66       -a
67       --seek-absolute
68           When  specified  on the command line, this directs btt to calculate
69           seek distances based solely upon the ending block  address  of  one
70           IO,  and the start of the next.  By default btt uses the concept of
71           the closeness to either the beginning or end of  the  previous  IO.
72           See the Users Manual for more details about seek distances.
73
74       -A
75       --all-data
76           Normally btt will not print out verbose information concerning per-
77           process and per-device data.  If you desire that  level  of  detail
78           you can specify this option.
79
80       -B <output name>
81       --dump-blocknos=<output name>
82           This  option will output absolute block numbers to three files pre‐
83           fixed by the specified output name:
84
85           prefix_device_r.dat
86                  All read block numbers are  output,  first  column  is  time
87                  (seconds),  second is the block number, and the third column
88                  is the ending block number.
89
90           prefix_device_w.dat
91                  All write block numbers are output,  first  column  is  time
92                  (seconds),  second is the block number, and the third column
93                  is the ending block number.
94
95           prefix_device_c.dat
96                  All block numbers (read and write) are output, first  column
97                  is time (seconds), second is the block number, and the third
98                  column is the ending block number.
99
100       -d <seconds>
101       --range-delta=<seconds>
102           btt outputs a file containing Q  and  C  activity,  the  notion  of
103           active  traces  simply means that there are Q or C traces occurring
104           within a certain period of each other. The default  values  is  0.1
105           seconds;  with this option allowing one to change that granularity.
106           The smaller the value, the more data points provided.
107
108       -D <dev;...>
109       --devices=<dev;...>
110           Normally, btt will produce data for all  devices  detected  in  the
111           traces parsed. With this option, one can reduce the analysis to one
112           or more devices provided in the string passed to this  option.  The
113           device  identifiers  are the major and minor number of each device,
114           and each device identifier is separated by a  colon  (:).  A  valid
115           specifier for devices 8,0 and 8,8 would then be: 8,0:8,8.
116
117       -e <exe,...>
118       --exes=<exe,...>
119           The  -e option supplies the list of executables that will have I/Os
120           analysed.
121
122       -h
123       --help
124           Shows a short summary of possible command line option
125
126       -i <input name>
127       --input-file <input file>
128           Specifies the input file to analyse.  This should be a  trace  file
129           produced by blktrace (8).
130
131       -I <output name>
132       --iostat=<output name>
133           The  -I option directs btt to output iostat-like data to the speci‐
134           fied file.  Refer to the iostat (sysstat) documentation for details
135           on the data columns.
136
137       -l <output name>
138       --d2c-latencies=<output name>
139           The  -l  option  allows  one to output per-IO D2C latencies respec‐
140           tively. The supplied argument provides the  basis  for  the  output
141           name for each device.
142
143       -L <freq>
144       --periodic-latencies=<freq>
145           The -L option allows one to output periodic latency information for
146           both Q2C and D2C latencies. The frequency specified  will  regulate
147           how  often  an  average latency is output -- a floating point value
148           expressing seconds.
149
150       -m <output name>
151       --seeks-per-second=<output name>
152           Trigger btt to output seeks-per-second information. The first  col‐
153           umn  will  contain  a  time  value (seconds), and the second column
154           will indicate the number of seeks per second at that point.
155
156       -M <dev map>
157       --dev-maps=<dev map>
158           The -M option takes in a file  generated  by  the  provided  script
159           (gen_disk_info.py), and allows for better output of device names.
160
161       -o <output name>
162       --output-file=<output name>
163           Specifies the output file name.
164
165       -p <output name>
166       --per-io-dump=<output name>
167           The  -p  option will generate a file that contains a list of all IO
168           "sequences" - showing the parts of each IO (Q, A, I/M, D, & C).
169
170       -P <output name>
171       --per-io-trees=<output name>
172           The -P option will generate a file that contains a list of  all  IO
173           "sequences"  - showing only the Q, D & C operation times. The D & C
174           time values are separated from the Q time values  with  a  vertical
175           bar.
176
177       -q <output name>
178       --q2c-latencies=<output name>
179           The  -q  option  allows  one to output per-IO Q2C latencies respec‐
180           tively. The supplied argument provides the  basis  for  the  output
181           name for each device.
182
183       -Q <output name>
184       --active-queue-depth=<output name>
185           The  -Q  option  allows  one  to output data files showing the time
186           stamp and the depth of active commands (those issued but  not  com‐
187           pleted).
188
189       -r
190       --no-remaps
191           Ignore remap traces; older kernels did not implement the full remap
192           PDU.
193
194       -s <output name>
195       --seeks=<output name>
196           The -s option instructs btt to output seek data, the argument  pro‐
197           vided  is  the basis for file names output. There are two files per
198           device, read seeks and write seeks.
199
200       -S <interval>
201       --iostat-interval=<interval>
202           The -S option specifies the interval to use between data output, it
203           defaults to once per second.
204
205       -t <sec>
206       --time-start=<sec>
207       -T <sec>
208       --time-end=<sec>
209           The  -t/-T  options  allow  one  to set a start and/or end time for
210           analysing - analysing will only be done for traces after -t's argu‐
211           ment  and  before -T's argument. (-t and -T are optional, so if you
212           specify just -t, analysis will occur for all traces after the  time
213           specified. Similarly, if only -T is specified, analysis stops after
214           -T's seconds.)
215
216       -u <output name>
217       --unplug-hist=<output name>
218           This option instructs btt to generate a data file  containing  his‐
219           togram  information  for  unplug  traces  on a per device basis. It
220           shows how many times an unplug was hit with a specified  number  of
221           IOs released. There are 21 output values into the file, as follows:
222
223               a value of 0 represents 0..4 counts
224               a value of 1 represents 5..9 counts
225               a value of 2 represents 10..14 counts
226               etc, until
227               a value of 20 represents 100+ counts
228
229           The  file  name(s) generated use the text string passed as an argu‐
230           ment  for  the  prefix,  followed  by  the  device  identifier   in
231           major,minor  form,  with  a  .dat  extension.  For example, with -u
232           up_hist specified on the command line: up_hist_008,032.dat.
233
234       -V
235       --version
236           Shows the version of btt.
237
238       -v
239       --verbose
240           Requests a more verbose output.
241
242       -X
243       --easy-parse-avgs
244           Provide data in an easy-to-parse form and write it to a  file  with
245           .avg exentsion
246
247       -z <output name>
248       --q2d-latencies=<output name>
249           The  -z  option  allows  one to output per-IO Q2D latencies respec‐
250           tively. The supplied argument provides the  basis  for  the  output
251           name for each device.
252
253       -Z
254       --do-active
255           The -Z will output files containing data which can be plotted show‐
256           ing per-device (and total system) I/O activity.
257
258
259

AUTHORS

261       btt was written by Alan D. Brunelle.  This man page  was  created  from
262       the blktrace documentation by Bas Zoetekouw.
263
264
265

REPORTING BUGS

267       Report bugs to <linux-btrace@vger.kernel.org>
268
269
271       Copyright © 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
272       This  is  free  software.   You may redistribute copies of it under the
273       terms      of      the      GNU      General       Public       License
274       <http://www.gnu.org/licenses/gpl.html>.   There  is NO WARRANTY, to the
275       extent permitted by law.
276       This manual page was created for  Debian  by  Bas  Zoetekouw.   It  was
277       derived  from  the  documentation provided by the authors and it may be
278       used, distributed and modified under the terms of the GNU General  Pub‐
279       lic License, version 2.
280       On  Debian  systems,  the text of the GNU General Public License can be
281       found in /usr/share/common-licenses/GPL-2.
282
283

SEE ALSO

285       The  btt  Users  Guide,  which  can  be  found  in  /usr/share/doc/blk‐
286       trace/btt.pdf
287       bno_plot   (1),   blktrace  (8),  blkparse  (1),  verify_blkparse  (1),
288       blkrawverify (1), btt (1)
289
290
291
292
293blktrace git-20070910192508   September 29, 2007                        BTT(1)
Impressum