Commit | Line | Data |
---|---|---|
5cd1099a PMF |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
3 | @setfilename ust.info | |
4 | @settitle LTTng Userspace Tracer (UST) Manual | |
5 | @c %**end of header | |
6 | ||
7 | @copying | |
8 | This manual is for program, version version. | |
9 | ||
10 | Copyright @copyright{} copyright-owner. | |
11 | ||
12 | @quotation | |
13 | Permission is granted to ... | |
14 | @end quotation | |
15 | @end copying | |
16 | ||
17 | @titlepage | |
18 | @title LTTng Userspace Tracer (UST) Manual | |
19 | @c @subtitle subtitle-if-any | |
20 | @c @subtitle second-subtitle | |
21 | @c @author author | |
22 | ||
23 | @c The following two commands | |
24 | @c start the copyright page. | |
25 | @c @page | |
26 | @c @vskip 0pt plus 1filll | |
27 | @c @insertcopying | |
28 | ||
29 | @c Published by ... | |
30 | @end titlepage | |
31 | ||
32 | @c So the toc is printed at the start. | |
33 | @contents | |
34 | ||
35 | @ifnottex | |
36 | @node Top | |
37 | @top LTTng Userspace Tracer | |
38 | ||
39 | This manual is for UST 0.1. | |
40 | @end ifnottex | |
41 | ||
42 | @menu | |
43 | * Overview:: | |
44 | * Installation:: | |
45 | * Quick start:: | |
46 | * Instrumenting an application:: | |
47 | * Recording a trace:: | |
48 | * Viewing traces:: | |
49 | * Performance:: | |
50 | @c * Copying:: Your rights and freedoms. | |
51 | @end menu | |
52 | ||
53 | @node Overview | |
54 | @chapter Overview | |
55 | ||
56 | @menu | |
79f9fac7 | 57 | * License:: |
5cd1099a PMF |
58 | * Supported platforms:: |
59 | @end menu | |
60 | ||
79f9fac7 PMF |
61 | @node License |
62 | @section License | |
63 | The LTTng Userspace Tracer is intended to be linkable to open source software | |
64 | as well as to proprietary applications. This was accomplished by licensing | |
65 | the code that needs to be linked to the traced program as @acronym{LGPL}. | |
66 | ||
67 | The @file{libust} library, including its headers, are licensed as @acronym{GNU} | |
68 | @acronym{LGPL} v2.1. It is also the case of some other helper libraries | |
69 | (@file{libmallocwrap}, @file{libinterfork}, @file{libustcomm}) that need to be linked to the traced | |
70 | program. | |
71 | ||
72 | The accompanying tools of the @acronym{UST} package are licensed as | |
73 | @acronym{GNU} @acronym{GPL} v2. These tools include the @file{ustctl} trace | |
74 | control program and the @file{ustd} daemon. | |
75 | ||
5cd1099a PMF |
76 | @node Supported platforms |
77 | @section Supported platforms | |
78 | ||
79 | UST can currently trace applications running on Linux, on the x86-32 and x86-64 architectures. | |
80 | ||
81 | @node Installation | |
82 | @chapter Installation | |
83 | ||
84 | The LTTng userspace tracer is a library and a set of userspace tools. | |
85 | ||
86 | The following packages are required: | |
87 | ||
88 | @itemize @bullet | |
89 | @item | |
90 | ust | |
91 | ||
92 | This contains the tracing library, the ustd daemon, trace control tools | |
93 | and other helper tools. | |
94 | ||
95 | Repository: http://git.dorsal.polymtl.ca | |
96 | ||
97 | @item | |
98 | libkcompat | |
99 | ||
100 | This is a library that contains a userspace port of some kernel APIs. | |
101 | ||
102 | Repository: http://git.dorsal.polymtl.ca | |
103 | ||
104 | @item | |
105 | liburcu | |
106 | ||
107 | This is the userspace read-copy update library by Mathieu Desnoyers. | |
108 | ||
109 | Available in Debian as package liburcu-dev. | |
110 | ||
111 | Home page: http://lttng.org/?q=node/18 | |
112 | ||
113 | @item | |
114 | LTTV | |
115 | ||
116 | LTTV is a graphical (and text) viewer for LTTng traces. | |
117 | ||
118 | Home page: http://lttng.org | |
119 | ||
120 | @end itemize | |
121 | ||
122 | Libkcompat and liburcu should be installed first. UST may then be compiled | |
123 | and installed. LTTV has no dependency on the other packages; it may therefore | |
124 | be installed on a system which does not have UST installed. | |
125 | ||
126 | Refer to the README in each of these packages for installation instructions. | |
127 | ||
128 | @c @menu | |
129 | @c @end menu | |
130 | ||
131 | @node Quick start | |
132 | @chapter Quick start | |
133 | ||
134 | First, instrument a program with a marker. | |
135 | ||
136 | @example | |
137 | @verbatim | |
138 | ||
139 | #include <ust/marker.h> | |
140 | ||
141 | int main(int argc, char **argv) | |
142 | { | |
143 | int v; | |
144 | char *st; | |
145 | ||
146 | /* ... set values of v and st ... */ | |
147 | ||
148 | /* a marker: */ | |
149 | trace_mark(ust, myevent, "firstarg %d secondarg %s", v, st); | |
150 | ||
151 | /* a marker without arguments: */ | |
152 | trace_mark(ust, myotherevent, MARK_NOARGS); | |
153 | ||
154 | return 0; | |
155 | } | |
156 | ||
157 | @end verbatim | |
158 | @end example | |
159 | ||
160 | Then compile it in the regular way, linking it with libust. For example: | |
161 | ||
162 | @example | |
163 | gcc -o foo -lust foo.c | |
164 | @end example | |
165 | ||
166 | Run the program with @command{usttrace}. The @command{usttrace} output says where the trace | |
167 | was written. | |
168 | ||
169 | @example | |
170 | usttrace ./foo | |
171 | @end example | |
172 | ||
173 | Finally, open the trace in LTTV. | |
174 | ||
175 | @example | |
176 | lttv-gui -t /path/to/trace | |
177 | @end example | |
178 | ||
179 | The trace can also be dumped as text in the console: | |
180 | ||
181 | @example | |
182 | lttv -m textDump -t /path/to/trace | |
183 | @end example | |
184 | ||
185 | @node Instrumenting an application | |
186 | @chapter Instrumenting an application | |
187 | ||
188 | In order to record a trace of events occurring in a application, the | |
189 | application must be instrumented. Instrumentation points resemble function | |
190 | calls. When the program reaches an instrumentation point, an event is | |
191 | generated. | |
192 | ||
193 | There are no limitations on the type of code that may be instrumented. | |
194 | Multi-threaded programs may be instrumented without problem. Signal handlers | |
195 | may be instrumented as well. | |
196 | ||
197 | There are two APIs to instrument programs: markers and tracepoints. Markers are | |
198 | quick to add and are usually used for temporary instrumentation. Tracepoints | |
199 | provide a way to instrument code more cleanly and are suited for permanent | |
200 | instrumentation. | |
201 | ||
202 | In addition to executable programs, shared libraries may also be instrumented | |
203 | with the methods described in this chapter. | |
204 | ||
205 | @menu | |
206 | * Markers:: | |
207 | * Tracepoints:: | |
208 | @end menu | |
209 | ||
210 | @node Markers | |
211 | @section Markers | |
212 | ||
213 | Adding a marker is simply a matter of insert one line in the program. | |
214 | ||
215 | @example | |
216 | @verbatim | |
217 | #include <ust/marker.h> | |
218 | ||
219 | int main(int argc, char **argv) | |
220 | { | |
221 | int v; | |
222 | char *st; | |
223 | ||
224 | /* ... set values of v and st ... */ | |
225 | ||
226 | /* a marker: */ | |
227 | trace_mark(main, myevent, "firstarg %d secondarg %s", v, st); | |
228 | ||
229 | /* a marker without arguments: */ | |
230 | trace_mark(main, myotherevent, MARK_NOARGS); | |
231 | ||
232 | return 0; | |
233 | } | |
234 | @end verbatim | |
235 | @end example | |
236 | ||
237 | The invocation of the trace_mark() macro requires at least 3 arguments. The | |
238 | first, here "main", is the name of the event category. It is also the name of | |
239 | the channel the event will go in. The second, here "myevent" is the name of the | |
240 | event. The third is a format string that announces the names and the types of | |
241 | the event arguments. Its format resembles that of a printf() format string; it | |
242 | is described thoroughly in Appendix x. | |
243 | ||
244 | A given Marker may appear more than once in the same program. Other Markers may | |
245 | have the same name and a different format string, although this might induce | |
246 | some confusion at analysis time. | |
247 | ||
248 | @node Tracepoints | |
249 | @section Tracepoints | |
250 | ||
251 | The Tracepoints API uses the Markers, but provides a higher-level abstraction. | |
252 | Whereas the markers API provides limited type checking, the Tracepoints API | |
253 | provides more thorough type checking and discharges from the need to insert | |
254 | format strings directly in the code and to have format strings appear more than | |
255 | once if a given marker is reused. | |
256 | ||
257 | @quotation Note Although this example uses @emph{mychannel} as the channel, the | |
258 | only channel name currently supported with early tracing is @strong{ust}. The | |
259 | @command{usttrace} tool always uses the early tracing mode. When using manual | |
260 | mode without early tracing, any channel name may be used. @end quotation | |
261 | ||
262 | A function instrumented with a tracepoint looks like this: | |
263 | ||
264 | @example | |
265 | @verbatim | |
266 | #include "tp.h" | |
267 | ||
268 | void function() | |
269 | { | |
270 | int v; | |
271 | char *st; | |
272 | ||
273 | /* ... set values of v and st ... */ | |
274 | ||
275 | /* a tracepoint: */ | |
276 | trace_mychannel_myevent(v, st); | |
277 | } | |
278 | @end verbatim | |
279 | @end example | |
280 | ||
281 | Another file, here tp.h, contains declarations for the tracepoint. | |
282 | ||
283 | @example | |
284 | @verbatim | |
285 | #include <ust/tracepoint.h> | |
286 | ||
287 | DECLARE_TRACE(mychannel_myevent, TPPROTO(int v, char *st), | |
288 | TPARGS(v, st)); | |
289 | @end verbatim | |
290 | @end example | |
291 | ||
292 | A third file, here tp.c, contains definitions for the tracepoint. | |
293 | ||
294 | @example | |
295 | @verbatim | |
296 | #include <ust/marker.h> | |
297 | #include "tp.h" | |
298 | ||
299 | DEFINE_TRACE(mychannel_myevent); | |
300 | ||
301 | void mychannel_myevent_probe(int v, char *st) | |
302 | { | |
303 | trace_mark(mychannel, myevent, "v %d st %s", v, st); | |
304 | } | |
305 | ||
306 | static void __attribute__((constructor)) init() | |
307 | { | |
308 | register_trace_mychannel_myevent(mychannel_myevent_probe); | |
309 | } | |
310 | @end verbatim | |
311 | @end example | |
312 | ||
313 | Here, tp.h and tp.c could contain declarations and definitions for other | |
314 | tracepoints. The constructor would contain other register_* calls. | |
315 | ||
316 | @node Recording a trace | |
317 | @chapter Recording a trace | |
318 | ||
319 | @menu | |
320 | * Using @command{usttrace}:: | |
321 | * Setting up the recording manually:: | |
322 | * Using early tracing:: | |
323 | * Crash recovery:: | |
324 | * Tracing across @code{fork()} and @code{clone()}:: | |
325 | * Tracing programs and libraries that were not linked to libust:: | |
326 | @end menu | |
327 | ||
328 | @node Using @command{usttrace} | |
329 | @section Using @command{usttrace} | |
330 | ||
331 | The simplest way to record a trace is to use the @command{usttrace} script. An | |
332 | example is given in the quickstart above. | |
333 | ||
334 | The @command{usttrace} script automatically: | |
335 | @itemize @bullet | |
336 | @item creates a daemon | |
337 | @item enables all markers | |
338 | @item runs the command specified on the command line | |
339 | @item after the command ends, prints the location where the trace was saved | |
340 | @end itemize | |
341 | ||
342 | Each subdirectory of the save location contains the trace of one process that | |
343 | was generated by the command. The name of a subdirectory consists in the the PID | |
344 | of the process, followed by the timestamp of its creation. | |
345 | ||
346 | The save location also contains logs of the tracing. | |
347 | ||
348 | When using @command{usttrace}, the early tracing is always active, which means | |
349 | that the tracing is guaranteed to be started by the time the process enters its | |
350 | main() function. | |
351 | ||
352 | Several @command{usttrace}'s may be run simultaneously without risk of | |
353 | conflict. This facilitates the use of the tracer by idependent users on a | |
354 | system. Each instance of @command{usttrace} starts its own daemon which | |
355 | collects the events of the processes it creates. | |
356 | ||
357 | @node Setting up the recording manually | |
358 | @section Setting up the recording manually | |
359 | ||
360 | Instead of using @command{usttrace}, a trace may be recorded on an already | |
361 | running process. | |
362 | ||
363 | First the daemon must be started. | |
364 | ||
365 | @example | |
366 | @verbatim | |
367 | # Make sure the directory for the communication sockets exists. | |
368 | $ mkdir /tmp/ustsocks | |
369 | ||
370 | # Make sure the directory where ustd will write the trace exists. | |
371 | $ mkdir /tmp/trace | |
372 | ||
373 | # Start the daemon | |
374 | $ ustd | |
375 | ||
376 | # We assume the program we want to trace is already running and that | |
377 | # it has pid 1234. | |
378 | ||
379 | # List the available markers | |
380 | $ ustctl --list-markers 1234 | |
381 | # A column indicates 0 for an inactive marker and 1 for an active marker. | |
382 | ||
383 | # Enable a marker | |
384 | $ ustctl --enable-marker 1234 ust/mymark | |
385 | ||
386 | # Create a trace | |
387 | $ ustctl --create-trace 1234 | |
388 | ||
389 | # Start tracing | |
390 | $ ustctl --start-trace 1234 | |
391 | ||
392 | # Do things... | |
393 | ||
394 | # Stop tracing | |
395 | $ ustctl --stop-trace 1234 | |
1af1f1db PMF |
396 | |
397 | # Destroy the trace | |
398 | $ ustctl --destroy-trace 1234 | |
5cd1099a PMF |
399 | @end verbatim |
400 | @end example | |
401 | ||
402 | @node Using early tracing | |
403 | @section Using early tracing | |
404 | ||
405 | Early tracing consists in starting the tracing as early as possible in the | |
406 | program, so no events are lost between program start and the point where the | |
407 | command to start the tracing is given. When using early tracing, it is | |
408 | guaranteed that by the time the traced program enters its @code{main()} | |
409 | function, the tracing will be started. | |
410 | ||
411 | When using @command{usttrace}, the early tracing is always active. | |
412 | ||
413 | When using the manual mode (@command{ustctl}), early tracing is enabled using | |
414 | environment variables. Setting @env{UST_TRACE} to @code{1}, enables early | |
415 | tracing, while setting @env{UST_AUTOPROBE} to @code{1} enables all markers | |
416 | automatically. | |
417 | ||
418 | ||
419 | @node Crash recovery | |
420 | @section Crash recovery | |
421 | ||
422 | When a process being traced crashes, the daemon is able to recover all the | |
423 | events in its buffers that were successfully commited. This is possible because | |
424 | the buffers are in a shared memory segment which remains available to the | |
425 | daemon even after the termination of the traced process. | |
426 | ||
427 | @node Tracing across @code{fork()} and @code{clone()} | |
428 | @section Tracing across @code{fork()} and @code{clone()} | |
429 | ||
430 | Tracing across @code{clone()} when @code{CLONE_VM} is specified is supported | |
431 | without any particular action. | |
432 | ||
433 | When @code{clone()} is called without @code{CLONE_VM} or @code{fork()} is | |
434 | called, a new address space is created and the tracer must be notified to | |
435 | create new buffers for it. @strong{TODO: specify how to do it.} | |
436 | ||
437 | This can be done automatically (for @code{fork()} only for now), by | |
438 | @env{LD_PRELOAD}'ing @file{libinterfork.so}. This library intercepts calls to | |
439 | @code{fork()} and informs the tracer it is being called. When using | |
440 | @command{usttrace}, this is accomplied by specifying the @option{-f} command | |
441 | line argument. | |
442 | ||
443 | @node Tracing programs and libraries that were not linked to libust | |
444 | @section Tracing programs and libraries that were not linked to libust | |
445 | ||
446 | Todo. | |
447 | ||
448 | @node Performance | |
449 | @chapter Performance | |
450 | ||
451 | Todo. | |
452 | ||
453 | @node Viewing traces | |
454 | @chapter Viewing traces | |
455 | ||
456 | @bye |