path: root/lket-b2a.1.in

.\" -*- 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.
.TP
.B \-n     
name_flag. name_flag set to 0 means not printing the event
description string and 1 means printing. Only valid with \-f
option. name_flag is set to 1 by default.
.TP
.B \-i     
id_flag. id_flag set to 0 means not printing event groupid and
hookid and 1 means printing. Only valid with \-f option. id_flag
is set to 0 by default.
.TP
.B \-a     
appname_flag. appname_flag set to 0 means not printing process
name and 1 means printing. Only valid with \-f option. appname_flag
is set to 1 by default.

.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:   1596405 (cycles per microsecond)
[...]
2.527880 CPU:0 PID:2450 APPNAME:gnome\-panel EVT_NAME:iosyscall.read.entry fd:3,buff_addr:\-1081126904,count:32,
2.527887 CPU:0 PID:2450 APPNAME:gnome\-panel EVT_NAME:iosyscall.read.return return:32,
2.534343 CPU:0 PID:1450 APPNAME:kjournald EVT_NAME:scsi.ioentry major:8,minor:0,sdev_state:2,request_addr:3806880208,
2.534359 CPU:0 PID:1450 APPNAME:kjournald EVT_NAME:scsi.iodispatching host:0,channel:0,lun:0,dev_id:0,dev_state:2,data_dir:1,reqbuf_addr:3248315840,reqbuf_len:8192,request_addr:3806880208,
[...]
.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)