1 \input texinfo @c -*-texinfo-*-
4 @settitle LTTng Userspace Tracer (UST) Manual
8 This manual is for program, version version.
10 Copyright @copyright{} copyright-owner.
13 Permission is granted to ...
18 @title LTTng Userspace Tracer (UST) Manual
19 @c @subtitle subtitle-if-any
20 @c @subtitle second-subtitle
23 @c The following two commands
24 @c start the copyright page.
26 @c @vskip 0pt plus 1filll
32 @c So the toc is printed at the start.
37 @top LTTng Userspace Tracer
39 This manual is for UST 0.1.
46 * Instrumenting an application::
50 @c * Copying:: Your rights and freedoms.
58 * Supported platforms::
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}.
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
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.
76 @node Supported platforms
77 @section Supported platforms
79 UST can currently trace applications running on Linux, on the x86-32 and x86-64 architectures.
84 The LTTng userspace tracer is a library and a set of userspace tools.
86 The following packages are required:
92 This contains the tracing library, the ustd daemon, trace control tools
93 and other helper tools.
95 Repository: http://git.dorsal.polymtl.ca
100 This is a library that contains a userspace port of some kernel APIs.
102 Repository: http://git.dorsal.polymtl.ca
107 This is the userspace read-copy update library by Mathieu Desnoyers.
109 Available in Debian as package liburcu-dev.
111 Home page: http://lttng.org/?q=node/18
116 LTTV is a graphical (and text) viewer for LTTng traces.
118 Home page: http://lttng.org
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.
126 Refer to the README in each of these packages for installation instructions.
134 First, instrument a program with a marker.
139 #include <ust/marker.h>
141 int main(int argc, char **argv)
146 /* ... set values of v and st ... */
149 trace_mark(ust, myevent, "firstarg %d secondarg %s", v, st);
151 /* a marker without arguments: */
152 trace_mark(ust, myotherevent, MARK_NOARGS);
160 Then compile it in the regular way, linking it with libust. For example:
163 gcc -o foo -lust foo.c
166 Run the program with @command{usttrace}. The @command{usttrace} output says where the trace
173 Finally, open the trace in LTTV.
176 lttv-gui -t /path/to/trace
179 The trace can also be dumped as text in the console:
182 lttv -m textDump -t /path/to/trace
185 @node Instrumenting an application
186 @chapter Instrumenting an application
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
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.
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
202 In addition to executable programs, shared libraries may also be instrumented
203 with the methods described in this chapter.
213 Adding a marker is simply a matter of insert one line in the program.
217 #include <ust/marker.h>
219 int main(int argc, char **argv)
224 /* ... set values of v and st ... */
227 trace_mark(main, myevent, "firstarg %d secondarg %s", v, st);
229 /* a marker without arguments: */
230 trace_mark(main, myotherevent, MARK_NOARGS);
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.
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.
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.
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
262 A function instrumented with a tracepoint looks like this:
273 /* ... set values of v and st ... */
276 trace_mychannel_myevent(v, st);
281 Another file, here tp.h, contains declarations for the tracepoint.
285 #include <ust/tracepoint.h>
287 DECLARE_TRACE(mychannel_myevent, TPPROTO(int v, char *st),
292 A third file, here tp.c, contains definitions for the tracepoint.
296 #include <ust/marker.h>
299 DEFINE_TRACE(mychannel_myevent);
301 void mychannel_myevent_probe(int v, char *st)
303 trace_mark(mychannel, myevent, "v %d st %s", v, st);
306 static void __attribute__((constructor)) init()
308 register_trace_mychannel_myevent(mychannel_myevent_probe);
313 Here, tp.h and tp.c could contain declarations and definitions for other
314 tracepoints. The constructor would contain other register_* calls.
316 @node Recording a trace
317 @chapter Recording a trace
320 * Using @command{usttrace}::
321 * Setting up the recording manually::
322 * Using early tracing::
324 * Tracing across @code{fork()} and @code{clone()}::
325 * Tracing programs and libraries that were not linked to libust::
328 @node Using @command{usttrace}
329 @section Using @command{usttrace}
331 The simplest way to record a trace is to use the @command{usttrace} script. An
332 example is given in the quickstart above.
334 The @command{usttrace} script automatically:
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
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.
346 The save location also contains logs of the tracing.
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
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.
357 @node Setting up the recording manually
358 @section Setting up the recording manually
360 Instead of using @command{usttrace}, a trace may be recorded on an already
363 First the daemon must be started.
367 # Make sure the directory for the communication sockets exists.
368 $ mkdir /tmp/ustsocks
370 # Make sure the directory where ustd will write the trace exists.
376 # We assume the program we want to trace is already running and that
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.
384 $ ustctl --enable-marker 1234 ust/mymark
387 $ ustctl --create-trace 1234
390 $ ustctl --start-trace 1234
395 $ ustctl --stop-trace 1234
398 $ ustctl --destroy-trace 1234
402 @node Using early tracing
403 @section Using early tracing
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.
411 When using @command{usttrace}, the early tracing is always active.
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
420 @section Crash recovery
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.
427 @node Tracing across @code{fork()} and @code{clone()}
428 @section Tracing across @code{fork()} and @code{clone()}
430 Tracing across @code{clone()} when @code{CLONE_VM} is specified is supported
431 without any particular action.
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.}
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
443 @node Tracing programs and libraries that were not linked to libust
444 @section Tracing programs and libraries that were not linked to libust
454 @chapter Viewing traces