1LTTNG-UST(3) LTTng Manual LTTNG-UST(3)
2
6 lttng-ust - LTTng user space tracing
7
9 #include <lttng/tracepoint.h>
10 #define TRACEPOINT_ENUM(prov_name, enum_name, mappings)
12 #define TRACEPOINT_EVENT(prov_name, t_name, args, fields)
13 #define TRACEPOINT_EVENT_CLASS(prov_name, class_name, args, fields)
14 #define TRACEPOINT_EVENT_INSTANCE(prov_name, class_name, t_name, args)
15 #define TRACEPOINT_LOGLEVEL(prov_name, t_name, level)
16 #define ctf_array(int_type, field_name, expr, count)
17 #define ctf_array_nowrite(int_type, field_name, expr, count)
18 #define ctf_array_hex(int_type, field_name, expr, count)
19 #define ctf_array_nowrite_hex(int_type, field_name, expr, count)
20 #define ctf_array_network(int_type, field_name, expr, count)
21 #define ctf_array_network_nowrite(int_type, field_name, expr, count)
22 #define ctf_array_network_hex(int_type, field_name, expr, count)
23 #define ctf_array_network_nowrite_hex(int_type, field_name, expr, count)
24 #define ctf_array_text(char, field_name, expr, count)
25 #define ctf_array_text_nowrite(char, field_name, expr, count)
26 #define ctf_enum(prov_name, enum_name, int_type, field_name, expr)
27 #define ctf_enum_nowrite(prov_name, enum_name, int_type, field_name,
28 expr)
29 #define ctf_enum_value(label, value)
30 #define ctf_enum_range(label, start, end)
31 #define ctf_float(float_type, field_name, expr)
32 #define ctf_float_nowrite(float_type, field_name, expr)
33 #define ctf_integer(int_type, field_name, expr)
34 #define ctf_integer_hex(int_type, field_name, expr)
35 #define ctf_integer_network(int_type, field_name, expr)
36 #define ctf_integer_network_hex(int_type, field_name, expr)
37 #define ctf_integer_nowrite(int_type, field_name, expr)
38 #define ctf_sequence(int_type, field_name, expr, len_type, len_expr)
39 #define ctf_sequence_nowrite(int_type, field_name, expr, len_type,
40 len_expr)
41 #define ctf_sequence_hex(int_type, field_name, expr, len_type,
42 len_expr)
43 #define ctf_sequence_nowrite_hex(int_type, field_name, expr, len_type,
44 len_expr)
45 #define ctf_sequence_network(int_type, field_name, expr, len_type,
46 len_expr)
47 #define ctf_sequence_network_nowrite(int_type, field_name, expr,
48 len_type, len_expr)
49 #define ctf_sequence_network_hex(int_type, field_name, expr, len_type,
50 len_expr)
51 #define ctf_sequence_network_nowrite_hex(int_type, field_name, expr,
52 len_type, len_expr)
53 #define ctf_sequence_text(char, field_name, expr, len_type, len_expr)
54 #define ctf_sequence_text_nowrite(char, field_name, expr, len_type,
55 len_expr)
56 #define ctf_string(field_name, expr)
57 #define ctf_string_nowrite(field_name, expr)
58 #define do_tracepoint(prov_name, t_name, ...)
59 #define tracepoint(prov_name, t_name, ...)
60 #define tracepoint_enabled(prov_name, t_name)
61 Link with -llttng-ust -ldl, following this man page.
63
65 The Linux Trace Toolkit: next generation <http://lttng.org/> is an open
66 source software package used for correlated tracing of the Linux
67 kernel, user applications, and user libraries.
68 LTTng-UST is the user space tracing component of the LTTng project. It
70 is a port to user space of the low-overhead tracing capabilities of the
71 LTTng Linux kernel tracer. The liblttng-ust library is used to trace
72 user applications and libraries.
73 Note
75 This man page is about the liblttng-ust library. The LTTng-UST
76 project also provides Java and Python packages to trace
77 applications written in those languages. How to instrument and
78 trace Java and Python applications is documented in the online
79 LTTng documentation <http://lttng.org/docs/>.
80 There are three ways to use liblttng-ust:
82 · Using the tracef(3) API, which is similar to printf(3).
84 · Using the tracelog(3) API, which is tracef(3) with a log level
86 parameter.
87 · Defining your own tracepoints. See the Creating a tracepoint
89 provider section below.
90 Creating a tracepoint provider
92 Creating a tracepoint provider is the first step of using liblttng-ust.
93 The next steps are:
94 · Instrumenting your application with tracepoint() calls
96 · Building your application with LTTng-UST support, either statically
98 or dynamically.
99 A tracepoint provider is a compiled object containing the event probes
101 corresponding to your custom tracepoint definitions. A tracepoint
102 provider contains the code to get the size of an event and to serialize
103 it, amongst other things.
104 To create a tracepoint provider, start with the following tracepoint
106 provider header template:
107 #undef TRACEPOINT_PROVIDER
109 #define TRACEPOINT_PROVIDER my_provider
110 #undef TRACEPOINT_INCLUDE
112 #define TRACEPOINT_INCLUDE "./tp.h"
113 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
115 #define _TP_H
116 #include <lttng/tracepoint.h>
118 /*
120 * TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
121 * TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(),
122 * and `TRACEPOINT_ENUM()` are used here.
123 */
124 #endif /* _TP_H */
126 #include <lttng/tracepoint-event.h>
128 In this template, the tracepoint provider is named my_provider
130 (TRACEPOINT_PROVIDER definition). The file needs to bear the name of
131 the TRACEPOINT_INCLUDE definition (tp.h in this case). Between #include
132 <lttng/tracepoint.h> and #endif go the invocations of the
133 TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
134 TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(), and
135 TRACEPOINT_ENUM() macros.
136 Note
138 You can avoid writing the prologue and epilogue boilerplate in the
139 template file above by using the lttng-gen-tp(1) tool shipped with
140 LTTng-UST.
141 The tracepoint provider header file needs to be included in a source
143 file which looks like this:
144 #define TRACEPOINT_CREATE_PROBES
146 #include "tp.h"
148 Together, those two files (let’s call them tp.h and tp.c) form the
150 tracepoint provider sources, ready to be compiled.
151 You can create multiple tracepoint providers to be used in a single
153 application, but each one must have its own header file.
154 The TRACEPOINT_EVENT() usage section below shows how to use the
156 TRACEPOINT_EVENT() macro to define the actual tracepoints in the
157 tracepoint provider header file.
158 See the EXAMPLE section below for a complete example.
160 TRACEPOINT_EVENT() usage
162 The TRACEPOINT_EVENT() macro is used in a template provider header file
163 (see the Creating a tracepoint provider section above) to define
164 LTTng-UST tracepoints.
165 The TRACEPOINT_EVENT() usage template is as follows:
167 TRACEPOINT_EVENT(
169 /* Tracepoint provider name */
170 my_provider,
171 /* Tracepoint/event name */
173 my_tracepoint,
174 /* List of tracepoint arguments (input) */
176 TP_ARGS(
177 ...
178 ),
179 /* List of fields of eventual event (output) */
181 TP_FIELDS(
182 ...
183 )
184 )
185 The TP_ARGS() macro contains the input arguments of the tracepoint.
187 Those arguments can be used in the argument expressions of the output
188 fields defined in TP_FIELDS().
189 The format of the TP_ARGS() parameters is: C type, then argument name;
191 repeat as needed, up to ten times. For example:
192 TP_ARGS(
194 int, my_int,
195 const char *, my_string,
196 FILE *, my_file,
197 double, my_float,
198 struct my_data *, my_data
199 )
200 The TP_FIELDS() macro contains the output fields of the tracepoint,
202 that is, the actual data that can be recorded in the payload of an
203 event emitted by this tracepoint.
204 The TP_FIELDS() macro contains a list of ctf_*() macros NOT separated
206 by commas. The available macros are documented in the Available ctf_*()
207 field type macros section below.
208 Available ctf_*() field type macros
210 This section documents the available ctf_*() macros that can be
211 inserted in the TP_FIELDS() macro of the TRACEPOINT_EVENT() macro.
212 Standard integer, displayed in base 10:
214 ctf_integer(int_type, field_name, expr)
216 ctf_integer_nowrite(int_type, field_name, expr)
217 Standard integer, displayed in base 16:
219 ctf_integer_hex(int_type, field_name, expr)
221 Integer in network byte order (big endian), displayed in base 10:
223 ctf_integer_network(int_type, field_name, expr)
225 Integer in network byte order, displayed in base 16:
227 ctf_integer_network_hex(int_type, field_name, expr)
229 Floating point number:
231 ctf_float(float_type, field_name, expr)
233 ctf_float_nowrite(float_type, field_name, expr)
234 Null-terminated string:
236 ctf_string(field_name, expr)
238 ctf_string_nowrite(field_name, expr)
239 Statically-sized array of integers (_hex versions displayed in
241 hexadecimal, _network versions in network byte order):
242 ctf_array(int_type, field_name, expr, count)
244 ctf_array_nowrite(int_type, field_name, expr, count)
245 ctf_array_hex(int_type, field_name, expr, count)
246 ctf_array_nowrite_hex(int_type, field_name, expr, count)
247 ctf_array_network(int_type, field_name, expr, count)
248 ctf_array_network_nowrite(int_type, field_name, expr, count)
249 ctf_array_network_hex(int_type, field_name, expr, count)
250 ctf_array_network_nowrite_hex(int_type, field_name, expr, count)
251 Statically-sized array, printed as text; no need to be null-terminated:
253 ctf_array_text(char, field_name, expr, count)
255 ctf_array_text_nowrite(char, field_name, expr, count)
256 Dynamically-sized array of integers (_hex versions displayed in
258 hexadecimal, _network versions in network byte order):
259 ctf_sequence(int_type, field_name, expr, len_type, len_expr)
261 ctf_sequence_nowrite(int_type, field_name, expr, len_type, len_expr)
262 ctf_sequence_hex(int_type, field_name, expr, len_type, len_expr)
263 ctf_sequence_nowrite_hex(int_type, field_name, expr, len_type,
264 len_expr)
265 ctf_sequence_network(int_type, field_name, expr, len_type, len_expr)
266 ctf_sequence_network_nowrite(int_type, field_name, expr, len_type,
267 len_expr)
268 ctf_sequence_network_hex(int_type, field_name, expr, len_type,
269 len_expr)
270 ctf_sequence_network_nowrite_hex(int_type, field_name, expr,
271 len_type, len_expr)
272 Dynamically-sized array, displayed as text; no need to be
274 null-terminated:
275 ctf_sequence_text(char, field_name, expr, len_type, len_expr)
277 ctf_sequence_text_nowrite(char, field_name, expr, len_type, len_expr)
278 Enumeration. The enumeration field must be defined before using this
280 macro with the TRACEPOINT_ENUM() macro. See the TRACEPOINT_ENUM() usage
281 section for more information.
282 ctf_enum(prov_name, enum_name, int_type, field_name, expr)
284 ctf_enum_nowrite(prov_name, enum_name, int_type, field_name, expr)
285 The parameters are:
287 count
289 Number of elements in array/sequence. This must be known at compile
290 time.
291 enum_name
293 Name of an enumeration field previously defined with the
294 TRACEPOINT_ENUM() macro. See the TRACEPOINT_ENUM() usage section
295 for more information.
296 expr
298 C expression resulting in the field’s value. This expression can
299 use one or more arguments passed to the tracepoint. The arguments
300 of a given tracepoint are defined in the TP_ARGS() macro (see the
301 Creating a tracepoint provider section above).
302 field_name
304 Event field name (C identifier syntax, NOT a literal string).
305 float_type
307 Float C type (float or double). The size of this type determines
308 the size of the floating point number field.
309 int_type
311 Integer C type. The size of this type determines the size of the
312 integer/enumeration field.
313 len_expr
315 C expression resulting in the sequence’s length. This expression
316 can use one or more arguments passed to the tracepoint.
317 len_type
319 Unsigned integer C type of sequence’s length.
320 prov_name
322 Tracepoint provider name. This must be the same as the tracepoint
323 provider name used in a previous field definition.
324 The _nowrite versions omit themselves from the recorded trace, but are
326 otherwise identical. Their primary purpose is to make some of the event
327 context available to the event filters without having to commit the
328 data to sub-buffers. See lttng-enable-event(1) to learn more about
329 dynamic event filtering.
330 See the EXAMPLE section below for a complete example.
332 TRACEPOINT_ENUM() usage
334 An enumeration field is a list of mappings between an integers, or a
335 range of integers, and strings (sometimes called labels or
336 enumerators). Enumeration fields can be used to have a more compact
337 trace when the possible values for a field are limited.
338 An enumeration field is defined with the TRACEPOINT_ENUM() macro:
340 TRACEPOINT_ENUM(
342 /* Tracepoint provider name */
343 my_provider,
344 /* Enumeration name (unique in the whole tracepoint provider) */
346 my_enum,
347 /* Enumeration mappings */
349 TP_ENUM_VALUES(
350 ...
351 )
352 )
353 TP_ENUM_VALUES() contains a list of enumeration mappings, NOT separated
355 by commas. Two macros can be used in the TP_ENUM_VALUES():
356 ctf_enum_value() and ctf_enum_range().
357 ctf_enum_value() is a single value mapping:
359 ctf_enum_value(label, value)
361 This macro maps the given label string to the value value.
363 ctf_enum_range() is a range mapping:
365 ctf_enum_range(label, start, end)
367 This macro maps the given label string to the range of integers from
369 start to end, inclusively. Range mappings may overlap, but the
370 behaviour is implementation-defined: each trace reader handles
371 overlapping ranges as it wishes.
372 See the EXAMPLE section below for a complete example.
374 TRACEPOINT_EVENT_CLASS() usage
376 A tracepoint class is a class of tracepoints sharing the same field
377 types and names. A tracepoint instance is one instance of such a
378 declared tracepoint class, with its own event name.
379 LTTng-UST creates one event serialization function per tracepoint
381 class. Using TRACEPOINT_EVENT() creates one tracepoint class per
382 tracepoint definition, whereas using TRACEPOINT_EVENT_CLASS() and
383 TRACEPOINT_EVENT_INSTANCE() creates one tracepoint class, and one or
384 more tracepoint instances of this class. In other words, many
385 tracepoints can reuse the same serialization code. Reusing the same
386 code, when possible, can reduce cache pollution, thus improve
387 performance.
388 The TRACEPOINT_EVENT_CLASS() macro accepts the same parameters as the
390 TRACEPOINT_EVENT() macro, except that instead of an event name, its
391 second parameter is the tracepoint class name:
392 TRACEPOINT_EVENT_CLASS(
394 /* Tracepoint provider name */
395 my_provider,
396 /* Tracepoint class name */
398 my_tracepoint_class,
399 /* List of tracepoint arguments (input) */
401 TP_ARGS(
402 ...
403 ),
404 /* List of fields of eventual event (output) */
406 TP_FIELDS(
407 ...
408 )
409 )
410 Once the tracepoint class is defined, you can create as many tracepoint
412 instances as needed:
413 TRACEPOINT_EVENT_INSTANCE(
415 /* Tracepoint provider name */
416 my_provider,
417 /* Tracepoint class name */
419 my_tracepoint_class,
420 /* Tracepoint/event name */
422 my_tracepoint,
423 /* List of tracepoint arguments (input) */
425 TP_ARGS(
426 ...
427 )
428 )
429 As you can see, the TRACEPOINT_EVENT_INSTANCE() does not contain the
431 TP_FIELDS() macro, because they are defined at the
432 TRACEPOINT_EVENT_CLASS() level.
433 See the EXAMPLE section below for a complete example.
435 TRACEPOINT_LOGLEVEL() usage
437 Optionally, a log level can be assigned to a defined tracepoint.
438 Assigning different levels of severity to tracepoints can be useful:
439 when controlling tracing sessions, you can choose to only enable events
440 falling into a specific log level range using the --loglevel and
441 --loglevel-only options of the lttng-enable-event(1) command.
442 Log levels are assigned to tracepoints that are already defined using
444 the TRACEPOINT_LOGLEVEL() macro. The latter must be used after having
445 used TRACEPOINT_EVENT() or TRACEPOINT_EVENT_INSTANCE() for a given
446 tracepoint. The TRACEPOINT_LOGLEVEL() macro is used as follows:
447 TRACEPOINT_LOGLEVEL(
449 /* Tracepoint provider name */
450 my_provider,
451 /* Tracepoint/event name */
453 my_tracepoint,
454 /* Log level */
456 TRACE_INFO
457 )
458 The available log level definitions are:
460 TRACE_EMERG
462 System is unusable.
463 TRACE_ALERT
465 Action must be taken immediately.
466 TRACE_CRIT
468 Critical conditions.
469 TRACE_ERR
471 Error conditions.
472 TRACE_WARNING
474 Warning conditions.
475 TRACE_NOTICE
477 Normal, but significant, condition.
478 TRACE_INFO
480 Informational message.
481 TRACE_DEBUG_SYSTEM
483 Debug information with system-level scope (set of programs).
484 TRACE_DEBUG_PROGRAM
486 Debug information with program-level scope (set of processes).
487 TRACE_DEBUG_PROCESS
489 Debug information with process-level scope (set of modules).
490 TRACE_DEBUG_MODULE
492 Debug information with module (executable/library) scope (set of
493 units).
494 TRACE_DEBUG_UNIT
496 Debug information with compilation unit scope (set of functions).
497 TRACE_DEBUG_FUNCTION
499 Debug information with function-level scope.
500 TRACE_DEBUG_LINE
502 Debug information with line-level scope (default log level).
503 TRACE_DEBUG
505 Debug-level message.
506 See the EXAMPLE section below for a complete example.
508 Instrumenting your application
510 Once the tracepoint provider is created (see the Creating a tracepoint
511 provider section above), you can instrument your application with the
512 defined tracepoints thanks to the tracepoint() macro:
513 #define tracepoint(prov_name, t_name, ...)
515 With:
517 prov_name
519 Tracepoint provider name.
520 t_name
522 Tracepoint/event name.
523 ...
525 Tracepoint arguments, if any.
526 Make sure to include the tracepoint provider header file anywhere you
528 use tracepoint() for this provider.
529 Note
531 Even though LTTng-UST supports tracepoint() call site duplicates
532 having the same provider and tracepoint names, it is recommended to
533 use a provider/tracepoint name pair only once within the
534 application source code to help map events back to their call sites
535 when analyzing the trace.
536 Sometimes, arguments to the tracepoint are expensive to compute (take
538 call stack, for example). To avoid the computation when the tracepoint
539 is disabled, you can use the tracepoint_enabled() and do_tracepoint()
540 macros:
541 #define tracepoint_enabled(prov_name, t_name)
543 #define do_tracepoint(prov_name, t_name, ...)
544 tracepoint_enabled() returns a non-zero value if the tracepoint named
546 t_name from the provider named prov_name is enabled at run time.
547 do_tracepoint() is like tracepoint(), except that it doesn’t check if
549 the tracepoint is enabled. Using tracepoint() with tracepoint_enabled()
550 is dangerous since tracepoint() also contains the tracepoint_enabled()
551 check, thus a race condition is possible in this situation:
552 if (tracepoint_enabled(my_provider, my_tracepoint)) {
554 stuff = prepare_stuff();
555 }
556 tracepoint(my_provider, my_tracepoint, stuff);
558 If the tracepoint is enabled after the condition, then stuff is not
560 prepared: the emitted event will either contain wrong data, or the
561 whole application could crash (segmentation fault, for example).
562 Note
564 Neither tracepoint_enabled() nor do_tracepoint() have a
565 STAP_PROBEV() call, so if you need it, you should emit this call
566 yourself.
567 Statically linking the tracepoint provider
569 With the static linking method, compiled tracepoint providers are
570 copied into the target application.
571 Define TRACEPOINT_DEFINE definition below the TRACEPOINT_CREATE_PROBES
573 definition in the tracepoint provider source:
574 #define TRACEPOINT_CREATE_PROBES
576 #define TRACEPOINT_DEFINE
577 #include "tp.h"
579 Create the tracepoint provider object file:
581 $ cc -c -I. tp.c
583 Note
586 Although an application instrumented with LTTng-UST tracepoints can
587 be compiled with a C++ compiler, tracepoint probes should be
588 compiled with a C compiler.
589 At this point, you can archive this tracepoint provider object file,
591 possibly with other object files of your application or with other
592 tracepoint provider object files, as a static library:
593 $ ar rc tp.a tp.o
595 Using a static library does have the advantage of centralising the
597 tracepoint providers objects so they can be shared between multiple
598 applications. This way, when the tracepoint provider is modified, the
599 source code changes don’t have to be patched into each application’s
600 source code tree. The applications need to be relinked after each
601 change, but need not to be otherwise recompiled (unless the tracepoint
602 provider’s API changes).
603 Then, link your application with this object file (or with the static
605 library containing it) and with liblttng-ust and libdl (libc on a BSD
606 system):
607 $ cc -o app tp.o app.o -llttng-ust -ldl
609 Dynamically loading the tracepoint provider
611 The second approach to package the tracepoint provider is to use the
612 dynamic loader: the library and its member functions are explicitly
613 sought, loaded at run time.
614 In this scenario, the tracepoint provider is compiled as a shared
616 object.
617 The process to create the tracepoint provider shared object is pretty
619 much the same as the static linking method, except that:
620 · Since the tracepoint provider is not part of the application,
622 TRACEPOINT_DEFINE must be defined, for each tracepoint provider, in
623 exactly one source file of the application
624 · TRACEPOINT_PROBE_DYNAMIC_LINKAGE must be defined next to
626 TRACEPOINT_DEFINE
627 Regarding TRACEPOINT_DEFINE and TRACEPOINT_PROBE_DYNAMIC_LINKAGE, the
629 recommended practice is to use a separate C source file in your
630 application to define them, then include the tracepoint provider header
631 files afterwards. For example, as tp-define.c:
632 #define TRACEPOINT_DEFINE
634 #define TRACEPOINT_PROBE_DYNAMIC_LINKAGE
635 #include "tp.h"
637 The tracepoint provider object file used to create the shared library
639 is built like it is using the static linking method, but with the -fpic
640 option:
641 $ cc -c -fpic -I. tp.c
643 It is then linked as a shared library like this:
645 $ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
647 This tracepoint provider shared object isn’t linked with the user
649 application: it must be loaded manually. This is why the application is
650 built with no mention of this tracepoint provider, but still needs
651 libdl:
652 $ cc -o app app.o tp-define.o -ldl
654 There are two ways to dynamically load the tracepoint provider shared
656 object:
657 · Load it manually from the application using dlopen(3)
659 · Make the dynamic loader load it with the LD_PRELOAD environment
661 variable (see ld.so(8))
662 If the application does not dynamically load the tracepoint provider
664 shared object using one of the methods above, tracing is disabled for
665 this application, and the events are not listed in the output of lttng-
666 list(1).
667 Note that it is not safe to use dlclose(3) on a tracepoint provider
669 shared object that is being actively used for tracing, due to a lack of
670 reference counting from LTTng-UST to the shared object.
671 For example, statically linking a tracepoint provider to a shared
673 object which is to be dynamically loaded by an application (a plugin,
674 for example) is not safe: the shared object, which contains the
675 tracepoint provider, could be dynamically closed (dlclose(3)) at any
676 time by the application.
677 To instrument a shared object, either:
679 · Statically link the tracepoint provider to the application, or
681 · Build the tracepoint provider as a shared object (following the
683 procedure shown in this section), and preload it when tracing is
684 needed using the LD_PRELOAD environment variable.
685 Using LTTng-UST with daemons
687 Some extra care is needed when using liblttng-ust with daemon
688 applications that call fork(2), clone(2), or BSD’s rfork(2) without a
689 following exec(3) family system call. The library liblttng-ust-fork.so
690 needs to be preloaded before starting the application with the
691 LD_PRELOAD environment variable (see ld.so(8)).
692 To use liblttng-ust with a daemon application which closes file
694 descriptors that were not opened by it, preload the liblttng-ust-fd.so
695 library before you start the application. Typical use cases include
696 daemons closing all file descriptors after fork(2), and buggy
697 applications doing “double-closes”.
698 Context information
700 Context information can be prepended by the LTTng-UST tracer before
701 each event, or before specific events.
702 Context fields can be added to specific channels using lttng-add-
704 context(1).
705 The following context fields are supported by LTTng-UST:
707 cpu_id
709 CPU ID.
710 Note
712 This context field is always enabled, and it cannot be added
713 with lttng-add-context(1). Its main purpose is to be used for
714 dynamic event filtering. See lttng-enable-event(1) for more
715 information about event filtering.
716 ip
718 Instruction pointer: enables recording the exact address from which
719 an event was emitted. This context field can be used to
720 reverse-lookup the source location that caused the event to be
721 emitted.
722 perf:thread:COUNTER
724 perf counter named COUNTER. Use lttng add-context --list to list
725 the available perf counters.
726 Only available on IA-32 and x86-64 architectures.
728 perf:thread:raw:rN:NAME
730 perf counter with raw ID N and custom name NAME. See lttng-add-
731 context(1) for more details.
732 pthread_id
734 POSIX thread identifier. Can be used on architectures where
735 pthread_t maps nicely to an unsigned long type.
736 procname
738 Thread name, as set by exec(3) or prctl(2). It is recommended that
739 programs set their thread name with prctl(2) before hitting the
740 first tracepoint for that thread.
741 vpid
743 Virtual process ID: process ID as seen from the point of view of
744 the current pid_namespaces(7).
745 vtid
747 Virtual thread ID: thread ID as seen from the point of view of the
748 current pid_namespaces(7).
749 The following namespaces(7) context fields are supported by LTTng-UST:
751 cgroup_ns
753 Cgroup root directory namespace: inode number of the current
754 cgroup_namespaces(7) in the proc filesystem.
755 ipc_ns
757 System V IPC, POSIX message queues namespace: inode number of the
758 current ipc_namespaces(7) namespace in the proc filesystem.
759 mnt_ns
761 Mount points namespace: inode number of the current
762 mount_namespaces(7) in the proc filesystem.
763 net_ns
765 Network devices, stacks, ports namespace: inode number of the
766 current network_namespaces(7) in the proc filesystem.
767 pid_ns
769 Process IDs namespace: inode number of the current
770 pid_namespaces(7) in the proc filesystem.
771 user_ns
773 User and group IDs namespace: inode number of the current
774 user_namespaces(7) in the proc filesystem.
775 uts_ns
777 Hostname and NIS domain name namespace: inode number of the current
778 uts_namespaces(7) in the proc filesystem.
779 The following credentials(7) context fields are supported by LTTng-UST:
781 vuid
783 Virtual real user ID: real user ID as seen from the point of view
784 of the current user_namespaces(7).
785 vgid
787 Virtual real group ID: real group ID as seen from the point of view
788 of the current user_namespaces(7).
789 veuid
791 Virtual effective user ID: effective user ID as seen from the point
792 of view of the current user_namespaces(7).
793 vegid
795 Virtual effective group ID: effective group ID as seen from the
796 point of view of the current user_namespaces(7).
797 vsuid
799 Virtual saved set-user ID: saved set-user ID as seen from the point
800 of view of the current user_namespaces(7).
801 vsgid
803 Virtual saved set-group ID: saved set-group ID as seen from the
804 point of view of the current user_namespaces(7).
805 LTTng-UST state dump
807 If an application that uses liblttng-ust becomes part of a tracing
808 session, information about its currently loaded shared objects, their
809 build IDs, and their debug link information are emitted as events by
810 the tracer.
811 The following LTTng-UST state dump events exist and must be enabled to
813 record application state dumps. Note that, during the state dump phase,
814 LTTng-UST can also emit shared library load/unload events (see Shared
815 library load/unload tracking below).
816 lttng_ust_statedump:start
818 Emitted when the state dump begins.
819 This event has no fields.
821 lttng_ust_statedump:end
823 Emitted when the state dump ends. Once this event is emitted, it is
824 guaranteed that, for a given process, the state dump is complete.
825 This event has no fields.
827 lttng_ust_statedump:bin_info
829 Emitted when information about a currently loaded executable or
830 shared object is found.
831 Fields:
833 ┌───────────────┬────────────────────────────────┐
835 │Field name │ Description │
836 ├───────────────┼────────────────────────────────┤
837 │baddr │ Base address of loaded │
838 │ │ executable. │
839 ├───────────────┼────────────────────────────────┤
840 │memsz │ Size of loaded executable │
841 │ │ in memory. │
842 ├───────────────┼────────────────────────────────┤
843 │path │ Path to loaded executable │
844 │ │ file. │
845 ├───────────────┼────────────────────────────────┤
846 │is_pic │ Whether or not the │
847 │ │ executable is │
848 │ │ position-independent code. │
849 ├───────────────┼────────────────────────────────┤
850 │has_build_id │ Whether or not the │
851 │ │ executable has a build ID. │
852 │ │ If this field is 1, you │
853 │ │ can expect that an │
854 │ │ lttng_ust_statedump:build_id │
855 │ │ event record follows this │
856 │ │ one (not necessarily │
857 │ │ immediately after). │
858 ├───────────────┼────────────────────────────────┤
859 │has_debug_link │ Whether or not the │
860 │ │ executable has debug link │
861 │ │ information. If this field │
862 │ │ is 1, you can expect that an │
863 │ │ lttng_ust_statedump:debug_link │
864 │ │ event record follows this │
865 │ │ one (not necessarily │
866 │ │ immediately after). │
867 └───────────────┴────────────────────────────────┘
868 lttng_ust_statedump:build_id
870 Emitted when a build ID is found in a currently loaded shared
871 library. See Debugging Information in Separate Files
872 <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
873 Files.html> for more information about build IDs.
874 Fields:
876 ┌───────────┬────────────────────────┐
878 │Field name │ Description │
879 ├───────────┼────────────────────────┤
880 │baddr │ Base address of loaded │
881 │ │ library. │
882 ├───────────┼────────────────────────┤
883 │build_id │ Build ID. │
884 └───────────┴────────────────────────┘
885 lttng_ust_statedump:debug_link
887 Emitted when debug link information is found in a currently loaded
888 shared library. See Debugging Information in Separate Files
889 <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
890 Files.html> for more information about debug links.
891 Fields:
893 ┌───────────┬────────────────────────┐
895 │Field name │ Description │
896 ├───────────┼────────────────────────┤
897 │baddr │ Base address of loaded │
898 │ │ library. │
899 ├───────────┼────────────────────────┤
900 │crc │ Debug link file’s CRC. │
901 ├───────────┼────────────────────────┤
902 │filename │ Debug link file name. │
903 └───────────┴────────────────────────┘
904 lttng_ust_statedump:procname
906 The process procname at process start.
907 Fields:
909 ┌───────────┬───────────────────┐
911 │Field name │ Description │
912 ├───────────┼───────────────────┤
913 │procname │ The process name. │
914 └───────────┴───────────────────┘
915 Shared library load/unload tracking
917 The LTTng-UST state dump and the LTTng-UST helper library to instrument
918 the dynamic linker (see liblttng-ust-dl(3)) can emit shared library
919 load/unload tracking events.
920 The following shared library load/unload tracking events exist and must
922 be enabled to track the loading and unloading of shared libraries:
923 lttng_ust_lib:load
925 Emitted when a shared library (shared object) is loaded.
926 Fields:
928 ┌───────────────┬────────────────────────────┐
930 │Field name │ Description │
931 ├───────────────┼────────────────────────────┤
932 │baddr │ Base address of loaded │
933 │ │ library. │
934 ├───────────────┼────────────────────────────┤
935 │memsz │ Size of loaded library in │
936 │ │ memory. │
937 ├───────────────┼────────────────────────────┤
938 │path │ Path to loaded library │
939 │ │ file. │
940 ├───────────────┼────────────────────────────┤
941 │has_build_id │ Whether or not the library │
942 │ │ has a build ID. If this │
943 │ │ field is 1, you can expect │
944 │ │ that an │
945 │ │ lttng_ust_lib:build_id │
946 │ │ event record follows this │
947 │ │ one (not necessarily │
948 │ │ immediately after). │
949 ├───────────────┼────────────────────────────┤
950 │has_debug_link │ Whether or not the library │
951 │ │ has debug link │
952 │ │ information. If this field │
953 │ │ is 1, you can expect that │
954 │ │ an │
955 │ │ lttng_ust_lib:debug_link │
956 │ │ event record follows this │
957 │ │ one (not necessarily │
958 │ │ immediately after). │
959 └───────────────┴────────────────────────────┘
960 lttng_ust_lib:unload
962 Emitted when a shared library (shared object) is unloaded.
963 Fields:
965 ┌───────────┬──────────────────────────┐
967 │Field name │ Description │
968 ├───────────┼──────────────────────────┤
969 │baddr │ Base address of unloaded │
970 │ │ library. │
971 └───────────┴──────────────────────────┘
972 lttng_ust_lib:build_id
974 Emitted when a build ID is found in a loaded shared library (shared
975 object). See Debugging Information in Separate Files
976 <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
977 Files.html> for more information about build IDs.
978 Fields:
980 ┌───────────┬────────────────────────┐
982 │Field name │ Description │
983 ├───────────┼────────────────────────┤
984 │baddr │ Base address of loaded │
985 │ │ library. │
986 ├───────────┼────────────────────────┤
987 │build_id │ Build ID. │
988 └───────────┴────────────────────────┘
989 lttng_ust_lib:debug_link
991 Emitted when debug link information is found in a loaded shared
992 library (shared object). See Debugging Information in Separate
993 Files <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
994 Files.html> for more information about debug links.
995 Fields:
997 ┌───────────┬────────────────────────┐
999 │Field name │ Description │
1000 ├───────────┼────────────────────────┤
1001 │baddr │ Base address of loaded │
1002 │ │ library. │
1003 ├───────────┼────────────────────────┤
1004 │crc │ Debug link file’s CRC. │
1005 ├───────────┼────────────────────────┤
1006 │filename │ Debug link file name. │
1007 └───────────┴────────────────────────┘
1008 Detect if LTTng-UST is loaded
1010 To detect if liblttng-ust is loaded from an application:
1011 1. Define the lttng_ust_loaded weak symbol globally:
1013 int lttng_ust_loaded __attribute__((weak));
1015 This weak symbol is set by the constructor of liblttng-ust.
1017 2. Test lttng_ust_loaded where needed:
1019 /* ... */
1021 if (lttng_ust_loaded) {
1023 /* LTTng-UST is loaded */
1024 } else {
1025 /* LTTng-UST is NOT loaded */
1026 }
1027 /* ... */
1029
1031 Note
1032 A few examples are available in the doc/examples
1033 <https://github.com/lttng/lttng-ust/tree/v2.12.0-rc3/doc/examples>
1034 directory of LTTng-UST’s source tree.
1035 This example shows all the features documented in the previous
1037 sections. The static linking method is chosen here to link the
1038 application with the tracepoint provider.
1039 You can compile the source files and link them together statically like
1041 this:
1042 $ cc -c -I. tp.c
1044 $ cc -c app.c
1045 $ cc -o app tp.o app.o -llttng-ust -ldl
1046 Using the lttng(1) tool, create an LTTng tracing session, enable all
1048 the events of this tracepoint provider, and start tracing:
1049 $ lttng create my-session
1051 $ lttng enable-event --userspace 'my_provider:*'
1052 $ lttng start
1053 You may also enable specific events:
1055 $ lttng enable-event --userspace my_provider:big_event
1057 $ lttng enable-event --userspace my_provider:event_instance2
1058 Run the application:
1060 $ ./app some arguments
1062 Stop the current tracing session and inspect the recorded events:
1064 $ lttng stop
1066 $ lttng view
1067 Tracepoint provider header file
1069 tp.h:
1070 #undef TRACEPOINT_PROVIDER
1072 #define TRACEPOINT_PROVIDER my_provider
1073 #undef TRACEPOINT_INCLUDE
1075 #define TRACEPOINT_INCLUDE "./tp.h"
1076 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
1078 #define _TP_H
1079 #include <lttng/tracepoint.h>
1081 #include <stdio.h>
1082 #include "app.h"
1084 TRACEPOINT_EVENT(
1086 my_provider,
1087 simple_event,
1088 TP_ARGS(
1089 int, my_integer_arg,
1090 const char *, my_string_arg
1091 ),
1092 TP_FIELDS(
1093 ctf_string(argc, my_string_arg)
1094 ctf_integer(int, argv, my_integer_arg)
1095 )
1096 )
1097 TRACEPOINT_ENUM(
1099 my_provider,
1100 my_enum,
1101 TP_ENUM_VALUES(
1102 ctf_enum_value("ZERO", 0)
1103 ctf_enum_value("ONE", 1)
1104 ctf_enum_value("TWO", 2)
1105 ctf_enum_range("A RANGE", 52, 125)
1106 ctf_enum_value("ONE THOUSAND", 1000)
1107 )
1108 )
1109 TRACEPOINT_EVENT(
1111 my_provider,
1112 big_event,
1113 TP_ARGS(
1114 int, my_integer_arg,
1115 const char *, my_string_arg,
1116 FILE *, stream,
1117 double, flt_arg,
1118 int *, array_arg
1119 ),
1120 TP_FIELDS(
1121 ctf_integer(int, int_field1, my_integer_arg * 2)
1122 ctf_integer_hex(long int, stream_pos, ftell(stream))
1123 ctf_float(double, float_field, flt_arg)
1124 ctf_string(string_field, my_string_arg)
1125 ctf_array(int, array_field, array_arg, 7)
1126 ctf_array_text(char, array_text_field, array_arg, 5)
1127 ctf_sequence(int, seq_field, array_arg, int,
1128 my_integer_arg / 10)
1129 ctf_sequence_text(char, seq_text_field, array_arg,
1130 int, my_integer_arg / 5)
1131 ctf_enum(my_provider, my_enum, int,
1132 enum_field, array_arg[1])
1133 )
1134 )
1135 TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING)
1137 TRACEPOINT_EVENT_CLASS(
1139 my_provider,
1140 my_tracepoint_class,
1141 TP_ARGS(
1142 int, my_integer_arg,
1143 struct app_struct *, app_struct_arg
1144 ),
1145 TP_FIELDS(
1146 ctf_integer(int, a, my_integer_arg)
1147 ctf_integer(unsigned long, b, app_struct_arg->b)
1148 ctf_string(c, app_struct_arg->c)
1149 )
1150 )
1151 TRACEPOINT_EVENT_INSTANCE(
1153 my_provider,
1154 my_tracepoint_class,
1155 event_instance1,
1156 TP_ARGS(
1157 int, my_integer_arg,
1158 struct app_struct *, app_struct_arg
1159 )
1160 )
1161 TRACEPOINT_EVENT_INSTANCE(
1163 my_provider,
1164 my_tracepoint_class,
1165 event_instance2,
1166 TP_ARGS(
1167 int, my_integer_arg,
1168 struct app_struct *, app_struct_arg
1169 )
1170 )
1171 TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO)
1173 TRACEPOINT_EVENT_INSTANCE(
1175 my_provider,
1176 my_tracepoint_class,
1177 event_instance3,
1178 TP_ARGS(
1179 int, my_integer_arg,
1180 struct app_struct *, app_struct_arg
1181 )
1182 )
1183 #endif /* _TP_H */
1185 #include <lttng/tracepoint-event.h>
1187 Tracepoint provider source file
1189 tp.c:
1190 #define TRACEPOINT_CREATE_PROBES
1192 #define TRACEPOINT_DEFINE
1193 #include "tp.h"
1195 Application header file
1197 app.h:
1198 #ifndef _APP_H
1200 #define _APP_H
1201 struct app_struct {
1203 unsigned long b;
1204 const char *c;
1205 double d;
1206 };
1207 #endif /* _APP_H */
1209 Application source file
1211 app.c:
1212 #include <stdlib.h>
1214 #include <stdio.h>
1215 #include "tp.h"
1217 #include "app.h"
1218 static int array_of_ints[] = {
1220 100, -35, 1, 23, 14, -6, 28, 1001, -3000,
1221 };
1222 int main(int argc, char* argv[])
1224 {
1225 FILE *stream;
1226 struct app_struct app_struct;
1227 tracepoint(my_provider, simple_event, argc, argv[0]);
1229 stream = fopen("/tmp/app.txt", "w");
1230 if (!stream) {
1232 fprintf(stderr,
1233 "Error: Cannot open /tmp/app.txt for writing\n");
1234 return EXIT_FAILURE;
1235 }
1236 if (fprintf(stream, "0123456789") != 10) {
1238 fclose(stream);
1239 fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
1240 return EXIT_FAILURE;
1241 }
1242 tracepoint(my_provider, big_event, 35, "hello tracepoint",
1244 stream, -3.14, array_of_ints);
1245 fclose(stream);
1246 app_struct.b = argc;
1247 app_struct.c = "[the string]";
1248 tracepoint(my_provider, event_instance1, 23, &app_struct);
1249 app_struct.b = argc * 5;
1250 app_struct.c = "[other string]";
1251 tracepoint(my_provider, event_instance2, 17, &app_struct);
1252 app_struct.b = 23;
1253 app_struct.c = "nothing";
1254 tracepoint(my_provider, event_instance3, -52, &app_struct);
1255 return EXIT_SUCCESS;
1257 }
1258
1260 LTTNG_HOME
1261 Alternative user’s home directory. This variable is useful when the
1262 user running the instrumented application has a non-writable home
1263 directory.
1264 Unix sockets used for the communication between liblttng-ust and
1266 the LTTng session and consumer daemons (part of the LTTng-tools
1267 project) are located in a specific directory under $LTTNG_HOME (or
1268 $HOME if $LTTNG_HOME is not set).
1269 LTTNG_UST_ALLOW_BLOCKING
1271 If set, allow the application to retry event tracing when there’s
1272 no space left for the event record in the sub-buffer, therefore
1273 effectively blocking the application until space is made available
1274 or the configured timeout is reached.
1275 To allow an application to block during tracing, you also need to
1277 specify a blocking timeout when you create a channel with the
1278 --blocking-timeout option of the lttng-enable-channel(1) command.
1279 This option can be useful in workloads generating very large trace
1281 data throughput, where blocking the application is an acceptable
1282 trade-off to prevent discarding event records.
1283 Warning
1285 Setting this environment variable may significantly affect
1286 application timings.
1287 LTTNG_UST_CLOCK_PLUGIN
1289 Path to the shared object which acts as the clock override plugin.
1290 An example of such a plugin can be found in the LTTng-UST
1291 documentation under examples/clock-override
1292 <https://github.com/lttng/lttng-
1293 ust/tree/v2.12.0-rc3/doc/examples/clock-override>.
1294 LTTNG_UST_DEBUG
1296 If set, enable liblttng-ust's debug and error output.
1297 LTTNG_UST_GETCPU_PLUGIN
1299 Path to the shared object which acts as the getcpu() override
1300 plugin. An example of such a plugin can be found in the LTTng-UST
1301 documentation under examples/getcpu-override
1302 <https://github.com/lttng/lttng-
1303 ust/tree/v2.12.0-rc3/doc/examples/getcpu-override>.
1304 LTTNG_UST_REGISTER_TIMEOUT
1306 Waiting time for the registration done session daemon command
1307 before proceeding to execute the main program (milliseconds).
1308 The value 0 means do not wait. The value -1 means wait forever.
1310 Setting this environment variable to 0 is recommended for
1311 applications with time constraints on the process startup time.
1312 Default: 3000.
1314 LTTNG_UST_WITHOUT_BADDR_STATEDUMP
1316 If set, prevents liblttng-ust from performing a base address state
1317 dump (see the LTTng-UST state dump section above).
1318 LTTNG_UST_WITHOUT_PROCNAME_STATEDUMP
1320 If set, prevents liblttng-ust from performing a procname state dump
1321 (see the LTTng-UST state dump section above).
1322
1324 If you encounter any issue or usability problem, please report it on
1325 the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>.
1326
1328 · LTTng project website <http://lttng.org>
1329 · LTTng documentation <http://lttng.org/docs>
1331 · Git repositories <http://git.lttng.org>
1333 · GitHub organization <http://github.com/lttng>
1335 · Continuous integration <http://ci.lttng.org/>
1337 · Mailing list <http://lists.lttng.org> for support and development:
1339 lttng-dev@lists.lttng.org
1340 · IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
1342
1344 This library is part of the LTTng-UST project.
1345 This library is distributed under the GNU Lesser General Public
1347 License, version 2.1 <http://www.gnu.org/licenses/old-
1348 licenses/lgpl-2.1.en.html>. See the COPYING
1349 <https://github.com/lttng/lttng-ust/blob/v2.12.0-rc3/COPYING> file for
1350 more details.
1351
1353 Thanks to Ericsson for funding this work, providing real-life use
1354 cases, and testing.
1355 Special thanks to Michel Dagenais and the DORSAL laboratory
1357 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
1358 the LTTng journey.
1359
1361 LTTng-UST was originally written by Mathieu Desnoyers, with additional
1362 contributions from various other people. It is currently maintained by
1363 Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
1364
1366 tracef(3), tracelog(3), lttng-gen-tp(1), lttng-ust-dl(3), lttng-ust-
1367 cyg-profile(3), lttng(1), lttng-enable-event(1), lttng-list(1), lttng-
1368 add-context(1), babeltrace(1), dlopen(3), ld.so(8)
1369LTTng 2.12.0-rc3 03/27/2020 LTTNG-UST(3)