8 lttng-ust - LTTng user space tracing
14 *#include <lttng/tracepoint.h>*
17 #define *TRACEPOINT_ENUM*('prov_name', 'enum_name', 'mappings')
18 #define *TRACEPOINT_EVENT*('prov_name', 't_name', 'args', 'fields')
19 #define *TRACEPOINT_EVENT_CLASS*('prov_name', 'class_name', 'args', 'fields')
20 #define *TRACEPOINT_EVENT_INSTANCE*('prov_name', 'class_name', 't_name', 'args')
21 #define *TRACEPOINT_LOGLEVEL*('prov_name', 't_name', 'level')
22 #define *ctf_array*('int_type', 'field_name', 'expr', 'count')
23 #define *ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count')
24 #define *ctf_array_hex*('int_type', 'field_name', 'expr', 'count')
25 #define *ctf_array_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
26 #define *ctf_array_network*('int_type', 'field_name', 'expr', 'count')
27 #define *ctf_array_network_nowrite*('int_type', 'field_name', 'expr', 'count')
28 #define *ctf_array_network_hex*('int_type', 'field_name', 'expr', 'count')
29 #define *ctf_array_network_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
30 #define *ctf_array_text*(char, 'field_name', 'expr', 'count')
31 #define *ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count')
32 #define *ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
33 #define *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type', 'field_name',
35 #define *ctf_enum_value*('label', 'value')
36 #define *ctf_enum_range*('label', 'start', 'end')
37 #define *ctf_float*('float_type', 'field_name', 'expr')
38 #define *ctf_float_nowrite*('float_type', 'field_name', 'expr')
39 #define *ctf_integer*('int_type', 'field_name', 'expr')
40 #define *ctf_integer_hex*('int_type', 'field_name', 'expr')
41 #define *ctf_integer_network*('int_type', 'field_name', 'expr')
42 #define *ctf_integer_network_hex*('int_type', 'field_name', 'expr')
43 #define *ctf_integer_nowrite*('int_type', 'field_name', 'expr')
44 #define *ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
45 #define *ctf_sequence_nowrite*('int_type', 'field_name', 'expr', 'len_type',
47 #define *ctf_sequence_hex*('int_type', 'field_name', 'expr', 'len_type',
49 #define *ctf_sequence_nowrite_hex*('int_type', 'field_name', 'expr', 'len_type',
51 #define *ctf_sequence_network*('int_type', 'field_name', 'expr', 'len_type',
53 #define *ctf_sequence_network_nowrite*('int_type', 'field_name', 'expr',
54 'len_type', 'len_expr')
55 #define *ctf_sequence_network_hex*('int_type', 'field_name', 'expr', 'len_type',
57 #define *ctf_sequence_network_nowrite_hex*('int_type', 'field_name', 'expr',
58 'len_type', 'len_expr')
59 #define *ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr')
60 #define *ctf_sequence_text_nowrite*(char, 'field_name', 'expr', 'len_type',
62 #define *ctf_string*('field_name', 'expr')
63 #define *ctf_string_nowrite*('field_name', 'expr')
64 #define *do_tracepoint*('prov_name', 't_name', ...)
65 #define *tracepoint*('prov_name', 't_name', ...)
66 #define *tracepoint_enabled*('prov_name', 't_name')
68 Link with `-llttng-ust -ldl`, following this man page.
73 The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
74 source software package used for correlated tracing of the Linux kernel,
75 user applications, and user libraries.
77 LTTng-UST is the user space tracing component of the LTTng project. It
78 is a port to user space of the low-overhead tracing capabilities of the
79 LTTng Linux kernel tracer. The `liblttng-ust` library is used to trace
80 user applications and libraries.
82 NOTE: This man page is about the `liblttng-ust` library. The LTTng-UST
83 project also provides Java and Python packages to trace applications
84 written in those languages. How to instrument and trace Java and Python
85 applications is documented in
86 http://lttng.org/docs/[the online LTTng documentation].
88 There are three ways to use `liblttng-ust`:
90 * Using the man:tracef(3) API, which is similar to man:printf(3).
91 * Using the man:tracelog(3) API, which is man:tracef(3) with
92 a log level parameter.
93 * Defining your own tracepoints. See the
94 <<creating-tp,Creating a tracepoint provider>> section below.
98 Creating a tracepoint provider
99 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
100 Creating a tracepoint provider is the first step of using
101 `liblttng-ust`. The next steps are:
103 * <<tracepoint,Instrumenting your application with `tracepoint()` calls>>
104 * Building your application with LTTng-UST support, either
105 <<build-static,statically>> or <<build-dynamic,dynamically>>.
107 A *tracepoint provider* is a compiled object containing the event
108 probes corresponding to your custom tracepoint definitions. A tracepoint
109 provider contains the code to get the size of an event and to serialize
110 it, amongst other things.
112 To create a tracepoint provider, start with the following
113 _tracepoint provider header_ template:
115 ------------------------------------------------------------------------
116 #undef TRACEPOINT_PROVIDER
117 #define TRACEPOINT_PROVIDER my_provider
119 #undef TRACEPOINT_INCLUDE
120 #define TRACEPOINT_INCLUDE "./tp.h"
122 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
125 #include <lttng/tracepoint.h>
128 * TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
129 * TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(),
130 * and `TRACEPOINT_ENUM()` are used here.
135 #include <lttng/tracepoint-event.h>
136 ------------------------------------------------------------------------
138 In this template, the tracepoint provider is named `my_provider`
139 (`TRACEPOINT_PROVIDER` definition). The file needs to bear the
140 name of the `TRACEPOINT_INCLUDE` definition (`tp.h` in this case).
141 Between `#include <lttng/tracepoint.h>` and `#endif` go
142 the invocations of the <<tracepoint-event,`TRACEPOINT_EVENT()`>>,
143 <<tracepoint-event-class,`TRACEPOINT_EVENT_CLASS()`>>,
144 <<tracepoint-event-class,`TRACEPOINT_EVENT_INSTANCE()`>>,
145 <<tracepoint-loglevel,`TRACEPOINT_LOGLEVEL()`>>, and
146 <<tracepoint-enum,`TRACEPOINT_ENUM()`>> macros.
148 NOTE: You can avoid writing the prologue and epilogue boilerplate in the
149 template file above by using the man:lttng-gen-tp(1) tool shipped with
152 The tracepoint provider header file needs to be included in a source
153 file which looks like this:
155 ------------------------------------------------------------------------
156 #define TRACEPOINT_CREATE_PROBES
159 ------------------------------------------------------------------------
161 Together, those two files (let's call them `tp.h` and `tp.c`) form the
162 tracepoint provider sources, ready to be compiled.
164 You can create multiple tracepoint providers to be used in a single
165 application, but each one must have its own header file.
167 The <<tracepoint-event,`TRACEPOINT_EVENT()` usage>> section below
168 shows how to use the `TRACEPOINT_EVENT()` macro to define the actual
169 tracepoints in the tracepoint provider header file.
171 See the <<example,EXAMPLE>> section below for a complete example.
175 `TRACEPOINT_EVENT()` usage
176 ~~~~~~~~~~~~~~~~~~~~~~~~~~
177 The `TRACEPOINT_EVENT()` macro is used in a template provider
178 header file (see the <<creating-tp,Creating a tracepoint provider>>
179 section above) to define LTTng-UST tracepoints.
181 The `TRACEPOINT_EVENT()` usage template is as follows:
183 ------------------------------------------------------------------------
185 /* Tracepoint provider name */
188 /* Tracepoint/event name */
191 /* List of tracepoint arguments (input) */
196 /* List of fields of eventual event (output) */
201 ------------------------------------------------------------------------
203 The `TP_ARGS()` macro contains the input arguments of the tracepoint.
204 Those arguments can be used in the argument expressions of the output
205 fields defined in `TP_FIELDS()`.
207 The format of the `TP_ARGS()` parameters is: C type, then argument name;
208 repeat as needed, up to ten times. For example:
210 ------------------------------------------------------------------------
213 const char *, my_string,
216 struct my_data *, my_data
218 ------------------------------------------------------------------------
220 The `TP_FIELDS()` macro contains the output fields of the tracepoint,
221 that is, the actual data that can be recorded in the payload of an
222 event emitted by this tracepoint.
224 The `TP_FIELDS()` macro contains a list of `ctf_*()` macros
225 :not: separated by commas. The available macros are documented in the
226 <<ctf-macros,Available `ctf_*()` field type macros>> section below.
230 Available `ctf_*()` field type macros
231 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
232 This section documents the available `ctf_*()` macros that can be
233 inserted in the `TP_FIELDS()` macro of the
234 <<tracepoint-event,`TRACEPOINT_EVENT()` macro>>.
236 Standard integer, displayed in base 10:
239 *ctf_integer*('int_type', 'field_name', 'expr')
240 *ctf_integer_nowrite*('int_type', 'field_name', 'expr')
242 Standard integer, displayed in base 16:
245 *ctf_integer_hex*('int_type', 'field_name', 'expr')
247 Integer in network byte order (big endian), displayed in base 10:
250 *ctf_integer_network*('int_type', 'field_name', 'expr')
252 Integer in network byte order, displayed in base 16:
255 *ctf_integer_network_hex*('int_type', 'field_name', 'expr')
257 Floating point number:
260 *ctf_float*('float_type', 'field_name', 'expr')
261 *ctf_float_nowrite*('float_type', 'field_name', 'expr')
263 Null-terminated string:
266 *ctf_string*('field_name', 'expr')
267 *ctf_string_nowrite*('field_name', 'expr')
269 Statically-sized array of integers (`_hex` versions displayed in
270 hexadecimal, `_network` versions in network byte order):
273 *ctf_array*('int_type', 'field_name', 'expr', 'count')
274 *ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count')
275 *ctf_array_hex*('int_type', 'field_name', 'expr', 'count')
276 *ctf_array_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
277 *ctf_array_network*('int_type', 'field_name', 'expr', 'count')
278 *ctf_array_network_nowrite*('int_type', 'field_name', 'expr', 'count')
279 *ctf_array_network_hex*('int_type', 'field_name', 'expr', 'count')
280 *ctf_array_network_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
282 Statically-sized array, printed as text; no need to be null-terminated:
285 *ctf_array_text*(char, 'field_name', 'expr', 'count')
286 *ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count')
288 Dynamically-sized array of integers (`_hex` versions displayed in
289 hexadecimal, `_network` versions in network byte order):
292 *ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
293 *ctf_sequence_nowrite*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
294 *ctf_sequence_hex*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
295 *ctf_sequence_nowrite_hex*('int_type', 'field_name', 'expr', 'len_type',
297 *ctf_sequence_network*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
298 *ctf_sequence_network_nowrite*('int_type', 'field_name', 'expr', 'len_type',
300 *ctf_sequence_network_hex*('int_type', 'field_name', 'expr', 'len_type',
302 *ctf_sequence_network_nowrite_hex*('int_type', 'field_name', 'expr',
303 'len_type', 'len_expr')
305 Dynamically-sized array, displayed as text; no need to be null-terminated:
308 *ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr')
309 *ctf_sequence_text_nowrite*(char, 'field_name', 'expr', 'len_type', 'len_expr')
311 Enumeration. The enumeration field must be defined before using this
312 macro with the `TRACEPOINT_ENUM()` macro. See the
313 <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more
317 *ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
318 *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
323 Number of elements in array/sequence. This must be known at
327 Name of an enumeration field previously defined with the
328 `TRACEPOINT_ENUM()` macro. See the
329 <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more
333 C expression resulting in the field's value. This expression can
334 use one or more arguments passed to the tracepoint. The arguments
335 of a given tracepoint are defined in the `TP_ARGS()` macro (see
336 the <<creating-tp,Creating a tracepoint provider>> section above).
339 Event field name (C identifier syntax, :not: a literal string).
342 Float C type (`float` or `double`). The size of this type determines
343 the size of the floating point number field.
346 Integer C type. The size of this type determines the size of the
347 integer/enumeration field.
350 C expression resulting in the sequence's length. This expression
351 can use one or more arguments passed to the tracepoint.
354 Unsigned integer C type of sequence's length.
357 Tracepoint provider name. This must be the same as the tracepoint
358 provider name used in a previous field definition.
360 The `_nowrite` versions omit themselves from the recorded trace, but are
361 otherwise identical. Their primary purpose is to make some of the
362 event context available to the event filters without having to commit
363 the data to sub-buffers. See man:lttng-enable-event(1) to learn more
364 about dynamic event filtering.
366 See the <<example,EXAMPLE>> section below for a complete example.
370 `TRACEPOINT_ENUM()` usage
371 ~~~~~~~~~~~~~~~~~~~~~~~~~
372 An enumeration field is a list of mappings between an integers, or a
373 range of integers, and strings (sometimes called _labels_ or
374 _enumerators_). Enumeration fields can be used to have a more compact
375 trace when the possible values for a field are limited.
377 An enumeration field is defined with the `TRACEPOINT_ENUM()` macro:
379 ------------------------------------------------------------------------
381 /* Tracepoint provider name */
384 /* Enumeration name (unique in the whole tracepoint provider) */
387 /* Enumeration mappings */
392 ------------------------------------------------------------------------
394 `TP_ENUM_VALUES()` contains a list of enumeration mappings, :not:
395 separated by commas. Two macros can be used in the `TP_ENUM_VALUES()`:
396 `ctf_enum_value()` and `ctf_enum_range()`.
398 `ctf_enum_value()` is a single value mapping:
401 *ctf_enum_value*('label', 'value')
403 This macro maps the given 'label' string to the value 'value'.
405 `ctf_enum_range()` is a range mapping:
408 *ctf_enum_range*('label', 'start', 'end')
410 This macro maps the given 'label' string to the range of integers from
411 'start' to 'end', inclusively. Range mappings may overlap, but the
412 behaviour is implementation-defined: each trace reader handles
413 overlapping ranges as it wishes.
415 See the <<example,EXAMPLE>> section below for a complete example.
418 [[tracepoint-event-class]]
419 `TRACEPOINT_EVENT_CLASS()` usage
420 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
421 A *tracepoint class* is a class of tracepoints sharing the
422 same field types and names. A tracepoint instance is one instance of
423 such a declared tracepoint class, with its own event name.
425 LTTng-UST creates one event serialization function per tracepoint
426 class. Using `TRACEPOINT_EVENT()` creates one tracepoint class per
427 tracepoint definition, whereas using `TRACEPOINT_EVENT_CLASS()` and
428 `TRACEPOINT_EVENT_INSTANCE()` creates one tracepoint class, and one or
429 more tracepoint instances of this class. In other words, many
430 tracepoints can reuse the same serialization code. Reusing the same
431 code, when possible, can reduce cache pollution, thus improve
434 The `TRACEPOINT_EVENT_CLASS()` macro accepts the same parameters as
435 the `TRACEPOINT_EVENT()` macro, except that instead of an event name,
436 its second parameter is the _tracepoint class name_:
438 ------------------------------------------------------------------------
439 TRACEPOINT_EVENT_CLASS(
440 /* Tracepoint provider name */
443 /* Tracepoint class name */
446 /* List of tracepoint arguments (input) */
451 /* List of fields of eventual event (output) */
456 ------------------------------------------------------------------------
458 Once the tracepoint class is defined, you can create as many tracepoint
461 -------------------------------------------------------------------------
462 TRACEPOINT_EVENT_INSTANCE(
463 /* Tracepoint provider name */
466 /* Tracepoint class name */
469 /* Tracepoint/event name */
472 /* List of tracepoint arguments (input) */
477 ------------------------------------------------------------------------
479 As you can see, the `TRACEPOINT_EVENT_INSTANCE()` does not contain
480 the `TP_FIELDS()` macro, because they are defined at the
481 `TRACEPOINT_EVENT_CLASS()` level.
483 See the <<example,EXAMPLE>> section below for a complete example.
486 [[tracepoint-loglevel]]
487 `TRACEPOINT_LOGLEVEL()` usage
488 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
489 Optionally, a *log level* can be assigned to a defined tracepoint.
490 Assigning different levels of severity to tracepoints can be useful:
491 when controlling tracing sessions, you can choose to only enable
492 events falling into a specific log level range using the
493 nloption:--loglevel and nloption:--loglevel-only options of the
494 man:lttng-enable-event(1) command.
496 Log levels are assigned to tracepoints that are already defined using
497 the `TRACEPOINT_LOGLEVEL()` macro. The latter must be used after having
498 used `TRACEPOINT_EVENT()` or `TRACEPOINT_EVENT_INSTANCE()` for a given
499 tracepoint. The `TRACEPOINT_LOGLEVEL()` macro is used as follows:
501 ------------------------------------------------------------------------
503 /* Tracepoint provider name */
506 /* Tracepoint/event name */
512 ------------------------------------------------------------------------
514 The available log level definitions are:
516 include::log-levels.txt[]
518 See the <<example,EXAMPLE>> section below for a complete example.
522 Instrumenting your application
523 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
524 Once the tracepoint provider is created (see the
525 <<creating-tp,Creating a tracepoint provider>> section above), you can
526 instrument your application with the defined tracepoints thanks to the
527 `tracepoint()` macro:
530 #define *tracepoint*('prov_name', 't_name', ...)
535 Tracepoint provider name.
538 Tracepoint/event name.
541 Tracepoint arguments, if any.
543 Make sure to include the tracepoint provider header file anywhere you
544 use `tracepoint()` for this provider.
546 NOTE: Even though LTTng-UST supports `tracepoint()` call site duplicates
547 having the same provider and tracepoint names, it is recommended to use
548 a provider/tracepoint name pair only once within the application source
549 code to help map events back to their call sites when analyzing the
552 Sometimes, arguments to the tracepoint are expensive to compute (take
553 call stack, for example). To avoid the computation when the tracepoint
554 is disabled, you can use the `tracepoint_enabled()` and
555 `do_tracepoint()` macros:
558 #define *tracepoint_enabled*('prov_name', 't_name')
559 #define *do_tracepoint*('prov_name', 't_name', ...)
561 `tracepoint_enabled()` returns a non-zero value if the tracepoint
562 named 't_name' from the provider named 'prov_name' is enabled at
565 `do_tracepoint()` is like `tracepoint()`, except that it doesn't check
566 if the tracepoint is enabled. Using `tracepoint()` with
567 `tracepoint_enabled()` is dangerous since `tracepoint()` also contains
568 the `tracepoint_enabled()` check, thus a race condition is possible
571 ------------------------------------------------------------------------
572 if (tracepoint_enabled(my_provider, my_tracepoint)) {
573 stuff = prepare_stuff();
576 tracepoint(my_provider, my_tracepoint, stuff);
577 ------------------------------------------------------------------------
579 If the tracepoint is enabled after the condition, then `stuff` is not
580 prepared: the emitted event will either contain wrong data, or the
581 whole application could crash (segmentation fault, for example).
583 NOTE: Neither `tracepoint_enabled()` nor `do_tracepoint()` have
584 a `STAP_PROBEV()` call, so if you need it, you should emit this call
589 Statically linking the tracepoint provider
590 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
591 With the static linking method, compiled tracepoint providers are copied
592 into the target application.
594 Define `TRACEPOINT_DEFINE` definition below the
595 `TRACEPOINT_CREATE_PROBES` definition in the tracepoint provider
598 ------------------------------------------------------------------------
599 #define TRACEPOINT_CREATE_PROBES
600 #define TRACEPOINT_DEFINE
603 ------------------------------------------------------------------------
605 Create the tracepoint provider object file:
612 NOTE: Although an application instrumented with LTTng-UST tracepoints
613 can be compiled with a C++ compiler, tracepoint probes should be
614 compiled with a C compiler.
616 At this point, you _can_ archive this tracepoint provider object file,
617 possibly with other object files of your application or with other
618 tracepoint provider object files, as a static library:
625 Using a static library does have the advantage of centralising the
626 tracepoint providers objects so they can be shared between multiple
627 applications. This way, when the tracepoint provider is modified, the
628 source code changes don't have to be patched into each application's
629 source code tree. The applications need to be relinked after each
630 change, but need not to be otherwise recompiled (unless the tracepoint
631 provider's API changes).
633 Then, link your application with this object file (or with the static
634 library containing it) and with `liblttng-ust` and `libdl`
635 (`libc` on a BSD system):
639 $ cc -o app tp.o app.o -llttng-ust -ldl
644 Dynamically loading the tracepoint provider
645 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
646 The second approach to package the tracepoint provider is to use the
647 dynamic loader: the library and its member functions are explicitly
648 sought, loaded at run time.
650 In this scenario, the tracepoint provider is compiled as a shared
653 The process to create the tracepoint provider shared object is pretty
654 much the same as the <<build-static,static linking method>>, except
657 * Since the tracepoint provider is not part of the application,
658 `TRACEPOINT_DEFINE` must be defined, for each tracepoint
659 provider, in exactly one source file of the
661 * `TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next
662 to `TRACEPOINT_DEFINE`
664 Regarding `TRACEPOINT_DEFINE` and `TRACEPOINT_PROBE_DYNAMIC_LINKAGE`,
665 the recommended practice is to use a separate C source file in your
666 application to define them, then include the tracepoint provider header
667 files afterwards. For example, as `tp-define.c`:
669 ------------------------------------------------------------------------
670 #define TRACEPOINT_DEFINE
671 #define TRACEPOINT_PROBE_DYNAMIC_LINKAGE
674 ------------------------------------------------------------------------
676 The tracepoint provider object file used to create the shared library is
677 built like it is using the static linking method, but with the
678 nloption:-fpic option:
682 $ cc -c -fpic -I. tp.c
685 It is then linked as a shared library like this:
689 $ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
692 This tracepoint provider shared object isn't linked with the user
693 application: it must be loaded manually. This is why the application is
694 built with no mention of this tracepoint provider, but still needs
699 $ cc -o app app.o tp-define.o -ldl
702 There are two ways to dynamically load the tracepoint provider shared
705 * Load it manually from the application using man:dlopen(3)
706 * Make the dynamic loader load it with the `LD_PRELOAD`
707 environment variable (see man:ld.so(8))
709 If the application does not dynamically load the tracepoint provider
710 shared object using one of the methods above, tracing is disabled for
711 this application, and the events are not listed in the output of
714 Note that it is not safe to use man:dlclose(3) on a tracepoint provider
715 shared object that is being actively used for tracing, due to a lack of
716 reference counting from LTTng-UST to the shared object.
718 For example, statically linking a tracepoint provider to a shared object
719 which is to be dynamically loaded by an application (a plugin, for
720 example) is not safe: the shared object, which contains the tracepoint
721 provider, could be dynamically closed (man:dlclose(3)) at any time by
724 To instrument a shared object, either:
726 * Statically link the tracepoint provider to the application, or
727 * Build the tracepoint provider as a shared object (following the
728 procedure shown in this section), and preload it when tracing is
729 needed using the `LD_PRELOAD` environment variable.
732 Using LTTng-UST with daemons
733 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
734 Some extra care is needed when using `liblttng-ust` with daemon
735 applications that call man:fork(2), man:clone(2), or BSD's man:rfork(2)
736 without a following man:exec(3) family system call. The library
737 `liblttng-ust-fork.so` needs to be preloaded before starting the
738 application with the `LD_PRELOAD` environment variable (see
741 To use `liblttng-ust` with a daemon application which closes file
742 descriptors that were not opened by it, preload the `liblttng-ust-fd.so`
743 library before you start the application. Typical use cases include
744 daemons closing all file descriptors after man:fork(2), and buggy
745 applications doing ``double-closes''.
750 Context information can be prepended by the LTTng-UST tracer before
751 each event, or before specific events.
753 Context fields can be added to specific channels using
754 man:lttng-add-context(1).
756 The following context fields are supported by LTTng-UST:
761 NOTE: This context field is always enabled, and it cannot be added
762 with man:lttng-add-context(1). Its main purpose is to be used for
763 dynamic event filtering. See man:lttng-enable-event(1) for more
764 information about event filtering.
767 Instruction pointer: enables recording the exact address from which
768 an event was emitted. This context field can be used to
769 reverse-lookup the source location that caused the event
772 `perf:thread:COUNTER`::
773 perf counter named 'COUNTER'. Use `lttng add-context --list` to
774 list the available perf counters.
776 Only available on IA-32 and x86-64 architectures.
778 `perf:thread:raw:rN:NAME`::
779 perf counter with raw ID 'N' and custom name 'NAME'. See
780 man:lttng-add-context(1) for more details.
783 POSIX thread identifier. Can be used on architectures where
784 `pthread_t` maps nicely to an `unsigned long` type.
787 Thread name, as set by man:exec(3) or man:prctl(2). It is
788 recommended that programs set their thread name with man:prctl(2)
789 before hitting the first tracepoint for that thread.
792 Virtual process ID: process ID as seen from the point of view of
793 the current man:pid_namespaces(7).
796 Virtual thread ID: thread ID as seen from the point of view of
797 the current man:pid_namespaces(7).
799 The following man:namespaces(7) context fields are supported by LTTng-UST:
802 Cgroup root directory namespace: inode number of the current
803 man:cgroup_namespaces(7) in the proc filesystem.
806 System V IPC, POSIX message queues namespace: inode number of the
807 current IPC namespace in the proc filesystem.
810 Mount points namespace: inode number of the current Mount namespace
811 in the proc filesystem.
814 Network devices, stacks, ports namespace: inode number of the
815 current Network namespace in the proc filesystem.
818 Process IDs namespace: inode number of the current
819 man:pid_namespaces(7) in the proc filesystem.
822 User and group IDs namespace: inode number of the current
823 man:user_namespaces(7) in the proc filesystem.
826 Hostname and NIS domain name namespace: inode number of the
827 current UTS namespace in the proc filesystem.
833 If an application that uses `liblttng-ust` becomes part of a tracing
834 session, information about its currently loaded shared objects, their
835 build IDs, and their debug link information are emitted as events
838 The following LTTng-UST state dump events exist and must be enabled
839 to record application state dumps. Note that, during the state dump
840 phase, LTTng-UST can also emit _shared library load/unload_ events
841 (see <<ust-lib,Shared library load/unload tracking>> below).
843 `lttng_ust_statedump:start`::
844 Emitted when the state dump begins.
846 This event has no fields.
848 `lttng_ust_statedump:end`::
849 Emitted when the state dump ends. Once this event is emitted, it
850 is guaranteed that, for a given process, the state dump is
853 This event has no fields.
855 `lttng_ust_statedump:bin_info`::
856 Emitted when information about a currently loaded executable or
857 shared object is found.
863 |Field name |Description
866 |Base address of loaded executable.
869 |Size of loaded executable in memory.
872 |Path to loaded executable file.
875 |Whether or not the executable is position-independent code.
878 |Whether or not the executable has a build ID. If this field is 1, you
879 can expect that an `lttng_ust_statedump:build_id` event record follows
880 this one (not necessarily immediately after).
883 |Whether or not the executable has debug link information. If this field
884 is 1, you can expect that an `lttng_ust_statedump:debug_link` event
885 record follows this one (not necessarily immediately after).
888 `lttng_ust_statedump:build_id`::
889 Emitted when a build ID is found in a currently loaded shared
891 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
892 for more information about build IDs.
898 |Field name |Description
901 |Base address of loaded library.
907 `lttng_ust_statedump:debug_link`::
908 Emitted when debug link information is found in a currently loaded
910 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
911 for more information about debug links.
917 |Field name |Description
920 |Base address of loaded library.
923 |Debug link file's CRC.
926 |Debug link file name.
931 Shared library load/unload tracking
932 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
933 The <<state-dump,LTTng-UST state dump>> and the LTTng-UST helper library
934 to instrument the dynamic linker (see man:liblttng-ust-dl(3)) can emit
935 **shared library load/unload tracking** events.
937 The following shared library load/unload tracking events exist and must
938 be enabled to track the loading and unloading of shared libraries:
940 `lttng_ust_lib:load`::
941 Emitted when a shared library (shared object) is loaded.
947 |Field name |Description
950 |Base address of loaded library.
953 |Size of loaded library in memory.
956 |Path to loaded library file.
959 |Whether or not the library has a build ID. If this field is 1, you
960 can expect that an `lttng_ust_lib:build_id` event record follows
961 this one (not necessarily immediately after).
964 |Whether or not the library has debug link information. If this field
965 is 1, you can expect that an `lttng_ust_lib:debug_link` event
966 record follows this one (not necessarily immediately after).
969 `lttng_ust_lib:unload`::
970 Emitted when a shared library (shared object) is unloaded.
976 |Field name |Description
979 |Base address of unloaded library.
982 `lttng_ust_lib:build_id`::
983 Emitted when a build ID is found in a loaded shared library (shared
985 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
986 for more information about build IDs.
992 |Field name |Description
995 |Base address of loaded library.
1001 `lttng_ust_lib:debug_link`::
1002 Emitted when debug link information is found in a loaded
1003 shared library (shared object). See
1004 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1005 for more information about debug links.
1011 |Field name |Description
1014 |Base address of loaded library.
1017 |Debug link file's CRC.
1020 |Debug link file name.
1024 Detect if LTTng-UST is loaded
1025 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1026 To detect if `liblttng-ust` is loaded from an application:
1028 . Define the `lttng_ust_loaded` weak symbol globally:
1030 ------------------------------------------------------------------------
1031 int lttng_ust_loaded __attribute__((weak));
1032 ------------------------------------------------------------------------
1034 This weak symbol is set by the constructor of `liblttng-ust`.
1036 . Test `lttng_ust_loaded` where needed:
1038 ------------------------------------------------------------------------
1041 if (lttng_ust_loaded) {
1042 /* LTTng-UST is loaded */
1044 /* LTTng-UST is NOT loaded */
1048 ------------------------------------------------------------------------
1054 NOTE: A few examples are available in the
1055 https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples[`doc/examples`]
1056 directory of LTTng-UST's source tree.
1058 This example shows all the features documented in the previous
1059 sections. The <<build-static,static linking>> method is chosen here
1060 to link the application with the tracepoint provider.
1062 You can compile the source files and link them together statically
1069 $ cc -o app tp.o app.o -llttng-ust -ldl
1072 Using the man:lttng(1) tool, create an LTTng tracing session, enable
1073 all the events of this tracepoint provider, and start tracing:
1077 $ lttng create my-session
1078 $ lttng enable-event --userspace 'my_provider:*'
1082 You may also enable specific events:
1086 $ lttng enable-event --userspace my_provider:big_event
1087 $ lttng enable-event --userspace my_provider:event_instance2
1090 Run the application:
1094 $ ./app some arguments
1097 Stop the current tracing session and inspect the recorded events:
1106 Tracepoint provider header file
1107 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1110 ------------------------------------------------------------------------
1111 #undef TRACEPOINT_PROVIDER
1112 #define TRACEPOINT_PROVIDER my_provider
1114 #undef TRACEPOINT_INCLUDE
1115 #define TRACEPOINT_INCLUDE "./tp.h"
1117 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
1120 #include <lttng/tracepoint.h>
1129 int, my_integer_arg,
1130 const char *, my_string_arg
1133 ctf_string(argc, my_string_arg)
1134 ctf_integer(int, argv, my_integer_arg)
1142 ctf_enum_value("ZERO", 0)
1143 ctf_enum_value("ONE", 1)
1144 ctf_enum_value("TWO", 2)
1145 ctf_enum_range("A RANGE", 52, 125)
1146 ctf_enum_value("ONE THOUSAND", 1000)
1154 int, my_integer_arg,
1155 const char *, my_string_arg,
1161 ctf_integer(int, int_field1, my_integer_arg * 2)
1162 ctf_integer_hex(long int, stream_pos, ftell(stream))
1163 ctf_float(double, float_field, flt_arg)
1164 ctf_string(string_field, my_string_arg)
1165 ctf_array(int, array_field, array_arg, 7)
1166 ctf_array_text(char, array_text_field, array_arg, 5)
1167 ctf_sequence(int, seq_field, array_arg, int,
1168 my_integer_arg / 10)
1169 ctf_sequence_text(char, seq_text_field, array_arg,
1170 int, my_integer_arg / 5)
1171 ctf_enum(my_provider, my_enum, int,
1172 enum_field, array_arg[1])
1176 TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING)
1178 TRACEPOINT_EVENT_CLASS(
1180 my_tracepoint_class,
1182 int, my_integer_arg,
1183 struct app_struct *, app_struct_arg
1186 ctf_integer(int, a, my_integer_arg)
1187 ctf_integer(unsigned long, b, app_struct_arg->b)
1188 ctf_string(c, app_struct_arg->c)
1192 TRACEPOINT_EVENT_INSTANCE(
1194 my_tracepoint_class,
1197 int, my_integer_arg,
1198 struct app_struct *, app_struct_arg
1202 TRACEPOINT_EVENT_INSTANCE(
1204 my_tracepoint_class,
1207 int, my_integer_arg,
1208 struct app_struct *, app_struct_arg
1212 TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO)
1214 TRACEPOINT_EVENT_INSTANCE(
1216 my_tracepoint_class,
1219 int, my_integer_arg,
1220 struct app_struct *, app_struct_arg
1226 #include <lttng/tracepoint-event.h>
1227 ------------------------------------------------------------------------
1230 Tracepoint provider source file
1231 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1234 ------------------------------------------------------------------------
1235 #define TRACEPOINT_CREATE_PROBES
1236 #define TRACEPOINT_DEFINE
1239 ------------------------------------------------------------------------
1242 Application header file
1243 ~~~~~~~~~~~~~~~~~~~~~~~
1246 ------------------------------------------------------------------------
1257 ------------------------------------------------------------------------
1260 Application source file
1261 ~~~~~~~~~~~~~~~~~~~~~~~
1264 ------------------------------------------------------------------------
1271 static int array_of_ints[] = {
1272 100, -35, 1, 23, 14, -6, 28, 1001, -3000,
1275 int main(int argc, char* argv[])
1278 struct app_struct app_struct;
1280 tracepoint(my_provider, simple_event, argc, argv[0]);
1281 stream = fopen("/tmp/app.txt", "w");
1285 "Error: Cannot open /tmp/app.txt for writing\n");
1286 return EXIT_FAILURE;
1289 if (fprintf(stream, "0123456789") != 10) {
1291 fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
1292 return EXIT_FAILURE;
1295 tracepoint(my_provider, big_event, 35, "hello tracepoint",
1296 stream, -3.14, array_of_ints);
1298 app_struct.b = argc;
1299 app_struct.c = "[the string]";
1300 tracepoint(my_provider, event_instance1, 23, &app_struct);
1301 app_struct.b = argc * 5;
1302 app_struct.c = "[other string]";
1303 tracepoint(my_provider, event_instance2, 17, &app_struct);
1305 app_struct.c = "nothing";
1306 tracepoint(my_provider, event_instance3, -52, &app_struct);
1308 return EXIT_SUCCESS;
1310 ------------------------------------------------------------------------
1313 ENVIRONMENT VARIABLES
1314 ---------------------
1316 Alternative user's home directory. This variable is useful when the
1317 user running the instrumented application has a non-writable home
1320 Unix sockets used for the communication between `liblttng-ust` and the
1321 LTTng session and consumer daemons (part of the LTTng-tools project)
1322 are located in a specific directory under `$LTTNG_HOME` (or `$HOME` if
1323 `$LTTNG_HOME` is not set).
1325 `LTTNG_UST_ALLOW_BLOCKING`::
1326 If set, allow the application to retry event tracing when there's
1327 no space left for the event record in the sub-buffer, therefore
1328 effectively blocking the application until space is made available
1329 or the configured timeout is reached.
1331 To allow an application to block during tracing, you also need to
1332 specify a blocking timeout when you create a channel with the
1333 nloption:--blocking-timeout option of the man:lttng-enable-channel(1)
1336 This option can be useful in workloads generating very large trace data
1337 throughput, where blocking the application is an acceptable trade-off to
1338 prevent discarding event records.
1340 WARNING: Setting this environment variable may significantly
1341 affect application timings.
1343 `LTTNG_UST_CLOCK_PLUGIN`::
1344 Path to the shared object which acts as the clock override plugin.
1345 An example of such a plugin can be found in the LTTng-UST
1347 https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/clock-override[`examples/clock-override`].
1350 If set, enable `liblttng-ust`'s debug and error output.
1352 `LTTNG_UST_GETCPU_PLUGIN`::
1353 Path to the shared object which acts as the `getcpu()` override
1354 plugin. An example of such a plugin can be found in the LTTng-UST
1356 https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/getcpu-override[`examples/getcpu-override`].
1358 `LTTNG_UST_REGISTER_TIMEOUT`::
1359 Waiting time for the _registration done_ session daemon command
1360 before proceeding to execute the main program (milliseconds).
1362 The value `0` means _do not wait_. The value `-1` means _wait forever_.
1363 Setting this environment variable to `0` is recommended for applications
1364 with time constraints on the process startup time.
1366 Default: {lttng_ust_register_timeout}.
1368 `LTTNG_UST_WITHOUT_BADDR_STATEDUMP`::
1369 If set, prevents `liblttng-ust` from performing a base address state
1370 dump (see the <<state-dump,LTTng-UST state dump>> section above).
1373 include::common-footer.txt[]
1375 include::common-copyrights.txt[]
1377 include::common-authors.txt[]
1384 man:lttng-gen-tp(1),
1385 man:lttng-ust-dl(3),
1386 man:lttng-ust-cyg-profile(3),
1388 man:lttng-enable-event(1),
1390 man:lttng-add-context(1),