diff options
Diffstat (limited to 'lket-b2a.1.in')
| -rw-r--r-- | lket-b2a.1.in | 257 |
1 files changed, 257 insertions, 0 deletions
diff --git a/lket-b2a.1.in b/lket-b2a.1.in new file mode 100644 index 00000000..753d8348 --- /dev/null +++ b/lket-b2a.1.in @@ -0,0 +1,257 @@ +.\" -*- nroff -*- +.TH LKET-B2A 1 @DATE@ "IBM" +.SH NAME +lket-b2a \- Converting and dumping utility for LKET binary trace data + +.\" macros +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH SYNOPSIS + +.br +.B lket-b2a +.I OPTIONS +.IR IN_FILENAME ... +.br + +.SH DESCRIPTION + +The trace data generated by +.I LKET +is in binary format by default for +better performance and smaller size. +.I lket-b2a +is used to convert the +binary trace data into readable data in ascii format and save +them into local file or MySQL database for off-line trace analysis. +It uses the per-cpu binary trace data files (stpd_cpu*) as inputs. +You can use "stap -bM" with LKET to get those per-cpu files before using it. + +The database used by +.I lket-b2a +is MySQL. So MySQL must be properly installed +and configured in order to make +.I lket-b2a +able to dump the trace data into MySQL database. + +.SH OPTIONS +.I lket-b2a +supports the following two options. They can be used +together or alone but at least one of them should be specified: + +.TP +.B \-m +convert and dump trace data into MySQL database. For more details, +See the following section. +.TP +.B \-f +convert and dump trace data into local file. For more details, +See the following section. + +.SH DUMP TRACE DATA INTO LOCAL FILE + +The generated output file is named +.IR lket.out . +The following is an example: + +.SAMPLE +root:/home/root/data> lket-b2a -f stpd_cpu* +root:/home/root/data> cat lket.out +LKET Magic: 0xAEFCDB6B +InitHdrLen: 9 +Version Major: 1 +Version Minor: 1 +Big endian: YES +Timing method: do_gettimeofday() +Bits width: 64 +Initial CPU timebase: 187994 (cycles per microsecond) + +0.2084 APPNAME: (null) PID:20922 CPU:3 HOOKGRP:3 HOOKID:1 tid:20936,pid:20936,ppid:35,pname:systemtap/0, +0.2086 APPNAME: (null) PID:20922 CPU:3 HOOKGRP:3 HOOKID:1 tid:20937,pid:20937,ppid:35,pname:systemtap/1, +0.2087 APPNAME: (null) PID:20922 CPU:3 HOOKGRP:3 HOOKID:1 tid:20938,pid:20938,ppid:35,pname:systemtap/2, +[...] +10.24319 APPNAME: sshd PID:7203 CPU:3 HOOKGRP:2 HOOKID:2 syscall:write, +10.24324 APPNAME: sshd PID:7203 CPU:3 HOOKGRP:2 HOOKID:1 syscall:compat_sys_select, +[...] +.ESAMPLE + +.SH DUMP TRACE DATA INTO MYSQL DATABASE + +To avoid either reading the complete trace data into internal data +structures to process, or filter through the raw trace data again +and again to calculate the interesting metrics, +.I lket-b2a +supports convert and save the binary trace data into MySQL database to +facilitate the query and calculation on the trace data. + +.I lket-b2a +creates the database name based on current time. And +.I lket-b2a +will not only save the trace data, but also some meta data into MySQL +database too, such as trace header, trace table description. + +The following is an example of navigating the trace data in MySQL database +created by +.IR lket-b2a : + +Use +.I lket-b2a +to convert and dump the binary trace data of +.I LKET +into MySQL database: + +.SAMPLE +root:/home/root/data> lket-b2a -m stpd_cpu* +.ESAMPLE + +list all databases in MySQL: + +.SAMPLE +mysql> show databases; ++------------------+ +| Database | ++------------------+ +| DB20061023161626 | +| mysql | +| test | ++------------------+ +3 rows in set (0.00 sec) +.ESAMPLE + +DB20061023161626 is the newly created database by "lket-b2a -m stpd_cpu*". We can list +all the tables contained in DB20061023161626: + +.SAMPLE +mysql> use DB20061023161626 +Database changed +mysql> show tables; ++----------------------------+ +| Tables_in_DB20061023161626 | ++----------------------------+ +| 2_1 | +| 2_2 | +| 3_1 | +| 3_3 | +| 3_5 | +| 4_1 | +| 4_3 | +| 4_4 | +| 8_1 | +| 8_3 | +| appNameMap | +| table_desc | +| trace_header | ++----------------------------+ +13 rows in set (0.00 sec) +.ESAMPLE + +The table trace_header is used to store the trace header info: + +.SAMPLE +mysql> select * from trace_header; ++-----------+-----------+------------+-----------------+------------+ +| Major_Ver | Minor_Ver | Big_Endian | Timing_Method | Bits_Width | ++-----------+-----------+------------+-----------------+------------+ +| 1 | 1 | 2 | do_gettimeofday | 64 | ++-----------+-----------+------------+-----------------+------------+ +1 row in set (0.00 sec) +.ESAMPLE + +The table appNameMap is used to store the mapping between PID and process name: + +.SAMPLE +mysql> select * from appNameMap; ++-------+-----------------+ +| pid | pname | ++-------+-----------------+ +| 10764 | systemtap/0 | +| 10765 | systemtap/1 | +| 10766 | systemtap/2 | +| 10767 | systemtap/3 | +| 10768 | systemtap/4 | +| 10769 | systemtap/5 | +| 10770 | systemtap/6 | +| 10771 | systemtap/7 | +| 0 | swapper | +| 1 | init | +| 2 | migration/0 | +| 3 | ksoftirqd/0 | +| 4 | watchdog/0 | +| 5 | migration/1 | +[...] +.ESAMPLE + +Each event corresponds to one table which is named as groupid_hookid. For example +table 8_1 corresponds to +.I addevent.netdev.receive +whose groupid is 8 and hookid is 1: + +.SAMPLE +mysql> select * from table_desc; ++------------+----------------------------------+ +| table_name | table_desc | ++------------+----------------------------------+ +| 2_1 | addevent.syscall.entry | +| 2_2 | addevent.syscall.return | +| 3_1 | process_snapshot | +| 3_3 | addevent.process.execve | +| 3_5 | addevent.process.fork | +| 4_3 | addevent.ioscheduler.elv_next_re | +| 4_4 | addevent.ioscheduler.elv_next_re | +| 4_1 | addevent.ioscheduler.elv_add_req | +| 8_1 | addevent.netdev.receive | +| 8_3 | addevent.netdev.transmit | ++------------+----------------------------------+ +10 rows in set (0.00 sec) +.ESAMPLE + +The hookid of a return type event( +.I addevent.*.return +) should be an +even number and its value should be the corresponding entry event hookid +1. +For example, the hookid of addevent.syscall.return is 2 and the hookid of +addevent.syscall.entry is 1. And what's more, there will be a new column +named +.I entry_usec +for all return type event tables which is the timestamp +of the entry of that event. The column +.I entry_usec +is created and calculated by lket-b2a on the fly while processing the binary trace data. + +.SAMPLE +mysql> select * from 2_1 limit 4; ++---------+--------+--------+------------+--------+--------------+ +| groupid | hookid | usec | process_id | cpu_id | syscall | ++---------+--------+--------+------------+--------+--------------+ +| 2 | 1 | 10727 | 20922 | 2 | read | +| 2 | 1 | 10746 | 20922 | 2 | read | +| 2 | 1 | 729066 | 3605 | 5 | gettimeofday | +| 2 | 1 | 729086 | 3605 | 5 | gettimeofday | ++---------+--------+--------+------------+--------+--------------+ +4 rows in set (0.00 sec) + +mysql> select * from 2_2 limit 4; ++---------+--------+--------+------------+--------+------------+--------------+ +| groupid | hookid | usec | process_id | cpu_id | entry_usec | syscall | ++---------+--------+--------+------------+--------+------------+--------------+ +| 2 | 2 | 10742 | 20922 | 2 | 10727 | read | +| 2 | 2 | 729072 | 3605 | 5 | 729066 | gettimeofday | +| 2 | 2 | 729089 | 3605 | 5 | 729086 | gettimeofday | +| 2 | 2 | 729100 | 3605 | 5 | 729096 | poll | ++---------+--------+--------+------------+--------+------------+--------------+ +4 rows in set (0.00 sec) +.ESAMPLE + +.SH SEE ALSO +.IR stap (1), +.IR lket (5) |