8 lttng-ust - LTTng user space tracing
14 *#include <lttng/tracepoint.h>*
17 #define *LTTNG_UST_TP_ARGS*('args'...)
18 #define *LTTNG_UST_TP_ENUM_VALUES*('values'...)
19 #define *LTTNG_UST_TP_FIELDS*('fields'...)
20 #define *LTTNG_UST_TRACEPOINT_ENUM*('prov_name', 'enum_name', 'mappings')
21 #define *LTTNG_UST_TRACEPOINT_EVENT*('prov_name', 't_name', 'args', 'fields')
22 #define *LTTNG_UST_TRACEPOINT_EVENT_CLASS*('cls_prov_name', 'cls_name',
24 #define *LTTNG_UST_TRACEPOINT_EVENT_INSTANCE*('cls_prov_name', 'cls_name',
25 'inst_prov_name', 't_name', 'args')
26 #define *LTTNG_UST_TRACEPOINT_LOGLEVEL*('prov_name', 't_name', 'level')
27 #define *lttng_ust_do_tracepoint*('prov_name', 't_name', ...)
28 #define *lttng_ust_field_array*('int_type', 'field_name', 'expr', 'count')
29 #define *lttng_ust_field_array_nowrite*('int_type', 'field_name', 'expr', 'count')
30 #define *lttng_ust_field_array_hex*('int_type', 'field_name', 'expr', 'count')
31 #define *lttng_ust_field_array_nowrite_hex*('int_type', 'field_name', 'expr',
33 #define *lttng_ust_field_array_network*('int_type', 'field_name', 'expr', 'count')
34 #define *lttng_ust_field_array_network_nowrite*('int_type', 'field_name',
36 #define *lttng_ust_field_array_network_hex*('int_type', 'field_name', 'expr',
38 #define *lttng_ust_field_array_network_nowrite_hex*('int_type', 'field_name',
40 #define *lttng_ust_field_array_text*(char, 'field_name', 'expr', 'count')
41 #define *lttng_ust_field_array_text_nowrite*(char, 'field_name', 'expr',
43 #define *lttng_ust_field_enum*('prov_name', 'enum_name', 'int_type', 'field_name',
45 #define *lttng_ust_field_enum_nowrite*('prov_name', 'enum_name', 'int_type',
47 #define *lttng_ust_field_enum_value*('label', 'value')
48 #define *lttng_ust_field_enum_range*('label', 'start', 'end')
49 #define *lttng_ust_field_float*('float_type', 'field_name', 'expr')
50 #define *lttng_ust_field_float_nowrite*('float_type', 'field_name', 'expr')
51 #define *lttng_ust_field_integer*('int_type', 'field_name', 'expr')
52 #define *lttng_ust_field_integer_hex*('int_type', 'field_name', 'expr')
53 #define *lttng_ust_field_integer_network*('int_type', 'field_name', 'expr')
54 #define *lttng_ust_field_integer_network_hex*('int_type', 'field_name', 'expr')
55 #define *lttng_ust_field_integer_nowrite*('int_type', 'field_name', 'expr')
56 #define *lttng_ust_field_sequence*('int_type', 'field_name', 'expr',
57 'len_type', 'len_expr')
58 #define *lttng_ust_field_sequence_nowrite*('int_type', 'field_name', 'expr',
59 'len_type', 'len_expr')
60 #define *lttng_ust_field_sequence_hex*('int_type', 'field_name', 'expr',
61 'len_type', 'len_expr')
62 #define *lttng_ust_field_sequence_nowrite_hex*('int_type', 'field_name', 'expr',
63 'len_type', 'len_expr')
64 #define *lttng_ust_field_sequence_network*('int_type', 'field_name', 'expr',
65 'len_type', 'len_expr')
66 #define *lttng_ust_field_sequence_network_nowrite*('int_type', 'field_name',
69 #define *lttng_ust_field_sequence_network_hex*('int_type', 'field_name', 'expr',
70 'len_type', 'len_expr')
71 #define *lttng_ust_field_sequence_network_nowrite_hex*('int_type',
75 #define *lttng_ust_field_sequence_text*(char, 'field_name', 'expr', 'len_type',
77 #define *lttng_ust_field_sequence_text_nowrite*(char, 'field_name', 'expr',
78 'len_type', 'len_expr')
79 #define *lttng_ust_field_string*('field_name', 'expr')
80 #define *lttng_ust_field_string_nowrite*('field_name', 'expr')
81 #define *lttng_ust_tracepoint*('prov_name', 't_name', ...)
82 #define *lttng_ust_tracepoint_enabled*('prov_name', 't_name')
84 Link with `-llttng-ust -llttng-ust-common -ldl`, following this man page.
89 The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
90 source software package used for correlated tracing of the Linux kernel,
91 user applications, and user libraries.
93 LTTng-UST is the user space tracing component of the LTTng project. It
94 is a port to user space of the low-overhead tracing capabilities of the
95 LTTng Linux kernel tracer. The `liblttng-ust` library is used to trace
96 user applications and libraries.
98 NOTE: This man page is about the `liblttng-ust` library. The LTTng-UST
99 project also provides Java and Python packages to trace applications
100 written in those languages. How to instrument and trace Java and Python
101 applications is documented in
102 http://lttng.org/docs/[the online LTTng documentation].
104 There are three ways to use `liblttng-ust`:
106 * Using the man:lttng_ust_tracef(3) API, which is similar to
108 * Using the man:lttng_ust_tracelog(3) API, which is
109 man:lttng_ust_tracef(3) with a log level parameter.
110 * Defining your own tracepoints. See the
111 <<creating-tp,Creating a tracepoint provider>> section below.
114 Compatibility with previous APIs
115 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
116 Since LTTng-UST{nbsp}2.13, the `LTTNG_UST_COMPAT_API_VERSION` definition
117 controls which LTTng-UST APIs are available (compiled):
120 All APIs are available.
122 'N' (0 or positive integer)::
123 API version{nbsp}__N__, and all the following existing APIs, are
124 available. Previous APIs are not available (not compiled).
126 The following table shows the mapping from LTTng-UST versions (up to
127 LTTng-UST{nbsp}{manversion}) to available API versions:
131 |LTTng-UST version |Available API versions
136 This manual page **only** documents version{nbsp}1 of the API.
138 If you wish to have access to version{nbsp}0 of the API (for example,
139 the `tracepoint()`, `ctf_integer()`, and `TRACEPOINT_EVENT()` macros),
140 then either don't define `LTTNG_UST_COMPAT_API_VERSION`, or define it to
141 `0` before including any LTTng-UST header.
145 Creating a tracepoint provider
146 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
147 Creating a tracepoint provider is the first step of using
148 `liblttng-ust`. The next steps are:
150 * <<tracepoint,Instrumenting your application with
151 `lttng_ust_tracepoint()` calls>>
152 * Building your application with LTTng-UST support, either
153 <<build-static,statically>> or <<build-dynamic,dynamically>>.
155 A *tracepoint provider* is a compiled object containing the event probes
156 corresponding to your custom tracepoint definitions. A tracepoint
157 provider contains the code to get the size of an event and to serialize
158 it, amongst other things.
160 To create a tracepoint provider, start with the following
161 _tracepoint provider header_ template:
163 ------------------------------------------------------------------------
164 #undef LTTNG_UST_TRACEPOINT_PROVIDER
165 #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
167 #undef LTTNG_UST_TRACEPOINT_INCLUDE
168 #define LTTNG_UST_TRACEPOINT_INCLUDE "./tp.h"
170 #if !defined(_TP_H) || \
171 defined(LTTNG_UST_TRACEPOINT_HEADER_MULTI_READ)
174 #include <lttng/tracepoint.h>
177 * LTTNG_UST_TRACEPOINT_EVENT(), LTTNG_UST_TRACEPOINT_EVENT_CLASS(),
178 * LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(),
179 * LTTNG_UST_TRACEPOINT_LOGLEVEL(), and `LTTNG_UST_TRACEPOINT_ENUM()`
185 #include <lttng/tracepoint-event.h>
186 ------------------------------------------------------------------------
188 In this template, the tracepoint provider is named `my_provider`
189 (`LTTNG_UST_TRACEPOINT_PROVIDER` definition). The file needs to bear the
190 name of the `LTTNG_UST_TRACEPOINT_INCLUDE` definition (`tp.h` in this case).
191 Between `#include <lttng/tracepoint.h>` and `#endif` go
192 the invocations of the <<tracepoint-event,`LTTNG_UST_TRACEPOINT_EVENT()`>>,
193 <<tracepoint-event-class,`LTTNG_UST_TRACEPOINT_EVENT_CLASS()`>>,
194 <<tracepoint-event-class,`LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()`>>,
195 <<tracepoint-loglevel,`LTTNG_UST_TRACEPOINT_LOGLEVEL()`>>, and
196 <<tracepoint-enum,`LTTNG_UST_TRACEPOINT_ENUM()`>> macros.
198 NOTE: You can avoid writing the prologue and epilogue boilerplate in the
199 template file above by using the man:lttng-gen-tp(1) tool shipped with
202 The tracepoint provider header file needs to be included in a source
203 file which looks like this:
205 ------------------------------------------------------------------------
206 #define LTTNG_UST_TRACEPOINT_CREATE_PROBES
209 ------------------------------------------------------------------------
211 Together, those two files (let's call them `tp.h` and `tp.c`) form the
212 tracepoint provider sources, ready to be compiled.
214 You can create multiple tracepoint providers to be used in a single
215 application, but each one must have its own header file.
217 The <<tracepoint-event,`LTTNG_UST_TRACEPOINT_EVENT()` usage>> section below
218 shows how to use the `LTTNG_UST_TRACEPOINT_EVENT()` macro to define the actual
219 tracepoints in the tracepoint provider header file.
221 See the <<example,EXAMPLE>> section below for a complete example.
225 `LTTNG_UST_TRACEPOINT_EVENT()` usage
226 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
227 The `LTTNG_UST_TRACEPOINT_EVENT()` macro is used in a template provider
228 header file (see the <<creating-tp,Creating a tracepoint provider>>
229 section above) to define LTTng-UST tracepoints.
231 The `LTTNG_UST_TRACEPOINT_EVENT()` usage template is as follows:
233 ------------------------------------------------------------------------
234 LTTNG_UST_TRACEPOINT_EVENT(
235 /* Tracepoint provider name */
238 /* Tracepoint/event name */
241 /* List of tracepoint arguments (input) */
246 /* List of fields of eventual event (output) */
251 ------------------------------------------------------------------------
253 The `LTTNG_UST_TP_ARGS()` macro contains the input arguments of the tracepoint.
254 Those arguments can be used in the argument expressions of the output
255 fields defined in `LTTNG_UST_TP_FIELDS()`.
257 The format of the `LTTNG_UST_TP_ARGS()` parameters is: C type, then argument name;
258 repeat as needed, up to ten times. For example:
260 ------------------------------------------------------------------------
263 const char *, my_string,
266 struct my_data *, my_data
268 ------------------------------------------------------------------------
270 The `LTTNG_UST_TP_FIELDS()` macro contains the output fields of the tracepoint,
271 that is, the actual data that can be recorded in the payload of an event
272 emitted by this tracepoint.
274 The `LTTNG_UST_TP_FIELDS()` macro contains a list of
275 `lttng_ust_field_*()` macros :not: separated by commas.
276 The available macros are documented in the
277 <<ctf-macros,Available `lttng_ust_field_*()` field type macros>>
282 Available field macros
283 ~~~~~~~~~~~~~~~~~~~~~~
284 This section documents the available `lttng_ust_field_*()` macros that
285 can be inserted in the `LTTNG_UST_TP_FIELDS()` macro of the
286 <<tracepoint-event,`LTTNG_UST_TRACEPOINT_EVENT()` macro>>.
288 Standard integer, displayed in base 10:
291 *lttng_ust_field_integer*('int_type', 'field_name', 'expr')
292 *lttng_ust_field_integer_nowrite*('int_type', 'field_name', 'expr')
294 Standard integer, displayed in base 16:
297 *lttng_ust_field_integer_hex*('int_type', 'field_name', 'expr')
299 Integer in network byte order (big endian), displayed in base 10:
302 *lttng_ust_field_integer_network*('int_type', 'field_name', 'expr')
304 Integer in network byte order, displayed in base 16:
307 *lttng_ust_field_integer_network_hex*('int_type', 'field_name', 'expr')
309 Floating point number:
312 *lttng_ust_field_float*('float_type', 'field_name', 'expr')
313 *lttng_ust_field_float_nowrite*('float_type', 'field_name', 'expr')
315 Null-terminated string:
318 *lttng_ust_field_string*('field_name', 'expr')
319 *lttng_ust_field_string_nowrite*('field_name', 'expr')
321 Statically-sized array of integers (`_hex` versions displayed in
322 hexadecimal, `_network` versions in network byte order):
325 *lttng_ust_field_array*('int_type', 'field_name', 'expr', 'count')
326 *lttng_ust_field_array_nowrite*('int_type', 'field_name', 'expr', 'count')
327 *lttng_ust_field_array_hex*('int_type', 'field_name', 'expr', 'count')
328 *lttng_ust_field_array_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
329 *lttng_ust_field_array_network*('int_type', 'field_name', 'expr', 'count')
330 *lttng_ust_field_array_network_nowrite*('int_type', 'field_name', 'expr',
332 *lttng_ust_field_array_network_hex*('int_type', 'field_name', 'expr', 'count')
333 *lttng_ust_field_array_network_nowrite_hex*('int_type', 'field_name',
336 Statically-sized array, printed as text; no need to be null-terminated:
339 *lttng_ust_field_array_text*(char, 'field_name', 'expr', 'count')
340 *lttng_ust_field_array_text_nowrite*(char, 'field_name', 'expr', 'count')
342 Dynamically-sized array of integers (`_hex` versions displayed in
343 hexadecimal, `_network` versions in network byte order):
346 *lttng_ust_field_sequence*('int_type', 'field_name', 'expr', 'len_type',
348 *lttng_ust_field_sequence_nowrite*('int_type', 'field_name', 'expr',
349 'len_type', 'len_expr')
350 *lttng_ust_field_sequence_hex*('int_type', 'field_name', 'expr', 'len_type',
352 *lttng_ust_field_sequence_nowrite_hex*('int_type', 'field_name', 'expr',
353 'len_type', 'len_expr')
354 *lttng_ust_field_sequence_network*('int_type', 'field_name', 'expr',
355 'len_type', 'len_expr')
356 *lttng_ust_field_sequence_network_nowrite*('int_type', 'field_name', 'expr',
357 'len_type', 'len_expr')
358 *lttng_ust_field_sequence_network_hex*('int_type', 'field_name', 'expr',
359 'len_type', 'len_expr')
360 *lttng_ust_field_sequence_network_nowrite_hex*('int_type', 'field_name',
364 Dynamically-sized array, displayed as text; no need to be null-terminated:
367 *lttng_ust_field_sequence_text*(char, 'field_name', 'expr', 'len_type',
369 *lttng_ust_field_sequence_text_nowrite*(char, 'field_name', 'expr',
370 'len_type', 'len_expr')
372 Enumeration. The enumeration field must be defined before using this
373 macro with the `LTTNG_UST_TRACEPOINT_ENUM()` macro. See the
374 <<tracepoint-enum,`LTTNG_UST_TRACEPOINT_ENUM()` usage>> section for more
378 *lttng_ust_field_enum*('prov_name', 'enum_name', 'int_type', 'field_name',
380 *lttng_ust_field_enum_nowrite*('prov_name', 'enum_name', 'int_type',
381 'field_name', 'expr')
386 Number of elements in array/sequence. This must be known at
390 Name of an enumeration field previously defined with the
391 `LTTNG_UST_TRACEPOINT_ENUM()` macro. See the
392 <<tracepoint-enum,`LTTNG_UST_TRACEPOINT_ENUM()` usage>> section for more
396 C expression resulting in the field's value. This expression can
397 use one or more arguments passed to the tracepoint. The arguments
398 of a given tracepoint are defined in the `LTTNG_UST_TP_ARGS()` macro (see
399 the <<creating-tp,Creating a tracepoint provider>> section above).
402 Event field name (C identifier syntax, :not: a literal string).
405 Float C type (`float` or `double`). The size of this type determines
406 the size of the floating point number field.
409 Integer C type. The size of this type determines the size of the
410 integer/enumeration field.
413 C expression resulting in the sequence's length. This expression
414 can use one or more arguments passed to the tracepoint.
417 Unsigned integer C type of sequence's length.
420 Tracepoint provider name. This must be the same as the tracepoint
421 provider name used in a previous field definition.
423 The `_nowrite` versions omit themselves from the recorded trace, but are
424 otherwise identical. Their primary purpose is to make some of the
425 event context available to the event filters without having to commit
426 the data to sub-buffers. See man:lttng-enable-event(1) to learn more
427 about dynamic event filtering.
429 See the <<example,EXAMPLE>> section below for a complete example.
433 `LTTNG_UST_TRACEPOINT_ENUM()` usage
434 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
435 An enumeration field is a list of mappings between an integers, or a
436 range of integers, and strings (sometimes called _labels_ or
437 _enumerators_). Enumeration fields can be used to have a more compact
438 trace when the possible values for a field are limited.
440 An enumeration field is defined with the `LTTNG_UST_TRACEPOINT_ENUM()`
443 ------------------------------------------------------------------------
444 LTTNG_UST_TRACEPOINT_ENUM(
445 /* Tracepoint provider name */
448 /* Enumeration name (unique in the whole tracepoint provider) */
451 /* Enumeration mappings */
452 LTTNG_UST_TP_ENUM_VALUES(
456 ------------------------------------------------------------------------
458 `LTTNG_UST_TP_ENUM_VALUES()` contains a list of enumeration mappings,
459 :not: separated by commas. Two macros can be used in the
460 `LTTNG_UST_TP_ENUM_VALUES()`: `lttng_ust_field_enum_value()` and
461 `lttng_ust_field_enum_range()`.
463 `lttng_ust_field_enum_value()` is a single value mapping:
466 *lttng_ust_field_enum_value*('label', 'value')
468 This macro maps the given 'label' string to the value 'value'.
470 `lttng_ust_field_enum_range()` is a range mapping:
473 *lttng_ust_field_enum_range*('label', 'start', 'end')
475 This macro maps the given 'label' string to the range of integers from
476 'start' to 'end', inclusively. Range mappings may overlap, but the
477 behaviour is implementation-defined: each trace reader handles
478 overlapping ranges as it wishes.
480 See the <<example,EXAMPLE>> section below for a complete example.
483 [[tracepoint-event-class]]
484 `LTTNG_UST_TRACEPOINT_EVENT_CLASS()` usage
485 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
486 A *tracepoint class* is a class of tracepoints sharing the
487 same field types and names. A tracepoint instance is one instance of
488 such a declared tracepoint class, with its own event name.
490 LTTng-UST creates one event serialization function per tracepoint class.
491 Using `LTTNG_UST_TRACEPOINT_EVENT()` creates one tracepoint class per
492 tracepoint definition, whereas using
493 `LTTNG_UST_TRACEPOINT_EVENT_CLASS()` and
494 `LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()` creates one tracepoint class,
495 and one or more tracepoint instances of this class. In other words, many
496 tracepoints can reuse the same serialization code. Reusing the same
497 code, when possible, can reduce cache pollution, thus improve
500 The `LTTNG_UST_TRACEPOINT_EVENT_CLASS()` macro accepts the same
501 parameters as the `LTTNG_UST_TRACEPOINT_EVENT()` macro, except that
502 instead of an event name, its second parameter is the _tracepoint class
505 ------------------------------------------------------------------------
506 #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
510 LTTNG_UST_TRACEPOINT_EVENT_CLASS(
511 /* Tracepoint class provider name */
514 /* Tracepoint class name */
517 /* List of tracepoint arguments (input) */
522 /* List of fields of eventual event (output) */
527 ------------------------------------------------------------------------
529 Once the tracepoint class is defined, you can create as many tracepoint
532 -------------------------------------------------------------------------
533 #define LTTNG_UST_TRACEPOINT_PROVIDER natality
537 LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
538 /* Name of the tracepoint class provider */
541 /* Tracepoint class name */
544 /* Name of the local (instance) tracepoint provider */
547 /* Tracepoint/event name */
550 /* List of tracepoint arguments (input) */
555 ------------------------------------------------------------------------
557 As you can see, the `LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()` does not
558 contain the `LTTNG_UST_TP_FIELDS()` macro, because they are defined at
559 the `LTTNG_UST_TRACEPOINT_EVENT_CLASS()` level.
561 Note that the `LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()` macro requires two
564 * The name of the tracepoint class provider (`my_provider` in the
567 This is the same as the first argument of the
568 `LTTNG_UST_TRACEPOINT_EVENT_CLASS()` expansion to refer to.
570 * The name of the local, or instance, provider (`natality` in the
573 This is the provider name which becomes the prefix part of the name of
574 the events which such a tracepoint creates.
576 The two provider names may be different if the tracepoint class and the
577 tracepoint instance macros are in two different translation units.
579 See the <<example,EXAMPLE>> section below for a complete example.
582 [[tracepoint-loglevel]]
583 `LTTNG_UST_TRACEPOINT_LOGLEVEL()` usage
584 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
585 Optionally, a *log level* can be assigned to a defined tracepoint.
586 Assigning different levels of severity to tracepoints can be useful:
587 when controlling tracing sessions, you can choose to only enable
588 events falling into a specific log level range using the
589 nloption:--loglevel and nloption:--loglevel-only options of the
590 man:lttng-enable-event(1) command.
592 Log levels are assigned to tracepoints that are already defined using
593 the `LTTNG_UST_TRACEPOINT_LOGLEVEL()` macro. The latter must be used
594 after having used `LTTNG_UST_TRACEPOINT_EVENT()` or
595 `LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()` for a given tracepoint. The
596 `LTTNG_UST_TRACEPOINT_LOGLEVEL()` macro is used as follows:
598 ------------------------------------------------------------------------
599 LTTNG_UST_TRACEPOINT_LOGLEVEL(
600 /* Tracepoint provider name */
603 /* Tracepoint/event name */
607 LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO
609 ------------------------------------------------------------------------
611 The available log level definitions are:
613 include::log-levels.txt[]
615 See the <<example,EXAMPLE>> section below for a complete example.
619 Instrumenting your application
620 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
621 Once the tracepoint provider is created (see the
622 <<creating-tp,Creating a tracepoint provider>> section above), you can
623 instrument your application with the defined tracepoints thanks to the
624 `lttng_ust_tracepoint()` macro:
627 #define *lttng_ust_tracepoint*('prov_name', 't_name', ...)
632 Tracepoint provider name.
635 Tracepoint/event name.
638 Tracepoint arguments, if any.
640 Make sure to include the tracepoint provider header file anywhere you
641 use `lttng_ust_tracepoint()` for this provider.
643 NOTE: Even though LTTng-UST supports `lttng_ust_tracepoint()` call site
644 duplicates having the same provider and tracepoint names, it is
645 recommended to use a provider/tracepoint name pair only once within the
646 application source code to help map events back to their call sites when
649 Sometimes, arguments to the tracepoint are expensive to compute (take
650 call stack, for example). To avoid the computation when the tracepoint
651 is disabled, you can use the `lttng_ust_tracepoint_enabled()` and
652 `lttng_ust_do_tracepoint()` macros:
655 #define *lttng_ust_tracepoint_enabled*('prov_name', 't_name')
656 #define *lttng_ust_do_tracepoint*('prov_name', 't_name', ...)
658 `lttng_ust_tracepoint_enabled()` returns a non-zero value if the tracepoint
659 named 't_name' from the provider named 'prov_name' is enabled at
662 `lttng_ust_do_tracepoint()` is like `lttng_ust_tracepoint()`, except that it doesn't check
663 if the tracepoint is enabled. Using `lttng_ust_tracepoint()` with
664 `lttng_ust_tracepoint_enabled()` is dangerous since `lttng_ust_tracepoint()` also contains
665 the `lttng_ust_tracepoint_enabled()` check, thus a race condition is possible
668 ------------------------------------------------------------------------
669 if (lttng_ust_tracepoint_enabled(my_provider, my_tracepoint)) {
670 stuff = prepare_stuff();
673 lttng_ust_tracepoint(my_provider, my_tracepoint, stuff);
674 ------------------------------------------------------------------------
676 If the tracepoint is enabled after the condition, then `stuff` is not
677 prepared: the emitted event will either contain wrong data, or the
678 whole application could crash (segmentation fault, for example).
680 NOTE: Neither `lttng_ust_tracepoint_enabled()` nor
681 `lttng_ust_do_tracepoint()` have a `STAP_PROBEV()` call, so if you need
682 it, you should emit this call yourself.
686 Statically linking the tracepoint provider
687 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
688 With the static linking method, compiled tracepoint providers are copied
689 into the target application.
691 Define `LTTNG_UST_TRACEPOINT_DEFINE` definition below the
692 `LTTNG_UST_TRACEPOINT_CREATE_PROBES` definition in the tracepoint
695 ------------------------------------------------------------------------
696 #define LTTNG_UST_TRACEPOINT_CREATE_PROBES
697 #define LTTNG_UST_TRACEPOINT_DEFINE
700 ------------------------------------------------------------------------
702 Create the tracepoint provider object file:
709 NOTE: Although an application instrumented with LTTng-UST tracepoints
710 can be compiled with a $$C++$$ compiler, tracepoint probes
711 should be compiled with a C compiler.
713 At this point, you _can_ archive this tracepoint provider object file,
714 possibly with other object files of your application or with other
715 tracepoint provider object files, as a static library:
722 Using a static library does have the advantage of centralising the
723 tracepoint providers objects so they can be shared between multiple
724 applications. This way, when the tracepoint provider is modified, the
725 source code changes don't have to be patched into each application's
726 source code tree. The applications need to be relinked after each
727 change, but need not to be otherwise recompiled (unless the tracepoint
728 provider's API changes).
730 Then, link your application with this object file (or with the static
731 library containing it) and with `liblttng-ust`, `liblttng-ust-common`,
732 and `libdl` (`libc` on a BSD system):
736 $ cc -o app tp.o app.o -llttng-ust -llttng-ust-common -ldl
741 Dynamically loading the tracepoint provider
742 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
743 The second approach to package the tracepoint provider is to use the
744 dynamic loader: the library and its member functions are explicitly
745 sought, loaded at run time.
747 In this scenario, the tracepoint provider is compiled as a shared
750 The process to create the tracepoint provider shared object is pretty
751 much the same as the <<build-static,static linking method>>, except
754 * Since the tracepoint provider is not part of the application,
755 `LTTNG_UST_TRACEPOINT_DEFINE` must be defined, for each tracepoint
756 provider, in exactly one source file of the _application_
757 * `LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next to
758 `LTTNG_UST_TRACEPOINT_DEFINE`
760 Regarding `LTTNG_UST_TRACEPOINT_DEFINE` and
761 `LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE`, the recommended practice
762 is to use a separate C source file in your application to define them,
763 then include the tracepoint provider header files afterwards. For
764 example, as `tp-define.c`:
766 ------------------------------------------------------------------------
767 #define LTTNG_UST_TRACEPOINT_DEFINE
768 #define LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE
771 ------------------------------------------------------------------------
773 The tracepoint provider object file used to create the shared library is
774 built like it is using the static linking method, but with the
775 nloption:-fpic option:
779 $ cc -c -fpic -I. tp.c
782 It is then linked as a shared library like this:
786 $ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust \
790 This tracepoint provider shared object isn't linked with the user
791 application: it must be loaded manually. This is why the application is
792 built with no mention of this tracepoint provider, but still needs
797 $ cc -o app app.o tp-define.o -ldl
800 There are two ways to dynamically load the tracepoint provider shared
803 * Load it manually from the application using man:dlopen(3)
804 * Make the dynamic loader load it with the `LD_PRELOAD`
805 environment variable (see man:ld.so(8))
807 If the application does not dynamically load the tracepoint provider
808 shared object using one of the methods above, tracing is disabled for
809 this application, and the events are not listed in the output of
812 Note that it is not safe to use man:dlclose(3) on a tracepoint provider
813 shared object that is being actively used for tracing, due to a lack of
814 reference counting from LTTng-UST to the shared object.
816 For example, statically linking a tracepoint provider to a shared object
817 which is to be dynamically loaded by an application (a plugin, for
818 example) is not safe: the shared object, which contains the tracepoint
819 provider, could be dynamically closed (man:dlclose(3)) at any time by
822 To instrument a shared object, either:
824 * Statically link the tracepoint provider to the application, or
825 * Build the tracepoint provider as a shared object (following the
826 procedure shown in this section), and preload it when tracing is
827 needed using the `LD_PRELOAD` environment variable.
830 Using LTTng-UST with daemons
831 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
832 Some extra care is needed when using `liblttng-ust` with daemon
833 applications that call man:fork(2), man:clone(2), or BSD's man:rfork(2)
834 without a following man:exec(3) family system call. The library
835 `liblttng-ust-fork.so` needs to be preloaded before starting the
836 application with the `LD_PRELOAD` environment variable (see
839 To use `liblttng-ust` with a daemon application which closes file
840 descriptors that were not opened by it, preload the `liblttng-ust-fd.so`
841 library before you start the application. Typical use cases include
842 daemons closing all file descriptors after man:fork(2), and buggy
843 applications doing ``double-closes''.
848 Context information can be prepended by the LTTng-UST tracer before
849 each event, or before specific events.
851 Context fields can be added to specific channels using
852 man:lttng-add-context(1).
854 The following context fields are supported by LTTng-UST:
856 General context fields::
861 NOTE: This context field is always enabled, and it cannot be added
862 with man:lttng-add-context(1). Its main purpose is to be used for
863 dynamic event filtering. See man:lttng-enable-event(1) for more
864 information about event filtering.
867 Instruction pointer: enables recording the exact address from which
868 an event was emitted. This context field can be used to
869 reverse-lookup the source location that caused the event
873 POSIX thread identifier.
875 Can be used on architectures where `pthread_t` maps nicely to an
876 `unsigned long` type.
878 Process context fields::
881 Thread name, as set by man:exec(3) or man:prctl(2). It is
882 recommended that programs set their thread name with man:prctl(2)
883 before hitting the first tracepoint for that thread.
886 Virtual process ID: process ID as seen from the point of view of the
887 current process ID namespace (see man:pid_namespaces(7)).
890 Virtual thread ID: thread ID as seen from the point of view of the
891 current process ID namespace (see man:pid_namespaces(7)).
893 perf context fields::
895 `perf:thread:COUNTER`:::
896 perf counter named 'COUNTER'. Use `lttng add-context --list` to
897 list the available perf counters.
899 Only available on IA-32 and x86-64 architectures.
901 `perf:thread:raw:rN:NAME`:::
902 perf counter with raw ID 'N' and custom name 'NAME'. See
903 man:lttng-add-context(1) for more details.
905 Namespace context fields (see man:namespaces(7))::
908 Inode number of the current control group namespace (see
909 man:cgroup_namespaces(7)) in the proc file system.
912 Inode number of the current IPC namespace (see
913 man:ipc_namespaces(7)) in the proc file system.
916 Inode number of the current mount point namespace (see
917 man:mount_namespaces(7)) in the proc file system.
920 Inode number of the current network namespace (see
921 man:network_namespaces(7)) in the proc file system.
924 Inode number of the current process ID namespace (see
925 man:pid_namespaces(7)) in the proc file system.
928 Inode number of the current clock namespace (see
929 man:time_namespaces(7)) in the proc file system.
932 Inode number of the current user namespace (see
933 man:user_namespaces(7)) in the proc file system.
936 Inode number of the current UTS namespace (see
937 man:uts_namespaces(7)) in the proc file system.
939 Credential context fields (see man:credentials(7))::
942 Virtual real user ID: real user ID as seen from the point of view of
943 the current user namespace (see man:user_namespaces(7)).
946 Virtual real group ID: real group ID as seen from the point of view
947 of the current user namespace (see man:user_namespaces(7)).
950 Virtual effective user ID: effective user ID as seen from the point
951 of view of the current user namespace (see man:user_namespaces(7)).
954 Virtual effective group ID: effective group ID as seen from the
955 point of view of the current user namespace (see
956 man:user_namespaces(7)).
959 Virtual saved set-user ID: saved set-user ID as seen from the point
960 of view of the current user namespace (see man:user_namespaces(7)).
963 Virtual saved set-group ID: saved set-group ID as seen from the
964 point of view of the current user namespace (see
965 man:user_namespaces(7)).
971 If an application that uses `liblttng-ust` becomes part of a tracing
972 session, information about its currently loaded shared objects, their
973 build IDs, and their debug link information are emitted as events
976 The following LTTng-UST state dump events exist and must be enabled
977 to record application state dumps. Note that, during the state dump
978 phase, LTTng-UST can also emit _shared library load/unload_ events
979 (see <<ust-lib,Shared library load/unload tracking>> below).
981 `lttng_ust_statedump:start`::
982 Emitted when the state dump begins.
984 This event has no fields.
986 `lttng_ust_statedump:end`::
987 Emitted when the state dump ends. Once this event is emitted, it
988 is guaranteed that, for a given process, the state dump is
991 This event has no fields.
993 `lttng_ust_statedump:bin_info`::
994 Emitted when information about a currently loaded executable or
995 shared object is found.
1001 |Field name |Description
1004 |Base address of loaded executable.
1007 |Size of loaded executable in memory.
1010 |Path to loaded executable file.
1013 |Whether or not the executable is position-independent code.
1016 |Whether or not the executable has a build ID. If this field is 1, you
1017 can expect that an `lttng_ust_statedump:build_id` event record follows
1018 this one (not necessarily immediately after).
1021 |Whether or not the executable has debug link information. If this field
1022 is 1, you can expect that an `lttng_ust_statedump:debug_link` event
1023 record follows this one (not necessarily immediately after).
1026 `lttng_ust_statedump:build_id`::
1027 Emitted when a build ID is found in a currently loaded shared
1029 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1030 for more information about build IDs.
1036 |Field name |Description
1039 |Base address of loaded library.
1045 `lttng_ust_statedump:debug_link`::
1046 Emitted when debug link information is found in a currently loaded
1048 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1049 for more information about debug links.
1055 |Field name |Description
1058 |Base address of loaded library.
1061 |Debug link file's CRC.
1064 |Debug link file name.
1067 `lttng_ust_statedump:procname`::
1068 The process procname at process start.
1074 |Field name |Description
1083 Shared library load/unload tracking
1084 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1085 The <<state-dump,LTTng-UST state dump>> and the LTTng-UST helper library
1086 to instrument the dynamic linker (see man:liblttng-ust-dl(3)) can emit
1087 **shared library load/unload tracking** events.
1089 The following shared library load/unload tracking events exist and must
1090 be enabled to track the loading and unloading of shared libraries:
1092 `lttng_ust_lib:load`::
1093 Emitted when a shared library (shared object) is loaded.
1099 |Field name |Description
1102 |Base address of loaded library.
1105 |Size of loaded library in memory.
1108 |Path to loaded library file.
1111 |Whether or not the library has a build ID. If this field is 1, you
1112 can expect that an `lttng_ust_lib:build_id` event record follows
1113 this one (not necessarily immediately after).
1116 |Whether or not the library has debug link information. If this field
1117 is 1, you can expect that an `lttng_ust_lib:debug_link` event
1118 record follows this one (not necessarily immediately after).
1121 `lttng_ust_lib:unload`::
1122 Emitted when a shared library (shared object) is unloaded.
1128 |Field name |Description
1131 |Base address of unloaded library.
1134 `lttng_ust_lib:build_id`::
1135 Emitted when a build ID is found in a loaded shared library (shared
1137 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1138 for more information about build IDs.
1144 |Field name |Description
1147 |Base address of loaded library.
1153 `lttng_ust_lib:debug_link`::
1154 Emitted when debug link information is found in a loaded
1155 shared library (shared object). See
1156 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1157 for more information about debug links.
1163 |Field name |Description
1166 |Base address of loaded library.
1169 |Debug link file's CRC.
1172 |Debug link file name.
1176 Detect if LTTng-UST is loaded
1177 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1178 To detect if `liblttng-ust` is loaded from an application:
1180 . Define the `lttng_ust_loaded` weak symbol globally:
1182 ------------------------------------------------------------------------
1183 int lttng_ust_loaded __attribute__((weak));
1184 ------------------------------------------------------------------------
1186 This weak symbol is set by the constructor of `liblttng-ust`.
1188 . Test `lttng_ust_loaded` where needed:
1190 ------------------------------------------------------------------------
1193 if (lttng_ust_loaded) {
1194 /* LTTng-UST is loaded */
1196 /* LTTng-UST is NOT loaded */
1200 ------------------------------------------------------------------------
1206 NOTE: A few examples are available in the
1207 https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples[`doc/examples`]
1208 directory of LTTng-UST's source tree.
1210 This example shows all the features documented in the previous
1211 sections. The <<build-static,static linking>> method is chosen here
1212 to link the application with the tracepoint provider.
1214 You can compile the source files and link them together statically
1221 $ cc -o app tp.o app.o -llttng-ust -llttng-ust-common -ldl
1224 Using the man:lttng(1) tool, create an LTTng tracing session, enable
1225 all the events of this tracepoint provider, and start tracing:
1229 $ lttng create my-session
1230 $ lttng enable-event --userspace 'my_provider:*'
1234 You may also enable specific events:
1238 $ lttng enable-event --userspace my_provider:big_event
1239 $ lttng enable-event --userspace my_provider:event_instance2
1242 Run the application:
1246 $ ./app some arguments
1249 Stop the current tracing session and inspect the recorded events:
1258 Tracepoint provider header file
1259 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1262 ------------------------------------------------------------------------
1263 #undef LTTNG_UST_TRACEPOINT_PROVIDER
1264 #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
1266 #undef LTTNG_USTTRACEPOINT_INCLUDE
1267 #define LTTNG_USTTRACEPOINT_INCLUDE "./tp.h"
1269 #if !defined(_TP_H) || \
1270 defined(LTTNG_UST_TRACEPOINT_HEADER_MULTI_READ)
1273 #include <lttng/tracepoint.h>
1278 LTTNG_UST_TRACEPOINT_EVENT(
1282 int, my_integer_arg,
1283 const char *, my_string_arg
1285 LTTNG_UST_TP_FIELDS(
1286 lttng_ust_field_string(argc, my_string_arg)
1287 lttng_ust_field_integer(int, argv, my_integer_arg)
1291 LTTNG_UST_TRACEPOINT_ENUM(
1294 LTTNG_UST_TP_ENUM_VALUES(
1295 lttng_ust_field_enum_value("ZERO", 0)
1296 lttng_ust_field_enum_value("ONE", 1)
1297 lttng_ust_field_enum_value("TWO", 2)
1298 lttng_ust_field_enum_range("A RANGE", 52, 125)
1299 lttng_ust_field_enum_value("ONE THOUSAND", 1000)
1303 LTTNG_UST_TRACEPOINT_EVENT(
1307 int, my_integer_arg,
1308 const char *, my_string_arg,
1313 LTTNG_UST_TP_FIELDS(
1314 lttng_ust_field_integer(int, int_field1, my_integer_arg * 2)
1315 lttng_ust_field_integer_hex(long int, stream_pos,
1317 lttng_ust_field_float(double, float_field, flt_arg)
1318 lttng_ust_field_string(string_field, my_string_arg)
1319 lttng_ust_field_array(int, array_field, array_arg, 7)
1320 lttng_ust_field_array_text(char, array_text_field,
1322 lttng_ust_field_sequence(int, seq_field, array_arg, int,
1323 my_integer_arg / 10)
1324 lttng_ust_field_sequence_text(char, seq_text_field,
1327 lttng_ust_field_enum(my_provider, my_enum, int,
1328 enum_field, array_arg[1])
1332 LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, big_event,
1333 LTTNG_UST_TRACEPOINT_LOGLEVEL_WARNING)
1335 LTTNG_UST_TRACEPOINT_EVENT_CLASS(
1337 my_tracepoint_class,
1339 int, my_integer_arg,
1340 struct app_struct *, app_struct_arg
1342 LTTNG_UST_TP_FIELDS(
1343 lttng_ust_field_integer(int, a, my_integer_arg)
1344 lttng_ust_field_integer(unsigned long, b, app_struct_arg->b)
1345 lttng_ust_field_string(c, app_struct_arg->c)
1349 LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
1351 my_tracepoint_class,
1355 int, my_integer_arg,
1356 struct app_struct *, app_struct_arg
1360 LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
1362 my_tracepoint_class,
1366 int, my_integer_arg,
1367 struct app_struct *, app_struct_arg
1371 LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, event_instance2,
1372 LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO)
1374 LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
1376 my_tracepoint_class,
1380 int, my_integer_arg,
1381 struct app_struct *, app_struct_arg
1387 #include <lttng/tracepoint-event.h>
1388 ------------------------------------------------------------------------
1391 Tracepoint provider source file
1392 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1395 ------------------------------------------------------------------------
1396 #define LTTNG_UST_TRACEPOINT_CREATE_PROBES
1397 #define LTTNG_UST_TRACEPOINT_DEFINE
1400 ------------------------------------------------------------------------
1403 Application header file
1404 ~~~~~~~~~~~~~~~~~~~~~~~
1407 ------------------------------------------------------------------------
1418 ------------------------------------------------------------------------
1421 Application source file
1422 ~~~~~~~~~~~~~~~~~~~~~~~
1425 ------------------------------------------------------------------------
1432 static int array_of_ints[] = {
1433 100, -35, 1, 23, 14, -6, 28, 1001, -3000,
1436 int main(int argc, char* argv[])
1439 struct app_struct app_struct;
1441 lttng_ust_tracepoint(my_provider, simple_event, argc, argv[0]);
1442 stream = fopen("/tmp/app.txt", "w");
1446 "Error: Cannot open /tmp/app.txt for writing\n");
1447 return EXIT_FAILURE;
1450 if (fprintf(stream, "0123456789") != 10) {
1452 fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
1453 return EXIT_FAILURE;
1456 lttng_ust_tracepoint(my_provider, big_event, 35,
1457 "hello tracepoint", stream, -3.14,
1460 app_struct.b = argc;
1461 app_struct.c = "[the string]";
1462 lttng_ust_tracepoint(my_provider, event_instance1, 23,
1464 app_struct.b = argc * 5;
1465 app_struct.c = "[other string]";
1466 lttng_ust_tracepoint(my_provider, event_instance2, 17,
1469 app_struct.c = "nothing";
1470 lttng_ust_tracepoint(my_provider, event_instance3, -52,
1472 return EXIT_SUCCESS;
1474 ------------------------------------------------------------------------
1477 ENVIRONMENT VARIABLES
1478 ---------------------
1480 Alternative user's home directory. This variable is useful when the
1481 user running the instrumented application has a non-writable home
1484 Unix sockets used for the communication between `liblttng-ust` and the
1485 LTTng session and consumer daemons (part of the LTTng-tools project)
1486 are located in a specific directory under `$LTTNG_HOME` (or `$HOME` if
1487 `$LTTNG_HOME` is not set).
1489 `LTTNG_UST_ALLOW_BLOCKING`::
1490 If set, allow the application to retry event tracing when there's
1491 no space left for the event record in the sub-buffer, therefore
1492 effectively blocking the application until space is made available
1493 or the configured timeout is reached.
1495 To allow an application to block during tracing, you also need to
1496 specify a blocking timeout when you create a channel with the
1497 nloption:--blocking-timeout option of the man:lttng-enable-channel(1)
1500 This option can be useful in workloads generating very large trace data
1501 throughput, where blocking the application is an acceptable trade-off to
1502 prevent discarding event records.
1504 WARNING: Setting this environment variable may significantly
1505 affect application timings.
1507 `LTTNG_UST_CLOCK_PLUGIN`::
1508 Path to the shared object which acts as the clock override plugin.
1509 An example of such a plugin can be found in the LTTng-UST
1511 https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/clock-override[`examples/clock-override`].
1514 If set, enable `liblttng-ust`'s debug and error output.
1516 `LTTNG_UST_GETCPU_PLUGIN`::
1517 Path to the shared object which acts as the `getcpu()` override
1518 plugin. An example of such a plugin can be found in the LTTng-UST
1520 https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/getcpu-override[`examples/getcpu-override`].
1522 `LTTNG_UST_REGISTER_TIMEOUT`::
1523 Waiting time for the _registration done_ session daemon command
1524 before proceeding to execute the main program (milliseconds).
1526 The value `0` means _do not wait_. The value `-1` means _wait forever_.
1527 Setting this environment variable to `0` is recommended for applications
1528 with time constraints on the process startup time.
1532 `LTTNG_UST_WITHOUT_BADDR_STATEDUMP`::
1533 If set, prevents `liblttng-ust` from performing a base address state
1534 dump (see the <<state-dump,LTTng-UST state dump>> section above).
1536 `LTTNG_UST_WITHOUT_PROCNAME_STATEDUMP`::
1537 If set, prevents `liblttng-ust` from performing a procname state
1538 dump (see the <<state-dump,LTTng-UST state dump>> section above).
1541 include::common-footer.txt[]
1543 include::common-copyrights.txt[]
1545 include::common-authors.txt[]
1550 man:lttng_ust_tracef(3),
1551 man:lttng_ust_tracelog(3),
1552 man:lttng-gen-tp(1),
1553 man:lttng-ust-dl(3),
1554 man:lttng-ust-cyg-profile(3),
1556 man:lttng-enable-event(1),
1558 man:lttng-add-context(1),