1 .TH "LTTNG-UST" "3" "February 16, 2012" "" ""
4 lttng-ust \(em Linux Trace Toolkit Next Generation User-Space Tracer 2.x
10 Link liblttng-ust.so with applications, following this manpage.
15 LTTng-UST, the Linux Trace Toolkit Next Generation Userspace Tracer, is a
16 port of the low-overhead tracing capabilities of the LTTng kernel tracer
17 to user-space. The library "liblttng-ust" enables tracing of
18 applications and libraries.
20 .SH "USAGE WITH TRACEF"
22 The simplest way to add instrumentation to your code is by far the
23 tracef() API. To do it, in a nutshell:
25 1) #include <lttng/tracef.h>
27 2) /* in your code, use like a printf */
28 tracef("my message, this integer %d", 1234);
30 3) Link your program against liblttng-ust.so.
32 4) Enable UST events when tracing with the following sequence of commands
36 lttng enable-event -u -a
38 [... run your program ...]
44 If you want to have more flexibility and control on the event names,
45 payload typing, etc, you can continue reading on and use the tracepoints
46 below. "tracef()" is there for quick and dirty ad hoc instrumentation,
47 whereas tracepoint.h is meant for thorough instrumentation of a code
48 base to be integrated with an upstream project.
51 .SH "USAGE WITH TRACEPOINT"
53 The simple way to generate the lttng-ust tracepoint probes is to use the
54 lttng-gen-tp(1) tool. See the lttng-gen-tp(1) manpage for explanation.
58 Here is the way to do it manually, without the lttng-gen-tp(1) helper
59 script, through an example:
62 .SH "CREATION OF TRACEPOINT PROVIDER"
66 To create a tracepoint provider, within a build tree similar to
67 examples/easy-ust installed with lttng-ust documentation, see
68 sample_component_provider.h for the general layout. You will need to
69 define TRACEPOINT_CREATE_PROBES before including your tracepoint
70 provider probe in one source file of your application. See tp.c from
71 easy-ust for an example of a tracepoint probe source file. This manpage
72 will focus on the various types that can be recorded into a trace
77 * provider name, not a variable but a string starting with a
78 * letter and containing either letters, numbers or underscores.
79 * Needs to be the same as TRACEPOINT_PROVIDER. Needs to
80 * follow the namespacing guide-lines in lttng/tracepoint.h:
82 * Must be included before include tracepoint provider
84 * ex.: project_component_event
86 * Optional company name goes here
87 * ex.: com_efficios_project_component_event
89 * In this example, "sample" is the project, and "component" is the
95 * tracepoint name, characters permitted follow the same
96 * constraints as the provider name. The name of this example
97 * event is "sample_event".
102 * TP_ARGS macro contains the arguments passed for the tracepoint
103 * it is in the following format
104 * TP_ARGS(type1, name1, type2, name2, ... type10,
106 * where there can be from zero to ten elements.
107 * typeN is the datatype, such as int, struct or double **.
108 * name is the variable name (in "int myInt" the name would be
110 * TP_ARGS() is valid to mean no arguments
111 * TP_ARGS(void) is valid too
113 TP_ARGS(int, anint, int, netint, long *, values,
114 char *, text, size_t, textlen,
115 double, doublearg, float, floatarg),
118 * TP_FIELDS describes how to write the fields of the trace event.
119 * You can put expressions in the "argument expression" area,
120 * typically using the input arguments from TP_ARGS.
124 * ctf_integer: standard integer field.
125 * args: (type, field name, argument expression)
127 ctf_integer(int, intfield, anint)
128 ctf_integer(long, longfield, anint)
131 * ctf_integer_hex: integer field printed as hexadecimal.
132 * args: (type, field name, argument expression)
134 ctf_integer_hex(int, intfield2, anint)
137 * ctf_integer_network: integer field in network byte
138 * order. (_hex: printed as hexadecimal too)
139 * args: (type, field name, argument expression)
141 ctf_integer_network(int, netintfield, netint)
142 ctf_integer_network_hex(int, netintfieldhex, netint)
145 * ctf_array: a statically-sized array.
146 * args: (type, field name, argument expression, value)
148 ctf_array(long, arrfield1, values, 3)
151 * ctf_array_text: a statically-sized array, printed as
152 * a string. No need to be terminated by a null
154 * Behavior is undefined if "text" argument is NULL.
156 ctf_array_text(char, arrfield2, text, 10)
159 * ctf_sequence: a dynamically-sized array.
160 * args: (type, field name, argument expression,
161 * type of length expression, length expression)
162 * The "type of length expression" needs to be an
163 * unsigned type. As a reminder, "unsigned char" should
164 * be preferred to "char", since the signedness of
165 * "char" is implementation-defined.
166 * Behavior is undefined if "text" argument is NULL.
168 ctf_sequence(char, seqfield1, text,
172 * ctf_sequence_text: a dynamically-sized array, printed
173 * as string. No need to be null-terminated.
174 * Behavior is undefined if "text" argument is NULL.
176 ctf_sequence_text(char, seqfield2, text,
180 * ctf_string: null-terminated string.
181 * args: (field name, argument expression)
182 * Behavior is undefined if "text" argument is NULL.
184 ctf_string(stringfield, text)
187 * ctf_float: floating-point number.
188 * args: (type, field name, argument expression)
190 ctf_float(float, floatfield, floatarg)
191 ctf_float(double, doublefield, doublearg)
195 There can be an arbitrary number of tracepoint providers within an
196 application, but they must each have their own provider name. Duplicate
197 provider names are not allowed.
201 .SH "ASSIGNING LOGLEVEL TO EVENTS"
205 Optionally, a loglevel can be assigned to a TRACEPOINT_EVENT using the
208 TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >,
209 < event >, < loglevel_name >)
211 The first field is the provider name, the second field is the name of
212 the tracepoint, and the third field is the loglevel name. A
213 TRACEPOINT_EVENT should be declared prior to the the TRACEPOINT_LOGLEVEL
214 for a given tracepoint name. The TRACEPOINT_PROVIDER must be already
215 declared before declaring a TRACEPOINT_LOGLEVEL.
217 The loglevels go from 0 to 14. Higher numbers imply the most verbosity
218 (higher event throughput expected.
220 Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels
221 semantic. Loglevels 7 through 13 offer more fine-grained selection of
228 action must be taken immediately
240 normal, but significant, condition
243 informational message
246 debug information with system-level scope (set of programs)
248 TRACE_DEBUG_PROGRAM 8
249 debug information with program-level scope (set of processes)
251 TRACE_DEBUG_PROCESS 9
252 debug information with process-level scope (set of modules)
254 TRACE_DEBUG_MODULE 10
255 debug information with module (executable/library) scope (set of
259 debug information with compilation unit scope (set of functions)
261 TRACE_DEBUG_FUNCTION 12
262 debug information with function-level scope
265 debug information with line-level scope (TRACEPOINT_EVENT default)
270 See lttng(1) for information on how to use LTTng-UST loglevels.
274 .SH "ADDING TRACEPOINTS TO YOUR CODE"
278 Include the provider header in each C files you plan to instrument,
279 following the building/linking directives in the next section.
281 For instance, add within a function:
283 tracepoint(ust_tests_hello, tptest, i, netint, values,
284 text, strlen(text), dbl, flt);
286 As a call to the tracepoint. It will only be activated when requested by
287 lttng(1) through lttng-sessiond(8).
289 Even though LTTng-UST supports tracepoint() call site duplicates having
290 the same provider and event name, it is recommended to use a
291 provider event name pair only once within the source code to help
292 map events back to their call sites when analyzing the trace.
294 Sometimes arguments to the probe are expensive to compute (e.g.
295 take call stack). To avoid the computation when the tracepoint is
296 disabled one can use more 'low level' tracepoint_enabled() and
297 do_tracepoint() macros as following:
299 if (tracepoint_enabled(ust_tests_hello, tptest)) {
300 /* prepare arguments */
301 do_tracepoint(ust_tests_hello, tptest, i, netint, values,
302 text, strlen(text), dbl, flt);
305 Here do_tracepoint() doesn't contain check if the tracepoint is enabled.
306 Using tracepoint() in such scenario is dangerous since it also contains
307 enabled check and thus race condition is possible in the following code
308 if the tracepoint has been enabled after check in tracepoint_enabled()
309 but before tracepoint():
311 if (tracepoint_enabled(provider, name)) { /* tracepoint is disabled */
314 /* tracepoint is enabled by 'lttng' tool */
315 tracepoint(provider, name, args); /* args wasn't prepared properly */
317 Note also that neither tracepoint_enabled() nor do_tracepoint() have
318 STAP_PROBEV() call so if you need it you should emit this call yourself.
322 .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER"
325 There are 2 ways to compile the Tracepoint Provider with the
326 application: either statically or dynamically. Please follow
329 1) Compile the Tracepoint Provider with the application, either
330 directly or through a static library (.a):
331 - Into exactly one object of your application, define
332 "TRACEPOINT_DEFINE" and include the tracepoint provider.
333 - Use "\-I." for the compilation unit containing the tracepoint
334 provider include (e.g., tp.c).
335 - Link the application with "\-llttng-ust" and "\-ldl".
336 - Include the tracepoint provider header into all C files using
339 - doc/examples/easy-ust/ sample.c sample_component_provider.h tp.c
341 - doc/examples/hello-static-lib/ hello.c tp.c ust_test_hello.h Makefile
343 2) Compile the Tracepoint Provider separately from the application,
344 using dynamic linking:
345 - Into exactly one object of your application: define
346 "TRACEPOINT_DEFINE" _and_ also define
347 "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint
349 - Include the tracepoint provider header into all instrumented C
350 files that use the provider.
351 - Compile the tracepoint provider with "\-I.".
352 - Link the tracepoint provider with "\-llttng-ust".
353 - Link application with "\-ldl".
354 - Set a LD_PRELOAD environment to preload the tracepoint provider
355 shared object before starting the application when tracing is
356 needed. Another way is to dlopen the tracepoint probe when needed
359 - doc/examples/demo demo.c tp*.c ust_tests_demo*.h demo-trace Makefile
361 - Note about dlclose() usage: it is not safe to use dlclose on a
362 provider shared object that is being actively used for tracing due
363 to a lack of reference counting from lttng-ust to the used shared
365 - Enable instrumentation and control tracing with the "lttng" command
366 from lttng-tools. See lttng-tools doc/quickstart.txt.
367 - Note for C++ support: although an application instrumented with
368 tracepoints can be compiled with g++, tracepoint probes should be
369 compiled with gcc (only tested with gcc so far).
373 .SH "USING LTTNG UST WITH DAEMONS"
376 Some extra care is needed when using liblttng-ust with daemon
377 applications that call fork(), clone(), or BSD rfork() without a
378 following exec() family system call. The library "liblttng-ust-fork.so"
379 needs to be preloaded for the application (launch with e.g.
380 LD_PRELOAD=liblttng-ust-fork.so appname).
387 Context information can be prepended by the tracer before each, or some,
388 events. The following context information is supported by LTTng-UST:
393 Virtual thread ID: thread ID as seen from the point of view of the
399 Virtual process ID: process ID as seen from the point of view of the
405 Instruction pointer: Enables recording of the exact location where a tracepoint
406 was emitted. Can be used to reverse-lookup the source location that caused the
412 Thread name, as set by exec() or prctl(). It is recommended that
413 programs set their thread name with prctl() before hitting the first
414 tracepoint for that thread.
419 Pthread identifier. Can be used on architectures where pthread_t maps
420 nicely to an unsigned long type.
423 .SH "BASE ADDRESS STATEDUMP"
426 If an application that uses liblttng-ust.so becomes part of a session,
427 information about its currently loaded shared objects will be traced to the
428 session at session-enable time. To record this information, the following event
431 .IP "ust_baddr_statedump:soinfo"
432 This event is used to trace a currently loaded shared object. The base address
433 (where the dynamic linker has placed the shared object) is recorded in the
434 "baddr" field. The path to the shared object gets recorded in the
435 "sopath" field (as string). The file size of the loaded object (in
436 bytes) is recorded to the "size" field and its time of last modification
437 (in seconds since Epoch) is recorded in the "mtime" field.
439 If the event above is enabled, a series of "ust_baddr_statedump:soinfo"
440 events is recorded at session-enable time. It represents the state of
441 currently loaded shared objects for the traced process. If this
442 information gets combined with the lttng-ust-dl(3) instrumentation, all
443 aspects of dynamic loading that are relevant for symbol and
444 line number lookup are traced by LTTng.
446 .SH "ENVIRONMENT VARIABLES"
449 .IP "LTTNG_UST_DEBUG"
450 Activate liblttng-ust debug and error output.
452 .IP "LTTNG_UST_REGISTER_TIMEOUT"
453 The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
454 specify how long the applications should wait for sessiond
455 "registration done" command before proceeding to execute the main
456 program. The default is 3000ms (3 seconds). The timeout value is
457 specified in milliseconds. The value 0 means "don't wait". The value
458 \-1 means "wait forever". Setting this environment variable to 0 is
459 recommended for applications with time constraints on the process
462 .IP "LTTNG_UST_WITHOUT_BADDR_STATEDUMP"
463 Prevent liblttng-ust to perform a base-address statedump on session-enable.
469 lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3),
470 lttng-ust-dl(3), lttng-sessiond(8)
476 Older lttng-ust libraries reject more recent, and incompatible, probe
477 providers. Newer lttng-ust libraries accept older probe providers, even
478 though some newer features might not be available with those providers.
484 LTTng-UST 2.0 and 2.1 lttng-ust libraries do not check for probe
485 provider version compatibility. This can lead to out-of-bound accesses
486 when using a more recent probe provider with an older lttng-ust library.
487 These error only trigger when tracing is active. This issue has been
488 fixed in LTTng-UST 2.2.
490 If you encounter any issues or usability problem, please report it on
491 our mailing list <lttng-dev@lists.lttng.org> to help improve this
495 liblttng-ust is distributed under the GNU Lesser General Public License
496 version 2.1. The headers are distributed under the MIT license.
498 See http://lttng.org for more information on the LTTng project.
500 Mailing list for support and development: <lttng-dev@lists.lttng.org>.
502 You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
506 Thanks to Ericsson for funding this work, providing real-life use-cases,
509 Special thanks to Michel Dagenais and the DORSAL laboratory at
510 Polytechnique de Montreal for the LTTng journey.
515 liblttng-ust was originally written by Mathieu Desnoyers, with additional
516 contributions from various other people. It is currently maintained by
517 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.