Update test-cases for new ustctl cli
[ust.git] / doc / info / ust.texi
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.11.
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 * Resource Usage::
51 * List of environment variables detected by libust::
52 * GDB integration::
53 @c * Copying:: Your rights and freedoms.
54 @end menu
55
56 @node Overview
57 @chapter Overview
58
59 @menu
60 * What is UST?::
61 * License::
62 * Supported platforms::
63 @end menu
64
65 @node What is UST?
66 @section What is UST?
67
68 The LTTng Userspace Tracer (UST) is a library accompanied by a set of tools to
69 trace userspace code.
70
71 Code may be instrumented with either markers or tracepoints. A highly efficient
72 lockless tracer records these events to a trace buffers. These buffers are reaped
73 by a deamon which writes trace data to disk.
74
75 High performance is achieved by the use of lockless buffering algorithms, RCU and
76 per-cpu buffers. In addition, special care is taken to minize cache impact.
77
78 @node License
79 @section License
80 The LTTng Userspace Tracer is intended to be linkable to open source software
81 as well as to proprietary applications. This was accomplished by licensing
82 the code that needs to be linked to the traced program as @acronym{LGPL}.
83
84 Components licensed as LGPL v2.1:
85 @itemize @bullet
86 @item libust
87 @item libinterfork
88 @item libustcomm
89 @end itemize
90
91 Components licensed as GPL v2:
92 @itemize @bullet
93 @item ustctl
94 @item libustcmd
95 @item ust-consumerd
96 @end itemize
97
98 @node Supported platforms
99 @section Supported platforms
100
101 UST can currently trace applications running on Linux, on the x86-32, x86-64
102 and PowerPC 32 architectures.
103
104 @node Installation
105 @chapter Installation
106
107 The LTTng userspace tracer is a library and a set of userspace tools.
108
109 The following packages are required:
110
111 @itemize @bullet
112 @item
113 ust
114
115 This contains the tracing library, the ust-consumerd daemon, trace control tools
116 and other helper tools.
117
118 Repository: @url{http://git.dorsal.polymtl.ca}
119
120 @item
121 liburcu
122
123 This is the userspace read-copy update library by Mathieu Desnoyers.
124
125 Available in Debian as package liburcu-dev.
126
127 Home page: @url{http://lttng.org/urcu}
128
129 @item
130 LTTV
131
132 LTTV is a graphical (and text) viewer for LTTng traces.
133
134 Home page: @url{http://lttng.org}
135
136 @end itemize
137
138 Liburcu should be installed first. UST may then be compiled and installed. LTTV
139 has no dependency on the other packages; it may therefore be installed on a
140 system which does not have UST installed.
141
142 Refer to the README in each of these packages for installation instructions.
143
144 @c @menu
145 @c @end menu
146
147 @node Quick start
148 @chapter Quick start
149
150 First, instrument a program with a marker.
151
152 @example
153 @verbatim
154
155 #include <ust/marker.h>
156
157 int main(int argc, char **argv)
158 {
159 int v;
160 char *st;
161
162 /* ... set values of v and st ... */
163
164 /* a marker: */
165 trace_mark(ust, myevent, "firstarg %d secondarg %s", v, st);
166
167 /* a marker without arguments: */
168 trace_mark(ust, myotherevent, MARK_NOARGS);
169
170 return 0;
171 }
172
173 @end verbatim
174 @end example
175
176 Then compile it in the regular way, linking it with libust. For example:
177
178 @example
179 gcc -o foo -lust foo.c
180 @end example
181
182 Run the program with @command{usttrace}. The @command{usttrace} output says where the trace
183 was written.
184
185 @example
186 usttrace ./foo
187 @end example
188
189 Finally, open the trace in LTTV.
190
191 @example
192 lttv-gui -t /path/to/trace
193 @end example
194
195 The trace can also be dumped as text in the console:
196
197 @example
198 lttv -m textDump -t /path/to/trace
199 @end example
200
201 @node Instrumenting an application
202 @chapter Instrumenting an application
203
204 In order to record a trace of events occurring in a application, the
205 application must be instrumented. Instrumentation points resemble function
206 calls. When the program reaches an instrumentation point, an event is
207 generated.
208
209 There are no limitations on the type of code that may be instrumented.
210 Multi-threaded programs may be instrumented without problem. Signal handlers
211 may be instrumented as well.
212
213 There are two APIs to instrument programs: markers and tracepoints. Markers are
214 quick to add and are usually used for temporary instrumentation. Tracepoints
215 provide a way to instrument code more cleanly and are suited for permanent
216 instrumentation.
217
218 In addition to executable programs, shared libraries may also be instrumented
219 with the methods described in this chapter.
220
221 @menu
222 * Markers::
223 * Tracepoints::
224 @end menu
225
226 @node Markers
227 @section Markers
228
229 Adding a marker is simply a matter of inserting one line in the program.
230
231 @example
232 @verbatim
233 #include <ust/marker.h>
234
235 int main(int argc, char **argv)
236 {
237 int v;
238 char *st;
239
240 /* ... set values of v and st ... */
241
242 /* a marker: */
243 trace_mark(main, myevent, "firstarg %d secondarg %s", v, st);
244
245 /* another marker without arguments: */
246 trace_mark(main, myotherevent, MARK_NOARGS);
247
248 return 0;
249 }
250 @end verbatim
251 @end example
252
253 The invocation of the trace_mark() macro requires at least 3 arguments. The
254 first, here "main", is the name of the event category. It is also the name of
255 the channel the event will go in. The second, here "myevent" is the name of the
256 event. The third is a format string that announces the names and the types of
257 the event arguments. Its format resembles that of a printf() format string; it
258 is described thoroughly in Appendix x.
259
260 A given Marker may appear more than once in the same program. Other Markers may
261 have the same name and a different format string, although this might induce
262 some confusion at analysis time.
263
264 @node Tracepoints
265 @section Tracepoints
266
267 The Tracepoints API uses the Markers, but provides a higher-level abstraction.
268 Whereas the markers API provides limited type checking, the Tracepoints API
269 provides more thorough type checking and discharges from the need to insert
270 format strings directly in the code and to have format strings appear more than
271 once if a given marker is reused.
272
273 @quotation Note
274 Although this example uses @emph{mychannel} as the channel, the
275 only channel name currently supported with early tracing is @strong{ust}. The
276 @command{usttrace} tool always uses the early tracing mode. When using manual
277 mode without early tracing, any channel name may be used.
278 @end quotation
279
280 A function instrumented with a tracepoint looks like this:
281
282 @example
283 @verbatim
284 #include "tp.h"
285
286 void function()
287 {
288 int v;
289 char *st;
290
291 /* ... set values of v and st ... */
292
293 /* a tracepoint: */
294 trace_mychannel_myevent(v, st);
295 }
296 @end verbatim
297 @end example
298
299 Another file, here tp.h, contains declarations for the tracepoint.
300
301 @example
302 @verbatim
303 #include <ust/tracepoint.h>
304
305 DECLARE_TRACE(mychannel_myevent, TP_PROTO(int v, char *st),
306 TP_ARGS(v, st));
307 @end verbatim
308 @end example
309
310 A third file, here tp.c, contains definitions for the tracepoint.
311
312 @example
313 @verbatim
314 #include <ust/marker.h>
315 #include "tp.h"
316
317 DEFINE_TRACE(mychannel_myevent);
318
319 void mychannel_myevent_probe(int v, char *st)
320 {
321 trace_mark(mychannel, myevent, "v %d st %s", v, st);
322 }
323
324 static void __attribute__((constructor)) init()
325 {
326 register_trace_mychannel_myevent(mychannel_myevent_probe);
327 }
328 @end verbatim
329 @end example
330
331 Here, tp.h and tp.c could contain declarations and definitions for other
332 tracepoints. The constructor would contain other register_* calls.
333
334 @node Recording a trace
335 @chapter Recording a trace
336
337 @menu
338 * Using @command{usttrace}::
339 * Setting up the recording manually::
340 * Using early tracing::
341 * Crash recovery::
342 * Tracing across @code{fork()} and @code{clone()}::
343 * Tracing programs and libraries that were not linked to libust::
344 @end menu
345
346 @node Using @command{usttrace}
347 @section Using @command{usttrace}
348
349 The simplest way to record a trace is to use the @command{usttrace} script. An
350 example is given in the quickstart above.
351
352 The @command{usttrace} script automatically:
353 @itemize @bullet
354 @item creates a daemon
355 @item enables all markers
356 @item runs the command specified on the command line
357 @item after the command ends, prints the location where the trace was saved
358 @end itemize
359
360 Each subdirectory of the save location contains the trace of one process that
361 was generated by the command. The name of a subdirectory consists in the the PID
362 of the process, followed by the timestamp of its creation.
363
364 The save location also contains logs of the tracing.
365
366 When using @command{usttrace}, the early tracing is always active, which means
367 that the tracing is guaranteed to be started by the time the process enters its
368 @code{main()} function.
369
370 Several @command{usttrace}'s may be run simultaneously without risk of
371 conflict. This facilitates the use of the tracer by idependent users on a
372 system. Each instance of @command{usttrace} starts its own daemon which
373 collects the events of the processes it creates.
374
375 @node Setting up the recording manually
376 @section Setting up the recording manually
377
378 Instead of using @command{usttrace}, a trace may be recorded on an already
379 running process.
380
381 First the daemon must be started.
382
383 @example
384 @verbatim
385 # Make sure the directory for the communication sockets exists.
386 $ mkdir /tmp/ustsocks
387
388 # Make sure the directory where ust-consumerd will write the trace exists.
389 $ mkdir /tmp/trace
390
391 # Start the daemon
392 $ ust-consumerd
393
394 # We assume the program we want to trace is already running and that
395 # it has pid 1234.
396
397 # List the available markers
398 $ ustctl --list-markers 1234
399 # A column indicates 0 for an inactive marker and 1 for an active marker.
400
401 # Enable a marker
402 $ ustctl --enable-marker ust/mymark 1234
403
404 # Create a trace
405 $ ustctl --create-trace 1234
406
407 # Start tracing
408 $ ustctl --start-trace 1234
409
410 # Do things...
411
412 # Stop tracing
413 $ ustctl --stop-trace 1234
414
415 # Destroy the trace
416 $ ustctl --destroy-trace 1234
417 @end verbatim
418 @end example
419
420 For more information about the manual mode, see the ustctl(1) man page.
421
422 @node Using early tracing
423 @section Using early tracing
424
425 Early tracing consists in starting the tracing as early as possible in the
426 program, so no events are lost between program start and the point where the
427 command to start the tracing is given. When using early tracing, it is
428 guaranteed that by the time the traced program enters its @code{main()}
429 function, the tracing will be started.
430
431 When using @command{usttrace}, the early tracing is always active.
432
433 When using the manual mode (@command{ustctl}), early tracing is enabled using
434 environment variables. Setting @env{UST_TRACE} to @code{1}, enables early
435 tracing, while setting @env{UST_AUTOPROBE} to @code{1} enables all markers
436 automatically.
437
438
439 @node Crash recovery
440 @section Crash recovery
441
442 When a process being traced crashes, the daemon is able to recover all the
443 events in its buffers that were successfully commited. This is possible because
444 the buffers are in a shared memory segment which remains available to the
445 daemon even after the termination of the traced process.
446
447 @node Tracing across @code{fork()} and @code{clone()}
448 @section Tracing across @code{fork()} and @code{clone()}
449
450 Tracing across @code{clone()} when the @code{CLONE_VM} flag is specified is
451 supported without any particular action.
452
453 When @code{clone()} is called without @code{CLONE_VM} or @code{fork()} is
454 called, a new address space is created and the tracer must be notified to
455 create new buffers for it.
456
457 This can be done automatically, by @env{LD_PRELOAD}'ing @file{libinterfork.so}.
458 This library intercepts calls to @code{fork()} and informs the tracer it is
459 being called. When using @command{usttrace}, this is accomplied by specifying
460 the @option{-f} command line argument.
461
462 Alternatively, the program can call @code{ust_before_fork()} before calling
463 @code{fork()} or @code{clone()} with @code{CLONE_VM}. After the call,
464 @code{ust_after_fork_parent()} must be called in the parent process and
465 @code{ust_after_fork_child()} must be called in the child process.
466
467
468 @node Tracing programs and libraries that were not linked to libust
469 @section Tracing programs and libraries that were not linked to libust
470
471 Some programs need to be traced even though they were not linked to libust
472 either because they were not instrumented or because it was not practical.
473
474 An executable that is not instrumented can still yield interesting traces when
475 at least one of its dynamic libraries is instrumented. It is also possible to
476 trace certain function calls by intercepting them with a specially crafted
477 library that is linked with @env{LD_PRELOAD} at program start.
478
479 In any case, a program that was not linked to libust at compile time must be
480 linked to it at run time with @env{LD_PRELOAD}. This can be accomplished with
481 @command{usttrace}'s @option{-l} option. It can also be done by setting the
482 @env{LD_PRELOAD} environment variable on the command line. For example:
483
484 @example
485 @verbatim
486 # Run ls with usttrace, LD_PRELOAD'ing libust
487 # (assuming one of the libraries used by ls is instrumented).
488 $ usttrace -l ls
489
490 # Run ls, manually adding the LD_PRELOAD.
491 $ LD_PRELOAD=/usr/local/lib/libust.so.0 ls
492 @end verbatim
493 @end example
494
495
496 @node Performance
497 @chapter Performance
498
499 Todo.
500
501 @node Viewing traces
502 @chapter Viewing traces
503
504 Traces may be viewed with LTTV. An example of command for launching LTTV is
505 given in the quickstart.
506
507 @menu
508 * Viewing multiple traces::
509 * Combined kernel-userspace tracing::
510 @end menu
511
512 @node Viewing multiple traces
513 @section Viewing multiple traces
514
515 When tracing multi-process applications or several applications simultaneously,
516 more than one trace will be obtained. LTTV can open and display all these
517 traces simultaneously.
518
519 @node Combined kernel-userspace tracing
520 @section Combined kernel-userspace tracing
521
522 In addition to multiple userspace traces, LTTV can open a kernel trace recorded
523 with the LTTng kernel tracer. This provides events that enable the rendering of
524 the Control Flow View and the Resource View.
525
526 When doing so, it is necessary to use the same time source for the kernel
527 tracer as well as the userspace tracer. Currently, the recommended method is to
528 use the timestamp counter for both. The TSC can however only be used on architectures
529 where it is synchronized across cores.
530
531 @node Resource Usage
532 @chapter Resource Usage
533
534 The purpose of this section is to give an overview of the resource usage of libust. For
535 a developer, knowing this can be important: because libust is linked with applications, it
536 needs to share some resources with it. Some applications may make some assumptions that are in
537 conflict with libust's usage of resources.
538
539 In practice however, libust is designed to be transparent and is compatible
540 with the vast majority of applications. This means no changes are required in
541 the application (or library) being linked to libust.
542
543 Libust is initialized by a constructor, which by definition runs before the
544 @code{main()} function of the application starts. This constructor creates a
545 thread called the @emph{listener thread}. The listener thread initializes a
546 named socket and waits for connections for ust-consumerd or ustctl.
547
548 Libust-specific code may:
549 @itemize @bullet
550 @item use @code{malloc()} and @code{free()}
551 @item map shared memory segment in the process adress space
552 @item intercept some library calls, specifically @code{fork()} and @code{clone()}
553 @item do interprocess communication with the daemon or ustctl
554 @item create and open named sockets
555
556 @end itemize
557
558 It will not:
559 @itemize @bullet
560 @item handle any signal (all signals are blocked in the listener thread)
561 @item change any process-wide setting that could confuse the application
562 @end itemize
563
564 @node List of environment variables detected by libust
565 @appendix List of environment variables detected by libust
566
567 The behavior of tracing can be influenced by setting special environment
568 variables in the environment of the traced application. This section
569 describes these variables.
570
571 @itemize @bullet
572
573 @item
574 @env{UST_TRACE}
575
576 If set to 1, start tracing as soon as the program starts. Tracing is
577 guaranteed to be started by the time the @code{main()} function starts.
578
579 @item
580 @env{UST_AUTOPROBE}
581
582 If set to @code{1}, enable all markers by the time the @code{main()} function starts.
583
584 @item
585 @env{UST_AUTOCOLLECT}
586
587 If set to @code{0}, disable notification of daemon on trace start. Useful for
588 performance tests.
589
590 @item
591 @env{UST_OVERWRITE}
592
593 If set to @code{1}, enable overwriting of buffers on overrun.
594
595 @item
596 @env{UST_SUBBUF_NUM}
597
598 If set, defines the default number of subbuffers per buffer.
599
600 @item
601 @env{UST_SUBBUF_SIZE}
602
603 If set, defines the default size of subbuffers, in bytes.
604
605 @end itemize
606
607 @node GDB integration
608 @appendix GDB integration
609
610 GDB, the GNU Debugger, can use UST markers as GDB tracepoints (note GDB has its
611 own concept of tracepoint). This feature is called GDB Static Tracepoints. When
612 a GDB tracepoint is hit, GDB collects the marker arguments, as well as the
613 state of the registers.
614
615 In UST, support for GDB integration is not compiled in by default because of
616 the cost of saving registers when a marker is hit. To enable it, run the
617 @command{./configure} script with the @code{-DCONFIG_UST_GDB_INTEGRATION} flag
618 in the @env{CFLAGS} environment variable. For example:
619
620 @example
621 @verbatim
622
623 CFLAGS=-DCONFIG_UST_GDB_INTEGRATION ./configure
624
625 @end verbatim
626 @end example
627
628 As of this writing, GDB Static Tracepoints have been submitted
629 (@url{http://sourceware.org/ml/gdb-patches/2010-06/msg00592.html}) to the GDB
630 mailing list.
631
632 GDB integration is currently only supported on x86-32 and x86-64.
633
634 @bye
This page took 0.04281 seconds and 4 git commands to generate.