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 process namespace.
745 vtid
747 Virtual thread ID: thread ID as seen from the point of view of the
748 process namespace.
749 LTTng-UST state dump
751 If an application that uses liblttng-ust becomes part of a tracing
752 session, information about its currently loaded shared objects, their
753 build IDs, and their debug link information are emitted as events by
754 the tracer.
755 The following LTTng-UST state dump events exist and must be enabled to
757 record application state dumps. Note that, during the state dump phase,
758 LTTng-UST can also emit shared library load/unload events (see Shared
759 library load/unload tracking below).
760 lttng_ust_statedump:start
762 Emitted when the state dump begins.
763 This event has no fields.
765 lttng_ust_statedump:end
767 Emitted when the state dump ends. Once this event is emitted, it is
768 guaranteed that, for a given process, the state dump is complete.
769 This event has no fields.
771 lttng_ust_statedump:bin_info
773 Emitted when information about a currently loaded executable or
774 shared object is found.
775 Fields:
777 ┌───────────────┬────────────────────────────────┐
779 │Field name │ Description │
780 ├───────────────┼────────────────────────────────┤
781 │baddr │ Base address of loaded │
782 │ │ executable. │
783 ├───────────────┼────────────────────────────────┤
784 │memsz │ Size of loaded executable │
785 │ │ in memory. │
786 ├───────────────┼────────────────────────────────┤
787 │path │ Path to loaded executable │
788 │ │ file. │
789 ├───────────────┼────────────────────────────────┤
790 │is_pic │ Whether or not the │
791 │ │ executable is │
792 │ │ position-independent code. │
793 ├───────────────┼────────────────────────────────┤
794 │has_build_id │ Whether or not the │
795 │ │ executable has a build ID. │
796 │ │ If this field is 1, you │
797 │ │ can expect that an │
798 │ │ lttng_ust_statedump:build_id │
799 │ │ event record follows this │
800 │ │ one (not necessarily │
801 │ │ immediately after). │
802 ├───────────────┼────────────────────────────────┤
803 │has_debug_link │ Whether or not the │
804 │ │ executable has debug link │
805 │ │ information. If this field │
806 │ │ is 1, you can expect that an │
807 │ │ lttng_ust_statedump:debug_link │
808 │ │ event record follows this │
809 │ │ one (not necessarily │
810 │ │ immediately after). │
811 └───────────────┴────────────────────────────────┘
812 lttng_ust_statedump:build_id
814 Emitted when a build ID is found in a currently loaded shared
815 library. See Debugging Information in Separate Files
816 <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
817 Files.html> for more information about build IDs.
818 Fields:
820 ┌───────────┬────────────────────────┐
822 │Field name │ Description │
823 ├───────────┼────────────────────────┤
824 │baddr │ Base address of loaded │
825 │ │ library. │
826 ├───────────┼────────────────────────┤
827 │build_id │ Build ID. │
828 └───────────┴────────────────────────┘
829 lttng_ust_statedump:debug_link
831 Emitted when debug link information is found in a currently loaded
832 shared library. See Debugging Information in Separate Files
833 <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
834 Files.html> for more information about debug links.
835 Fields:
837 ┌───────────┬────────────────────────┐
839 │Field name │ Description │
840 ├───────────┼────────────────────────┤
841 │baddr │ Base address of loaded │
842 │ │ library. │
843 ├───────────┼────────────────────────┤
844 │crc │ Debug link file’s CRC. │
845 ├───────────┼────────────────────────┤
846 │filename │ Debug link file name. │
847 └───────────┴────────────────────────┘
848 Shared library load/unload tracking
850 The LTTng-UST state dump and the LTTng-UST helper library to instrument
851 the dynamic linker (see liblttng-ust-dl(3)) can emit shared library
852 load/unload tracking events.
853 The following shared library load/unload tracking events exist and must
855 be enabled to track the loading and unloading of shared libraries:
856 lttng_ust_lib:load
858 Emitted when a shared library (shared object) is loaded.
859 Fields:
861 ┌───────────────┬────────────────────────────┐
863 │Field name │ Description │
864 ├───────────────┼────────────────────────────┤
865 │baddr │ Base address of loaded │
866 │ │ library. │
867 ├───────────────┼────────────────────────────┤
868 │memsz │ Size of loaded library in │
869 │ │ memory. │
870 ├───────────────┼────────────────────────────┤
871 │path │ Path to loaded library │
872 │ │ file. │
873 ├───────────────┼────────────────────────────┤
874 │has_build_id │ Whether or not the library │
875 │ │ has a build ID. If this │
876 │ │ field is 1, you can expect │
877 │ │ that an │
878 │ │ lttng_ust_lib:build_id │
879 │ │ event record follows this │
880 │ │ one (not necessarily │
881 │ │ immediately after). │
882 ├───────────────┼────────────────────────────┤
883 │has_debug_link │ Whether or not the library │
884 │ │ has debug link │
885 │ │ information. If this field │
886 │ │ is 1, you can expect that │
887 │ │ an │
888 │ │ lttng_ust_lib:debug_link │
889 │ │ event record follows this │
890 │ │ one (not necessarily │
891 │ │ immediately after). │
892 └───────────────┴────────────────────────────┘
893 lttng_ust_lib:unload
895 Emitted when a shared library (shared object) is unloaded.
896 Fields:
898 ┌───────────┬──────────────────────────┐
900 │Field name │ Description │
901 ├───────────┼──────────────────────────┤
902 │baddr │ Base address of unloaded │
903 │ │ library. │
904 └───────────┴──────────────────────────┘
905 lttng_ust_lib:build_id
907 Emitted when a build ID is found in a loaded shared library (shared
908 object). See Debugging Information in Separate Files
909 <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
910 Files.html> for more information about build IDs.
911 Fields:
913 ┌───────────┬────────────────────────┐
915 │Field name │ Description │
916 ├───────────┼────────────────────────┤
917 │baddr │ Base address of loaded │
918 │ │ library. │
919 ├───────────┼────────────────────────┤
920 │build_id │ Build ID. │
921 └───────────┴────────────────────────┘
922 lttng_ust_lib:debug_link
924 Emitted when debug link information is found in a loaded shared
925 library (shared object). See Debugging Information in Separate
926 Files <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
927 Files.html> for more information about debug links.
928 Fields:
930 ┌───────────┬────────────────────────┐
932 │Field name │ Description │
933 ├───────────┼────────────────────────┤
934 │baddr │ Base address of loaded │
935 │ │ library. │
936 ├───────────┼────────────────────────┤
937 │crc │ Debug link file’s CRC. │
938 ├───────────┼────────────────────────┤
939 │filename │ Debug link file name. │
940 └───────────┴────────────────────────┘
941 Detect if LTTng-UST is loaded
943 To detect if liblttng-ust is loaded from an application:
944 1. Define the lttng_ust_loaded weak symbol globally:
946 int lttng_ust_loaded __attribute__((weak));
948 This weak symbol is set by the constructor of liblttng-ust.
950 2. Test lttng_ust_loaded where needed:
952 /* ... */
954 if (lttng_ust_loaded) {
956 /* LTTng-UST is loaded */
957 } else {
958 /* LTTng-UST is NOT loaded */
959 }
960 /* ... */
962
964 Note
965 A few examples are available in the doc/examples
966 <https://github.com/lttng/lttng-ust/tree/master/doc/examples>
967 directory of LTTng-UST’s source tree.
968 This example shows all the features documented in the previous
970 sections. The static linking method is chosen here to link the
971 application with the tracepoint provider.
972 You can compile the source files and link them together statically like
974 this:
975 $ cc -c -I. tp.c
977 $ cc -c app.c
978 $ cc -o app tp.o app.o -llttng-ust -ldl
979 Using the lttng(1) tool, create an LTTng tracing session, enable all
981 the events of this tracepoint provider, and start tracing:
982 $ lttng create my-session
984 $ lttng enable-event --userspace 'my_provider:*'
985 $ lttng start
986 You may also enable specific events:
988 $ lttng enable-event --userspace my_provider:big_event
990 $ lttng enable-event --userspace my_provider:event_instance2
991 Run the application:
993 $ ./app some arguments
995 Stop the current tracing session and inspect the recorded events:
997 $ lttng stop
999 $ lttng view
1000 Tracepoint provider header file
1002 tp.h:
1003 #undef TRACEPOINT_PROVIDER
1005 #define TRACEPOINT_PROVIDER my_provider
1006 #undef TRACEPOINT_INCLUDE
1008 #define TRACEPOINT_INCLUDE "./tp.h"
1009 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
1011 #define _TP_H
1012 #include <lttng/tracepoint.h>
1014 #include <stdio.h>
1015 #include "app.h"
1017 TRACEPOINT_EVENT(
1019 my_provider,
1020 simple_event,
1021 TP_ARGS(
1022 int, my_integer_arg,
1023 const char *, my_string_arg
1024 ),
1025 TP_FIELDS(
1026 ctf_string(argc, my_string_arg)
1027 ctf_integer(int, argv, my_integer_arg)
1028 )
1029 )
1030 TRACEPOINT_ENUM(
1032 my_provider,
1033 my_enum,
1034 TP_ENUM_VALUES(
1035 ctf_enum_value("ZERO", 0)
1036 ctf_enum_value("ONE", 1)
1037 ctf_enum_value("TWO", 2)
1038 ctf_enum_range("A RANGE", 52, 125)
1039 ctf_enum_value("ONE THOUSAND", 1000)
1040 )
1041 )
1042 TRACEPOINT_EVENT(
1044 my_provider,
1045 big_event,
1046 TP_ARGS(
1047 int, my_integer_arg,
1048 const char *, my_string_arg,
1049 FILE *, stream,
1050 double, flt_arg,
1051 int *, array_arg
1052 ),
1053 TP_FIELDS(
1054 ctf_integer(int, int_field1, my_integer_arg * 2)
1055 ctf_integer_hex(long int, stream_pos, ftell(stream))
1056 ctf_float(double, float_field, flt_arg)
1057 ctf_string(string_field, my_string_arg)
1058 ctf_array(int, array_field, array_arg, 7)
1059 ctf_array_text(char, array_text_field, array_arg, 5)
1060 ctf_sequence(int, seq_field, array_arg, int,
1061 my_integer_arg / 10)
1062 ctf_sequence_text(char, seq_text_field, array_arg,
1063 int, my_integer_arg / 5)
1064 ctf_enum(my_provider, my_enum, int,
1065 enum_field, array_arg[1])
1066 )
1067 )
1068 TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING)
1070 TRACEPOINT_EVENT_CLASS(
1072 my_provider,
1073 my_tracepoint_class,
1074 TP_ARGS(
1075 int, my_integer_arg,
1076 struct app_struct *, app_struct_arg
1077 ),
1078 TP_FIELDS(
1079 ctf_integer(int, a, my_integer_arg)
1080 ctf_integer(unsigned long, b, app_struct_arg->b)
1081 ctf_string(c, app_struct_arg->c)
1082 )
1083 )
1084 TRACEPOINT_EVENT_INSTANCE(
1086 my_provider,
1087 my_tracepoint_class,
1088 event_instance1,
1089 TP_ARGS(
1090 int, my_integer_arg,
1091 struct app_struct *, app_struct_arg
1092 )
1093 )
1094 TRACEPOINT_EVENT_INSTANCE(
1096 my_provider,
1097 my_tracepoint_class,
1098 event_instance2,
1099 TP_ARGS(
1100 int, my_integer_arg,
1101 struct app_struct *, app_struct_arg
1102 )
1103 )
1104 TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO)
1106 TRACEPOINT_EVENT_INSTANCE(
1108 my_provider,
1109 my_tracepoint_class,
1110 event_instance3,
1111 TP_ARGS(
1112 int, my_integer_arg,
1113 struct app_struct *, app_struct_arg
1114 )
1115 )
1116 #endif /* _TP_H */
1118 #include <lttng/tracepoint-event.h>
1120 Tracepoint provider source file
1122 tp.c:
1123 #define TRACEPOINT_CREATE_PROBES
1125 #define TRACEPOINT_DEFINE
1126 #include "tp.h"
1128 Application header file
1130 app.h:
1131 #ifndef _APP_H
1133 #define _APP_H
1134 struct app_struct {
1136 unsigned long b;
1137 const char *c;
1138 double d;
1139 };
1140 #endif /* _APP_H */
1142 Application source file
1144 app.c:
1145 #include <stdlib.h>
1147 #include <stdio.h>
1148 #include "tp.h"
1150 #include "app.h"
1151 static int array_of_ints[] = {
1153 100, -35, 1, 23, 14, -6, 28, 1001, -3000,
1154 };
1155 int main(int argc, char* argv[])
1157 {
1158 FILE *stream;
1159 struct app_struct app_struct;
1160 tracepoint(my_provider, simple_event, argc, argv[0]);
1162 stream = fopen("/tmp/app.txt", "w");
1163 if (!stream) {
1165 fprintf(stderr,
1166 "Error: Cannot open /tmp/app.txt for writing\n");
1167 return EXIT_FAILURE;
1168 }
1169 if (fprintf(stream, "0123456789") != 10) {
1171 fclose(stream);
1172 fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
1173 return EXIT_FAILURE;
1174 }
1175 tracepoint(my_provider, big_event, 35, "hello tracepoint",
1177 stream, -3.14, array_of_ints);
1178 fclose(stream);
1179 app_struct.b = argc;
1180 app_struct.c = "[the string]";
1181 tracepoint(my_provider, event_instance1, 23, &app_struct);
1182 app_struct.b = argc * 5;
1183 app_struct.c = "[other string]";
1184 tracepoint(my_provider, event_instance2, 17, &app_struct);
1185 app_struct.b = 23;
1186 app_struct.c = "nothing";
1187 tracepoint(my_provider, event_instance3, -52, &app_struct);
1188 return EXIT_SUCCESS;
1190 }
1191
1193 LTTNG_HOME
1194 Alternative user’s home directory. This variable is useful when the
1195 user running the instrumented application has a non-writable home
1196 directory.
1197 Unix sockets used for the communication between liblttng-ust and
1199 the LTTng session and consumer daemons (part of the LTTng-tools
1200 project) are located in a specific directory under $LTTNG_HOME (or
1201 $HOME if $LTTNG_HOME is not set).
1202 LTTNG_UST_ALLOW_BLOCKING
1204 If set, allow the application to retry event tracing when there’s
1205 no space left for the event record in the sub-buffer, therefore
1206 effectively blocking the application until space is made available
1207 or the configured timeout is reached.
1208 To allow an application to block during tracing, you also need to
1210 specify a blocking timeout when you create a channel with the
1211 --blocking-timeout option of the lttng-enable-channel(1) command.
1212 This option can be useful in workloads generating very large trace
1214 data throughput, where blocking the application is an acceptable
1215 trade-off to prevent discarding event records.
1216 Warning
1218 Setting this environment variable may significantly affect
1219 application timings.
1220 LTTNG_UST_CLOCK_PLUGIN
1222 Path to the shared object which acts as the clock override plugin.
1223 An example of such a plugin can be found in the LTTng-UST
1224 documentation under examples/clock-override
1225 <https://github.com/lttng/lttng-ust/tree/master/doc/examples/clock-
1226 override>.
1227 LTTNG_UST_DEBUG
1229 If set, enable liblttng-ust's debug and error output.
1230 LTTNG_UST_GETCPU_PLUGIN
1232 Path to the shared object which acts as the getcpu() override
1233 plugin. An example of such a plugin can be found in the LTTng-UST
1234 documentation under examples/getcpu-override
1235 <https://github.com/lttng/lttng-
1236 ust/tree/master/doc/examples/getcpu-override>.
1237 LTTNG_UST_REGISTER_TIMEOUT
1239 Waiting time for the registration done session daemon command
1240 before proceeding to execute the main program (milliseconds).
1241 The value 0 means do not wait. The value -1 means wait forever.
1243 Setting this environment variable to 0 is recommended for
1244 applications with time constraints on the process startup time.
1245 Default: 3000.
1247 LTTNG_UST_WITHOUT_BADDR_STATEDUMP
1249 If set, prevents liblttng-ust from performing a base address state
1250 dump (see the LTTng-UST state dump section above).
1251
1253 If you encounter any issue or usability problem, please report it on
1254 the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>.
1255
1257 · LTTng project website <http://lttng.org>
1258 · LTTng documentation <http://lttng.org/docs>
1260 · Git repositories <http://git.lttng.org>
1262 · GitHub organization <http://github.com/lttng>
1264 · Continuous integration <http://ci.lttng.org/>
1266 · Mailing list <http://lists.lttng.org> for support and development:
1268 lttng-dev@lists.lttng.org
1269 · IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
1271
1273 This library is part of the LTTng-UST project.
1274 This library is distributed under the GNU Lesser General Public
1276 License, version 2.1 <http://www.gnu.org/licenses/old-
1277 licenses/lgpl-2.1.en.html>. See the COPYING
1278 <https://github.com/lttng/lttng-ust/blob/master/COPYING> file for more
1279 details.
1280
1282 Thanks to Ericsson for funding this work, providing real-life use
1283 cases, and testing.
1284 Special thanks to Michel Dagenais and the DORSAL laboratory
1286 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
1287 the LTTng journey.
1288
1290 LTTng-UST was originally written by Mathieu Desnoyers, with additional
1291 contributions from various other people. It is currently maintained by
1292 Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
1293
1295 tracef(3), tracelog(3), lttng-gen-tp(1), lttng-ust-dl(3), lttng-ust-
1296 cyg-profile(3), lttng(1), lttng-enable-event(1), lttng-list(1), lttng-
1297 add-context(1), babeltrace(1), dlopen(3), ld.so(8)
1298LTTng 2.10.4 05/24/2019 LTTNG-UST(3)