new ltt-usertrace
[lttv.git] / ltt-usertrace / README
1
2 LTTng usertrace generic package
3
4 Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
5 March 2006
6
7 This package contains all the user space headers and c files necessary to make
8 your application and library trace through an active LTTng tracer. Here is a
9 short quickstart guide of it.
10
11 Here are the currently supported architectures :
12 x86
13 (please add the ltt_* system calls to other architectures as you need them : it
14 will work magically)
15
16 * Compile your kernel with the latest LTTng patch. Make sure the option
17 "Allow tracing from userspace" is _active_!
18 See the QUICKSTART guide at http://ltt.polymtl.ca/ for details about how to
19 setup a working tracer and viewer. See the genevent installation step : it is
20 required for method #2 below.
21
22 * Extract the latest usertrace-generic archive :
23 su
24 cd /usr/src
25 wget http://ltt.polymtl.ca/packages/usertrace-generic-x.x.tar.gz
26 gzip -cd usertrace-generic-x.x.tar.gz | tar xvof -
27
28 * Build the sample programs and install the headers into your system :
29 su
30 cd /usr/src/usertrace-generic
31 make
32 make install
33
34 * There are two ways to trace information from your application :
35
36 1) Easy way, but slow (printf style)
37 See sample-printf.c for code example.
38
39 - Add the following statements to your program source (the define must come
40 _before_ the includes!) :
41
42 #define LTT_TRACE
43 #define LTT_BLOCKING 1
44 #include <ltt/ltt-facility-user_generic.h>
45 #include <ltt/ltt-facility-custom-user_generic.h>
46
47 Note the define of LTT_BLOCKING to 1 : if a trace buffer is full, your
48 application will block. The default of this parameter is 0 (non blocking) :
49 events are lost when trace buffer is full. The choice is up to you.
50
51 - Add something like the following sample line in your code. Note that this is a
52 very standard format string, this is only a suggested presentation.
53
54 trace_user_generic_slow_printf("in: %s at: %s:%d: Counter value is: %u.",
55 __FILE__, __func__, __LINE__, count);
56
57 - Compile your application with at least these parameters to gcc (it is splitted
58 on two lines, joined by a "\") :
59 gcc -D LTT_SHOW_DEBUG -I /usr/src/usertrace-generic -o myapp myapp.c \
60 /usr/src/usertrace-generic/ltt-facility-loader-user_generic.c
61
62 To see what the final result looks like :
63 - Start tracing
64 - Start your application
65 ** You should see the following message when your program starts and the
66 LTT_SHOW_DEBUG is defined :
67 "LTT : ltt-facility-user_generic init in userspace"
68 If you don't then you forgot to compile the facility loader in your
69 application. If you find this output annoying, you can remove the
70 "-D LTT_SHOW_DEBUG" gcc parameter, which will make the facility loader
71 silent.
72 - Stop tracing
73 Then, to see only the user_generic events :
74 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_generic"
75
76 It will show :
77 user_generic.slow_printf: 35885.922829472 (/cpu_0), 15521, 7453, SYSCALL { "in: sample-printf.c at: main:18: Counter value is: 0." }
78 user_generic.slow_printf: 35886.925685289 (/cpu_0), 15521, 7453, SYSCALL { "in: sample-printf.c at: main:18: Counter value is: 1." }
79 ...
80
81
82
83 2) The second way to log events is still easy, yet faster. It requires creating
84 your own XML description of your data structures. It will make it easier to
85 identify your data in the trace. Please read the comments in method 1)
86 explained previously, as they are not repeated here.
87 See sample.c for code example.
88
89 - Go to the usertrace-generic directory
90 su
91 cd /usr/src/usertrace-generic
92
93 - Create your own facility (i.e. user_myfacility.xml).
94 See the ones available in /usr/share/LinuxTraceToolkitViewer/facilities for
95 examples.
96 You facility _must_ be named following this standard : "user_*", where * is
97 whatever you like. If it is not, it will be rejected by the kernel with a
98 Operation not permitted (can be seen with the -D LTT_SHOW_DEBUG compilation
99 parameter).
100
101 user_myfacility.xml:
102
103 <facility name="user_myfacility">
104 <description>Sample facility</description>
105 <event name="myevent">
106 <description>Sample event</description>
107 <field name="file"><string></field>
108 <field name="function"><string></field>
109 <field name="line"><int></field>
110 <field name="firstval"><long></field>
111 <field name="secondval"><pointer></field>
112 </event>
113 </facility>
114
115 - AN IMPORTANT STEP FOLLOWS :
116 *copy* the user_myfacility.xml file in your system :
117 su
118 cp user_myfacility.xml /usr/share/LinuxTraceToolkitViewer/facilities
119
120 - Use genevent to create the c code and headers :
121 su
122 cd /tmp
123 mkdir genevent
124 cd genevent
125 for a in /usr/share/LinuxTraceToolkitViewer/facilities/user_*.xml;
126 do /usr/local/bin/genevent $a;
127 done
128 cd /usr/src/usertrace-generic
129 cp /tmp/genevent/*load* .
130 cd ltt
131 cp /tmp/genevent/ltt-facility-id-user_myfacility.h .
132 cp /tmp/genevent/ltt-facility-user_myfacility.h .
133 cd ..
134 make install
135
136 - Add the following statements to your program source (the define must come
137 _before_ the includes!) :
138
139 #define LTT_TRACE
140 #define LTT_BLOCKING 1
141 #include <ltt/ltt-facility-user_myfacility.h>
142
143 - Add a call following the trace_user_myfacility_myevent function found in
144 /usr/include/ltt/ltt-facility-user_myfacility.h in your program.
145 For instance :
146 trace_user_myfacility_myevent(__FILE__, __func__, __LINE__, 1234, (void*)0xF0F0F0F0);
147
148 - Compile your application with at least these parameters to gcc (it is splitted
149 on two lines, joined by a "\") :
150 gcc -I /usr/src/usertrace-generic -o myapp myapp.c \
151 /usr/src/usertrace-generic/ltt-facility-loader-user_myfacility.c
152
153 To see what the final result looks like :
154 - Start tracing
155 - Start your application
156 - Stop tracing
157 Then, to see only the user_myfacility events :
158 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_myfacility"
159
160 It will show, for example :
161 user_myfacility.myevent: 39507.805584526 (/cpu_1), 15829, 15736, SYSCALL { "myapp.c", "main", 8, 1234, 0xf0f0f0f0 }
162
163
164 * Fun feature : function instrumentation
165
166 Here is how to generate a full trace of you program function calls.
167 See the sample-instrument-fct.c example program.
168
169 - Compile your application with at least these parameters to gcc (it is splitted
170 on two lines, joined by a "\") :
171 gcc -g -finstrument-functions \
172 -lltt-instrument-functions -o myapp myapp.c
173
174 To see what the final result looks like :
175 - Start tracing
176 - Start your application
177 - Stop tracing
178 Then, to see only the function_entry and function_exit events :
179 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_generic & (event.name=function_entry & event.name=function_exit)"
180
181 It will show, for example :
182 user_generic.function_entry: 59329.709939111 (/cpu_0), 19250, 18581, SYSCALL { 0x8048454, 0x80484c2 }
183 user_generic.function_exit: 59329.709944613 (/cpu_0), 19250, 18581, SYSCALL { 0x8048454, 0x80484c2 }
184
185 you can then use (from the binutils package)
186 addr2line -e sample-instrument-fct -i -f 0x8048454
187 Which shows :
188 test_function
189 /usr/src/usertrace-generic/sample-instrument-fct.c:12
190
191 The lookup in LTTV through libbfd has not been implemented yet.
192
193
This page took 0.033221 seconds and 4 git commands to generate.