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.
57 * Supported platforms::
60 @node Supported platforms
61 @section Supported platforms
63 UST can currently trace applications running on Linux, on the x86-32 and x86-64 architectures.
68 The LTTng userspace tracer is a library and a set of userspace tools.
70 The following packages are required:
76 This contains the tracing library, the ustd daemon, trace control tools
77 and other helper tools.
79 Repository: http://git.dorsal.polymtl.ca
84 This is a library that contains a userspace port of some kernel APIs.
86 Repository: http://git.dorsal.polymtl.ca
91 This is the userspace read-copy update library by Mathieu Desnoyers.
93 Available in Debian as package liburcu-dev.
95 Home page: http://lttng.org/?q=node/18
100 LTTV is a graphical (and text) viewer for LTTng traces.
102 Home page: http://lttng.org
106 Libkcompat and liburcu should be installed first. UST may then be compiled
107 and installed. LTTV has no dependency on the other packages; it may therefore
108 be installed on a system which does not have UST installed.
110 Refer to the README in each of these packages for installation instructions.
118 First, instrument a program with a marker.
123 #include <ust/marker.h>
125 int main(int argc, char **argv)
130 /* ... set values of v and st ... */
133 trace_mark(ust, myevent, "firstarg %d secondarg %s", v, st);
135 /* a marker without arguments: */
136 trace_mark(ust, myotherevent, MARK_NOARGS);
144 Then compile it in the regular way, linking it with libust. For example:
147 gcc -o foo -lust foo.c
150 Run the program with @command{usttrace}. The @command{usttrace} output says where the trace
157 Finally, open the trace in LTTV.
160 lttv-gui -t /path/to/trace
163 The trace can also be dumped as text in the console:
166 lttv -m textDump -t /path/to/trace
169 @node Instrumenting an application
170 @chapter Instrumenting an application
172 In order to record a trace of events occurring in a application, the
173 application must be instrumented. Instrumentation points resemble function
174 calls. When the program reaches an instrumentation point, an event is
177 There are no limitations on the type of code that may be instrumented.
178 Multi-threaded programs may be instrumented without problem. Signal handlers
179 may be instrumented as well.
181 There are two APIs to instrument programs: markers and tracepoints. Markers are
182 quick to add and are usually used for temporary instrumentation. Tracepoints
183 provide a way to instrument code more cleanly and are suited for permanent
186 In addition to executable programs, shared libraries may also be instrumented
187 with the methods described in this chapter.
197 Adding a marker is simply a matter of insert one line in the program.
201 #include <ust/marker.h>
203 int main(int argc, char **argv)
208 /* ... set values of v and st ... */
211 trace_mark(main, myevent, "firstarg %d secondarg %s", v, st);
213 /* a marker without arguments: */
214 trace_mark(main, myotherevent, MARK_NOARGS);
221 The invocation of the trace_mark() macro requires at least 3 arguments. The
222 first, here "main", is the name of the event category. It is also the name of
223 the channel the event will go in. The second, here "myevent" is the name of the
224 event. The third is a format string that announces the names and the types of
225 the event arguments. Its format resembles that of a printf() format string; it
226 is described thoroughly in Appendix x.
228 A given Marker may appear more than once in the same program. Other Markers may
229 have the same name and a different format string, although this might induce
230 some confusion at analysis time.
235 The Tracepoints API uses the Markers, but provides a higher-level abstraction.
236 Whereas the markers API provides limited type checking, the Tracepoints API
237 provides more thorough type checking and discharges from the need to insert
238 format strings directly in the code and to have format strings appear more than
239 once if a given marker is reused.
241 @quotation Note Although this example uses @emph{mychannel} as the channel, the
242 only channel name currently supported with early tracing is @strong{ust}. The
243 @command{usttrace} tool always uses the early tracing mode. When using manual
244 mode without early tracing, any channel name may be used. @end quotation
246 A function instrumented with a tracepoint looks like this:
257 /* ... set values of v and st ... */
260 trace_mychannel_myevent(v, st);
265 Another file, here tp.h, contains declarations for the tracepoint.
269 #include <ust/tracepoint.h>
271 DECLARE_TRACE(mychannel_myevent, TPPROTO(int v, char *st),
276 A third file, here tp.c, contains definitions for the tracepoint.
280 #include <ust/marker.h>
283 DEFINE_TRACE(mychannel_myevent);
285 void mychannel_myevent_probe(int v, char *st)
287 trace_mark(mychannel, myevent, "v %d st %s", v, st);
290 static void __attribute__((constructor)) init()
292 register_trace_mychannel_myevent(mychannel_myevent_probe);
297 Here, tp.h and tp.c could contain declarations and definitions for other
298 tracepoints. The constructor would contain other register_* calls.
300 @node Recording a trace
301 @chapter Recording a trace
304 * Using @command{usttrace}::
305 * Setting up the recording manually::
306 * Using early tracing::
308 * Tracing across @code{fork()} and @code{clone()}::
309 * Tracing programs and libraries that were not linked to libust::
312 @node Using @command{usttrace}
313 @section Using @command{usttrace}
315 The simplest way to record a trace is to use the @command{usttrace} script. An
316 example is given in the quickstart above.
318 The @command{usttrace} script automatically:
320 @item creates a daemon
321 @item enables all markers
322 @item runs the command specified on the command line
323 @item after the command ends, prints the location where the trace was saved
326 Each subdirectory of the save location contains the trace of one process that
327 was generated by the command. The name of a subdirectory consists in the the PID
328 of the process, followed by the timestamp of its creation.
330 The save location also contains logs of the tracing.
332 When using @command{usttrace}, the early tracing is always active, which means
333 that the tracing is guaranteed to be started by the time the process enters its
336 Several @command{usttrace}'s may be run simultaneously without risk of
337 conflict. This facilitates the use of the tracer by idependent users on a
338 system. Each instance of @command{usttrace} starts its own daemon which
339 collects the events of the processes it creates.
341 @node Setting up the recording manually
342 @section Setting up the recording manually
344 Instead of using @command{usttrace}, a trace may be recorded on an already
347 First the daemon must be started.
351 # Make sure the directory for the communication sockets exists.
352 $ mkdir /tmp/ustsocks
354 # Make sure the directory where ustd will write the trace exists.
360 # We assume the program we want to trace is already running and that
363 # List the available markers
364 $ ustctl --list-markers 1234
365 # A column indicates 0 for an inactive marker and 1 for an active marker.
368 $ ustctl --enable-marker 1234 ust/mymark
371 $ ustctl --create-trace 1234
374 $ ustctl --start-trace 1234
379 $ ustctl --stop-trace 1234
382 $ ustctl --destroy-trace 1234
386 @node Using early tracing
387 @section Using early tracing
389 Early tracing consists in starting the tracing as early as possible in the
390 program, so no events are lost between program start and the point where the
391 command to start the tracing is given. When using early tracing, it is
392 guaranteed that by the time the traced program enters its @code{main()}
393 function, the tracing will be started.
395 When using @command{usttrace}, the early tracing is always active.
397 When using the manual mode (@command{ustctl}), early tracing is enabled using
398 environment variables. Setting @env{UST_TRACE} to @code{1}, enables early
399 tracing, while setting @env{UST_AUTOPROBE} to @code{1} enables all markers
404 @section Crash recovery
406 When a process being traced crashes, the daemon is able to recover all the
407 events in its buffers that were successfully commited. This is possible because
408 the buffers are in a shared memory segment which remains available to the
409 daemon even after the termination of the traced process.
411 @node Tracing across @code{fork()} and @code{clone()}
412 @section Tracing across @code{fork()} and @code{clone()}
414 Tracing across @code{clone()} when @code{CLONE_VM} is specified is supported
415 without any particular action.
417 When @code{clone()} is called without @code{CLONE_VM} or @code{fork()} is
418 called, a new address space is created and the tracer must be notified to
419 create new buffers for it. @strong{TODO: specify how to do it.}
421 This can be done automatically (for @code{fork()} only for now), by
422 @env{LD_PRELOAD}'ing @file{libinterfork.so}. This library intercepts calls to
423 @code{fork()} and informs the tracer it is being called. When using
424 @command{usttrace}, this is accomplied by specifying the @option{-f} command
427 @node Tracing programs and libraries that were not linked to libust
428 @section Tracing programs and libraries that were not linked to libust
438 @chapter Viewing traces