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, following this manual page:
87 * If you define `_LGPL_SOURCE` before including
88 `<lttng/tracepoint.h>` (directly or indirectly): `-llttng-ust-common`
93 The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
94 source software package used for correlated tracing of the Linux kernel,
95 user applications, and user libraries.
97 LTTng-UST is the user space tracing component of the LTTng project. It
98 is a port to user space of the low-overhead tracing capabilities of the
99 LTTng Linux kernel tracer. The `liblttng-ust` library is used to trace
100 user applications and libraries.
102 NOTE: This man page is about the `liblttng-ust` library. The LTTng-UST
103 project also provides Java and Python packages to trace applications
104 written in those languages. How to instrument and trace Java and Python
105 applications is documented in
106 http://lttng.org/docs/[the online LTTng documentation].
108 There are three ways to use `liblttng-ust`:
110 * Using the man:lttng_ust_tracef(3) API, which is similar to
112 * Using the man:lttng_ust_tracelog(3) API, which is
113 man:lttng_ust_tracef(3) with a log level parameter.
114 * Defining your own tracepoints. See the
115 <<creating-tp,Creating a tracepoint provider>> section below.
118 Compatibility with previous APIs
119 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
120 Since LTTng-UST{nbsp}2.13, the `LTTNG_UST_COMPAT_API_VERSION` definition
121 controls which LTTng-UST APIs are available (compiled):
124 All APIs are available.
126 'N' (0 or positive integer)::
127 API version{nbsp}__N__, and all the following existing APIs, are
128 available. Previous APIs are not available (not compiled).
130 The following table shows the mapping from LTTng-UST versions (up to
131 LTTng-UST{nbsp}{manversion}) to available API versions:
135 |LTTng-UST version |Available API versions
140 This manual page **only** documents version{nbsp}1 of the API.
142 If you wish to have access to version{nbsp}0 of the API (for example,
143 the `tracepoint()`, `ctf_integer()`, and `TRACEPOINT_EVENT()` macros),
144 then either don't define `LTTNG_UST_COMPAT_API_VERSION`, or define it to
145 `0` before including any LTTng-UST header.
149 Creating a tracepoint provider
150 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
151 Creating a tracepoint provider is the first step of using
152 `liblttng-ust`. The next steps are:
154 * <<tracepoint,Instrumenting your application with
155 `lttng_ust_tracepoint()` calls>>
156 * Building your application with LTTng-UST support, either
157 <<build-static,statically>> or <<build-dynamic,dynamically>>.
159 A *tracepoint provider* is a compiled object containing the event probes
160 corresponding to your custom tracepoint definitions. A tracepoint
161 provider contains the code to get the size of an event and to serialize
162 it, amongst other things.
164 To create a tracepoint provider, start with the following
165 _tracepoint provider header_ template:
167 ------------------------------------------------------------------------
168 #undef LTTNG_UST_TRACEPOINT_PROVIDER
169 #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
171 #undef LTTNG_UST_TRACEPOINT_INCLUDE
172 #define LTTNG_UST_TRACEPOINT_INCLUDE "./tp.h"
174 #if !defined(_TP_H) || \
175 defined(LTTNG_UST_TRACEPOINT_HEADER_MULTI_READ)
178 #include <lttng/tracepoint.h>
181 * LTTNG_UST_TRACEPOINT_EVENT(), LTTNG_UST_TRACEPOINT_EVENT_CLASS(),
182 * LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(),
183 * LTTNG_UST_TRACEPOINT_LOGLEVEL(), and `LTTNG_UST_TRACEPOINT_ENUM()`
189 #include <lttng/tracepoint-event.h>
190 ------------------------------------------------------------------------
192 In this template, the tracepoint provider is named `my_provider`
193 (`LTTNG_UST_TRACEPOINT_PROVIDER` definition). The file needs to bear the
194 name of the `LTTNG_UST_TRACEPOINT_INCLUDE` definition (`tp.h` in this case).
195 Between `#include <lttng/tracepoint.h>` and `#endif` go
196 the invocations of the <<tracepoint-event,`LTTNG_UST_TRACEPOINT_EVENT()`>>,
197 <<tracepoint-event-class,`LTTNG_UST_TRACEPOINT_EVENT_CLASS()`>>,
198 <<tracepoint-event-class,`LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()`>>,
199 <<tracepoint-loglevel,`LTTNG_UST_TRACEPOINT_LOGLEVEL()`>>, and
200 <<tracepoint-enum,`LTTNG_UST_TRACEPOINT_ENUM()`>> macros.
202 NOTE: You can avoid writing the prologue and epilogue boilerplate in the
203 template file above by using the man:lttng-gen-tp(1) tool shipped with
206 The tracepoint provider header file needs to be included in a source
207 file which looks like this:
209 ------------------------------------------------------------------------
210 #define LTTNG_UST_TRACEPOINT_CREATE_PROBES
213 ------------------------------------------------------------------------
215 Together, those two files (let's call them `tp.h` and `tp.c`) form the
216 tracepoint provider sources, ready to be compiled.
218 You can create multiple tracepoint providers to be used in a single
219 application, but each one must have its own header file.
221 The <<tracepoint-event,`LTTNG_UST_TRACEPOINT_EVENT()` usage>> section below
222 shows how to use the `LTTNG_UST_TRACEPOINT_EVENT()` macro to define the actual
223 tracepoints in the tracepoint provider header file.
225 See the <<example,EXAMPLE>> section below for a complete example.
229 `LTTNG_UST_TRACEPOINT_EVENT()` usage
230 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
231 The `LTTNG_UST_TRACEPOINT_EVENT()` macro is used in a template provider
232 header file (see the <<creating-tp,Creating a tracepoint provider>>
233 section above) to define LTTng-UST tracepoints.
235 The `LTTNG_UST_TRACEPOINT_EVENT()` usage template is as follows:
237 ------------------------------------------------------------------------
238 LTTNG_UST_TRACEPOINT_EVENT(
239 /* Tracepoint provider name */
242 /* Tracepoint/event name */
245 /* List of tracepoint arguments (input) */
250 /* List of fields of eventual event (output) */
255 ------------------------------------------------------------------------
257 The `LTTNG_UST_TP_ARGS()` macro contains the input arguments of the tracepoint.
258 Those arguments can be used in the argument expressions of the output
259 fields defined in `LTTNG_UST_TP_FIELDS()`.
261 The format of the `LTTNG_UST_TP_ARGS()` parameters is: C type, then argument name;
262 repeat as needed, up to ten times. For example:
264 ------------------------------------------------------------------------
267 const char *, my_string,
270 struct my_data *, my_data
272 ------------------------------------------------------------------------
274 The `LTTNG_UST_TP_FIELDS()` macro contains the output fields of the tracepoint,
275 that is, the actual data that can be recorded in the payload of an event
276 emitted by this tracepoint.
278 The `LTTNG_UST_TP_FIELDS()` macro contains a list of
279 `lttng_ust_field_*()` macros :not: separated by commas.
280 The available macros are documented in the
281 <<ctf-macros,Available `lttng_ust_field_*()` field type macros>>
286 Available field macros
287 ~~~~~~~~~~~~~~~~~~~~~~
288 This section documents the available `lttng_ust_field_*()` macros that
289 can be inserted in the `LTTNG_UST_TP_FIELDS()` macro of the
290 <<tracepoint-event,`LTTNG_UST_TRACEPOINT_EVENT()` macro>>.
292 Standard integer, displayed in base 10:
295 *lttng_ust_field_integer*('int_type', 'field_name', 'expr')
296 *lttng_ust_field_integer_nowrite*('int_type', 'field_name', 'expr')
298 Standard integer, displayed in base 16:
301 *lttng_ust_field_integer_hex*('int_type', 'field_name', 'expr')
303 Integer in network byte order (big endian), displayed in base 10:
306 *lttng_ust_field_integer_network*('int_type', 'field_name', 'expr')
308 Integer in network byte order, displayed in base 16:
311 *lttng_ust_field_integer_network_hex*('int_type', 'field_name', 'expr')
313 Floating point number:
316 *lttng_ust_field_float*('float_type', 'field_name', 'expr')
317 *lttng_ust_field_float_nowrite*('float_type', 'field_name', 'expr')
319 Null-terminated string:
322 *lttng_ust_field_string*('field_name', 'expr')
323 *lttng_ust_field_string_nowrite*('field_name', 'expr')
325 Statically-sized array of integers (`_hex` versions displayed in
326 hexadecimal, `_network` versions in network byte order):
329 *lttng_ust_field_array*('int_type', 'field_name', 'expr', 'count')
330 *lttng_ust_field_array_nowrite*('int_type', 'field_name', 'expr', 'count')
331 *lttng_ust_field_array_hex*('int_type', 'field_name', 'expr', 'count')
332 *lttng_ust_field_array_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
333 *lttng_ust_field_array_network*('int_type', 'field_name', 'expr', 'count')
334 *lttng_ust_field_array_network_nowrite*('int_type', 'field_name', 'expr',
336 *lttng_ust_field_array_network_hex*('int_type', 'field_name', 'expr', 'count')
337 *lttng_ust_field_array_network_nowrite_hex*('int_type', 'field_name',
340 Statically-sized array, printed as text; no need to be null-terminated:
343 *lttng_ust_field_array_text*(char, 'field_name', 'expr', 'count')
344 *lttng_ust_field_array_text_nowrite*(char, 'field_name', 'expr', 'count')
346 Dynamically-sized array of integers (`_hex` versions displayed in
347 hexadecimal, `_network` versions in network byte order):
350 *lttng_ust_field_sequence*('int_type', 'field_name', 'expr', 'len_type',
352 *lttng_ust_field_sequence_nowrite*('int_type', 'field_name', 'expr',
353 'len_type', 'len_expr')
354 *lttng_ust_field_sequence_hex*('int_type', 'field_name', 'expr', 'len_type',
356 *lttng_ust_field_sequence_nowrite_hex*('int_type', 'field_name', 'expr',
357 'len_type', 'len_expr')
358 *lttng_ust_field_sequence_network*('int_type', 'field_name', 'expr',
359 'len_type', 'len_expr')
360 *lttng_ust_field_sequence_network_nowrite*('int_type', 'field_name', 'expr',
361 'len_type', 'len_expr')
362 *lttng_ust_field_sequence_network_hex*('int_type', 'field_name', 'expr',
363 'len_type', 'len_expr')
364 *lttng_ust_field_sequence_network_nowrite_hex*('int_type', 'field_name',
368 Dynamically-sized array, displayed as text; no need to be null-terminated:
371 *lttng_ust_field_sequence_text*(char, 'field_name', 'expr', 'len_type',
373 *lttng_ust_field_sequence_text_nowrite*(char, 'field_name', 'expr',
374 'len_type', 'len_expr')
376 Enumeration. The enumeration field must be defined before using this
377 macro with the `LTTNG_UST_TRACEPOINT_ENUM()` macro. See the
378 <<tracepoint-enum,`LTTNG_UST_TRACEPOINT_ENUM()` usage>> section for more
382 *lttng_ust_field_enum*('prov_name', 'enum_name', 'int_type', 'field_name',
384 *lttng_ust_field_enum_nowrite*('prov_name', 'enum_name', 'int_type',
385 'field_name', 'expr')
390 Number of elements in array/sequence. This must be known at
394 Name of an enumeration field previously defined with the
395 `LTTNG_UST_TRACEPOINT_ENUM()` macro. See the
396 <<tracepoint-enum,`LTTNG_UST_TRACEPOINT_ENUM()` usage>> section for more
400 C expression resulting in the field's value. This expression can
401 use one or more arguments passed to the tracepoint. The arguments
402 of a given tracepoint are defined in the `LTTNG_UST_TP_ARGS()` macro (see
403 the <<creating-tp,Creating a tracepoint provider>> section above).
406 Event field name (C identifier syntax, :not: a literal string).
409 Float C type (`float` or `double`). The size of this type determines
410 the size of the floating point number field.
413 Integer C type. The size of this type determines the size of the
414 integer/enumeration field.
417 C expression resulting in the sequence's length. This expression
418 can use one or more arguments passed to the tracepoint.
421 Unsigned integer C type of sequence's length.
424 Tracepoint provider name. This must be the same as the tracepoint
425 provider name used in a previous field definition.
427 The `_nowrite` versions omit themselves from the recorded trace, but are
428 otherwise identical. Their primary purpose is to make some of the
429 event context available to the event filters without having to commit
430 the data to sub-buffers. See man:lttng-enable-event(1) to learn more
431 about dynamic event filtering.
433 See the <<example,EXAMPLE>> section below for a complete example.
437 `LTTNG_UST_TRACEPOINT_ENUM()` usage
438 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
439 An enumeration field is a list of mappings between an integers, or a
440 range of integers, and strings (sometimes called _labels_ or
441 _enumerators_). Enumeration fields can be used to have a more compact
442 trace when the possible values for a field are limited.
444 An enumeration field is defined with the `LTTNG_UST_TRACEPOINT_ENUM()`
447 ------------------------------------------------------------------------
448 LTTNG_UST_TRACEPOINT_ENUM(
449 /* Tracepoint provider name */
452 /* Enumeration name (unique in the whole tracepoint provider) */
455 /* Enumeration mappings */
456 LTTNG_UST_TP_ENUM_VALUES(
460 ------------------------------------------------------------------------
462 `LTTNG_UST_TP_ENUM_VALUES()` contains a list of enumeration mappings,
463 :not: separated by commas. Two macros can be used in the
464 `LTTNG_UST_TP_ENUM_VALUES()`: `lttng_ust_field_enum_value()` and
465 `lttng_ust_field_enum_range()`.
467 `lttng_ust_field_enum_value()` is a single value mapping:
470 *lttng_ust_field_enum_value*('label', 'value')
472 This macro maps the given 'label' string to the value 'value'.
474 `lttng_ust_field_enum_range()` is a range mapping:
477 *lttng_ust_field_enum_range*('label', 'start', 'end')
479 This macro maps the given 'label' string to the range of integers from
480 'start' to 'end', inclusively. Range mappings may overlap, but the
481 behaviour is implementation-defined: each trace reader handles
482 overlapping ranges as it wishes.
484 See the <<example,EXAMPLE>> section below for a complete example.
487 [[tracepoint-event-class]]
488 `LTTNG_UST_TRACEPOINT_EVENT_CLASS()` usage
489 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
490 A *tracepoint class* is a class of tracepoints sharing the
491 same field types and names. A tracepoint instance is one instance of
492 such a declared tracepoint class, with its own event name.
494 LTTng-UST creates one event serialization function per tracepoint class.
495 Using `LTTNG_UST_TRACEPOINT_EVENT()` creates one tracepoint class per
496 tracepoint definition, whereas using
497 `LTTNG_UST_TRACEPOINT_EVENT_CLASS()` and
498 `LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()` creates one tracepoint class,
499 and one or more tracepoint instances of this class. In other words, many
500 tracepoints can reuse the same serialization code. Reusing the same
501 code, when possible, can reduce cache pollution, thus improve
504 The `LTTNG_UST_TRACEPOINT_EVENT_CLASS()` macro accepts the same
505 parameters as the `LTTNG_UST_TRACEPOINT_EVENT()` macro, except that
506 instead of an event name, its second parameter is the _tracepoint class
509 ------------------------------------------------------------------------
510 #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
514 LTTNG_UST_TRACEPOINT_EVENT_CLASS(
515 /* Tracepoint class provider name */
518 /* Tracepoint class name */
521 /* List of tracepoint arguments (input) */
526 /* List of fields of eventual event (output) */
531 ------------------------------------------------------------------------
533 Once the tracepoint class is defined, you can create as many tracepoint
536 -------------------------------------------------------------------------
537 #define LTTNG_UST_TRACEPOINT_PROVIDER natality
541 LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
542 /* Name of the tracepoint class provider */
545 /* Tracepoint class name */
548 /* Name of the local (instance) tracepoint provider */
551 /* Tracepoint/event name */
554 /* List of tracepoint arguments (input) */
559 ------------------------------------------------------------------------
561 As you can see, the `LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()` does not
562 contain the `LTTNG_UST_TP_FIELDS()` macro, because they are defined at
563 the `LTTNG_UST_TRACEPOINT_EVENT_CLASS()` level.
565 Note that the `LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()` macro requires two
568 * The name of the tracepoint class provider (`my_provider` in the
571 This is the same as the first argument of the
572 `LTTNG_UST_TRACEPOINT_EVENT_CLASS()` expansion to refer to.
574 * The name of the local, or instance, provider (`natality` in the
577 This is the provider name which becomes the prefix part of the name of
578 the events which such a tracepoint creates.
580 The two provider names may be different if the tracepoint class and the
581 tracepoint instance macros are in two different translation units.
583 See the <<example,EXAMPLE>> section below for a complete example.
586 [[tracepoint-loglevel]]
587 `LTTNG_UST_TRACEPOINT_LOGLEVEL()` usage
588 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
589 Optionally, a *log level* can be assigned to a defined tracepoint.
590 Assigning different levels of severity to tracepoints can be useful:
591 when controlling tracing sessions, you can choose to only enable
592 events falling into a specific log level range using the
593 nloption:--loglevel and nloption:--loglevel-only options of the
594 man:lttng-enable-event(1) command.
596 Log levels are assigned to tracepoints that are already defined using
597 the `LTTNG_UST_TRACEPOINT_LOGLEVEL()` macro. The latter must be used
598 after having used `LTTNG_UST_TRACEPOINT_EVENT()` or
599 `LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()` for a given tracepoint. The
600 `LTTNG_UST_TRACEPOINT_LOGLEVEL()` macro is used as follows:
602 ------------------------------------------------------------------------
603 LTTNG_UST_TRACEPOINT_LOGLEVEL(
604 /* Tracepoint provider name */
607 /* Tracepoint/event name */
611 LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO
613 ------------------------------------------------------------------------
615 The available log level definitions are:
617 include::log-levels.txt[]
619 See the <<example,EXAMPLE>> section below for a complete example.
623 Instrumenting your application
624 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
625 Once the tracepoint provider is created (see the
626 <<creating-tp,Creating a tracepoint provider>> section above), you can
627 instrument your application with the defined tracepoints thanks to the
628 `lttng_ust_tracepoint()` macro:
631 #define *lttng_ust_tracepoint*('prov_name', 't_name', ...)
636 Tracepoint provider name.
639 Tracepoint/event name.
642 Tracepoint arguments, if any.
644 Make sure to include the tracepoint provider header file anywhere you
645 use `lttng_ust_tracepoint()` for this provider.
647 NOTE: Even though LTTng-UST supports `lttng_ust_tracepoint()` call site
648 duplicates having the same provider and tracepoint names, it is
649 recommended to use a provider/tracepoint name pair only once within the
650 application source code to help map events back to their call sites when
653 Sometimes, arguments to the tracepoint are expensive to compute (take
654 call stack, for example). To avoid the computation when the tracepoint
655 is disabled, you can use the `lttng_ust_tracepoint_enabled()` and
656 `lttng_ust_do_tracepoint()` macros:
659 #define *lttng_ust_tracepoint_enabled*('prov_name', 't_name')
660 #define *lttng_ust_do_tracepoint*('prov_name', 't_name', ...)
662 `lttng_ust_tracepoint_enabled()` returns a non-zero value if the tracepoint
663 named 't_name' from the provider named 'prov_name' is enabled at
666 `lttng_ust_do_tracepoint()` is like `lttng_ust_tracepoint()`, except that it doesn't check
667 if the tracepoint is enabled. Using `lttng_ust_tracepoint()` with
668 `lttng_ust_tracepoint_enabled()` is dangerous since `lttng_ust_tracepoint()` also contains
669 the `lttng_ust_tracepoint_enabled()` check, thus a race condition is possible
672 ------------------------------------------------------------------------
673 if (lttng_ust_tracepoint_enabled(my_provider, my_tracepoint)) {
674 stuff = prepare_stuff();
677 lttng_ust_tracepoint(my_provider, my_tracepoint, stuff);
678 ------------------------------------------------------------------------
680 If the tracepoint is enabled after the condition, then `stuff` is not
681 prepared: the emitted event will either contain wrong data, or the
682 whole application could crash (segmentation fault, for example).
684 NOTE: Neither `lttng_ust_tracepoint_enabled()` nor
685 `lttng_ust_do_tracepoint()` have a `STAP_PROBEV()` call, so if you need
686 it, you should emit this call yourself.
690 Statically linking the tracepoint provider
691 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
692 With the static linking method, compiled tracepoint providers are copied
693 into the target application.
695 Define `LTTNG_UST_TRACEPOINT_DEFINE` definition below the
696 `LTTNG_UST_TRACEPOINT_CREATE_PROBES` definition in the tracepoint
699 ------------------------------------------------------------------------
700 #define LTTNG_UST_TRACEPOINT_CREATE_PROBES
701 #define LTTNG_UST_TRACEPOINT_DEFINE
704 ------------------------------------------------------------------------
706 Create the tracepoint provider object file:
713 NOTE: Although an application instrumented with LTTng-UST tracepoints
714 can be compiled with a $$C++$$ compiler, tracepoint probes
715 should be compiled with a C compiler.
717 At this point, you _can_ archive this tracepoint provider object file,
718 possibly with other object files of your application or with other
719 tracepoint provider object files, as a static library:
726 Using a static library does have the advantage of centralising the
727 tracepoint providers objects so they can be shared between multiple
728 applications. This way, when the tracepoint provider is modified, the
729 source code changes don't have to be patched into each application's
730 source code tree. The applications need to be relinked after each
731 change, but need not to be otherwise recompiled (unless the tracepoint
732 provider's API changes).
734 Then, link your application with this object file (or with the static
735 library containing it) and with `liblttng-ust` and `libdl` (`libc` on a
740 $ cc -o app tp.o app.o -llttng-ust -ldl
745 Dynamically loading the tracepoint provider
746 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
747 The second approach to package the tracepoint provider is to use the
748 dynamic loader: the library and its member functions are explicitly
749 sought, loaded at run time.
751 In this scenario, the tracepoint provider is compiled as a shared
754 The process to create the tracepoint provider shared object is pretty
755 much the same as the <<build-static,static linking method>>, except
758 * Since the tracepoint provider is not part of the application,
759 `LTTNG_UST_TRACEPOINT_DEFINE` must be defined, for each tracepoint
760 provider, in exactly one source file of the _application_
761 * `LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next to
762 `LTTNG_UST_TRACEPOINT_DEFINE`
764 Regarding `LTTNG_UST_TRACEPOINT_DEFINE` and
765 `LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE`, the recommended practice
766 is to use a separate C source file in your application to define them,
767 then include the tracepoint provider header files afterwards. For
768 example, as `tp-define.c`:
770 ------------------------------------------------------------------------
771 #define LTTNG_UST_TRACEPOINT_DEFINE
772 #define LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE
775 ------------------------------------------------------------------------
777 The tracepoint provider object file used to create the shared library is
778 built like it is using the static linking method, but with the
779 nloption:-fpic option:
783 $ cc -c -fpic -I. tp.c
786 It is then linked as a shared library like this:
790 $ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
793 This tracepoint provider shared object isn't linked with the user
794 application: it must be loaded manually. This is why the application is
795 built with no mention of this tracepoint provider, but still needs
800 $ cc -o app app.o tp-define.o -ldl
803 There are two ways to dynamically load the tracepoint provider shared
806 * Load it manually from the application using man:dlopen(3)
807 * Make the dynamic loader load it with the `LD_PRELOAD`
808 environment variable (see man:ld.so(8))
810 If the application does not dynamically load the tracepoint provider
811 shared object using one of the methods above, tracing is disabled for
812 this application, and the events are not listed in the output of
815 Note that it is not safe to use man:dlclose(3) on a tracepoint provider
816 shared object that is being actively used for tracing, due to a lack of
817 reference counting from LTTng-UST to the shared object.
819 For example, statically linking a tracepoint provider to a shared object
820 which is to be dynamically loaded by an application (a plugin, for
821 example) is not safe: the shared object, which contains the tracepoint
822 provider, could be dynamically closed (man:dlclose(3)) at any time by
825 To instrument a shared object, either:
827 * Statically link the tracepoint provider to the application, or
828 * Build the tracepoint provider as a shared object (following the
829 procedure shown in this section), and preload it when tracing is
830 needed using the `LD_PRELOAD` environment variable.
833 Using LTTng-UST with daemons
834 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
835 Some extra care is needed when using `liblttng-ust` with daemon
836 applications that call man:fork(2), man:clone(2), or BSD's man:rfork(2)
837 without a following man:exec(3) family system call. The library
838 `liblttng-ust-fork.so` needs to be preloaded before starting the
839 application with the `LD_PRELOAD` environment variable (see
842 To use `liblttng-ust` with a daemon application which closes file
843 descriptors that were not opened by it, preload the `liblttng-ust-fd.so`
844 library before you start the application. Typical use cases include
845 daemons closing all file descriptors after man:fork(2), and buggy
846 applications doing ``double-closes''.
851 Context information can be prepended by the LTTng-UST tracer before
852 each event, or before specific events.
854 Context fields can be added to specific channels using
855 man:lttng-add-context(1).
857 The following context fields are supported by LTTng-UST:
859 General context fields::
864 NOTE: This context field is always enabled, and it cannot be added
865 with man:lttng-add-context(1). Its main purpose is to be used for
866 dynamic event filtering. See man:lttng-enable-event(1) for more
867 information about event filtering.
870 Instruction pointer: enables recording the exact address from which
871 an event was emitted. This context field can be used to
872 reverse-lookup the source location that caused the event
876 POSIX thread identifier.
878 Can be used on architectures where `pthread_t` maps nicely to an
879 `unsigned long` type.
881 Process context fields::
884 Thread name, as set by man:exec(3) or man:prctl(2). It is
885 recommended that programs set their thread name with man:prctl(2)
886 before hitting the first tracepoint for that thread.
889 Virtual process ID: process ID as seen from the point of view of the
890 current process ID namespace (see man:pid_namespaces(7)).
893 Virtual thread ID: thread ID as seen from the point of view of the
894 current process ID namespace (see man:pid_namespaces(7)).
896 perf context fields::
898 `perf:thread:COUNTER`:::
899 perf counter named 'COUNTER'. Use `lttng add-context --list` to
900 list the available perf counters.
902 Only available on IA-32 and x86-64 architectures.
904 `perf:thread:raw:rN:NAME`:::
905 perf counter with raw ID 'N' and custom name 'NAME'. See
906 man:lttng-add-context(1) for more details.
908 Namespace context fields (see man:namespaces(7))::
911 Inode number of the current control group namespace (see
912 man:cgroup_namespaces(7)) in the proc file system.
915 Inode number of the current IPC namespace (see
916 man:ipc_namespaces(7)) in the proc file system.
919 Inode number of the current mount point namespace (see
920 man:mount_namespaces(7)) in the proc file system.
923 Inode number of the current network namespace (see
924 man:network_namespaces(7)) in the proc file system.
927 Inode number of the current process ID namespace (see
928 man:pid_namespaces(7)) in the proc file system.
931 Inode number of the current clock namespace (see
932 man:time_namespaces(7)) in the proc file system.
935 Inode number of the current user namespace (see
936 man:user_namespaces(7)) in the proc file system.
939 Inode number of the current UTS namespace (see
940 man:uts_namespaces(7)) in the proc file system.
942 Credential context fields (see man:credentials(7))::
945 Virtual real user ID: real user ID as seen from the point of view of
946 the current user namespace (see man:user_namespaces(7)).
949 Virtual real group ID: real group ID as seen from the point of view
950 of the current user namespace (see man:user_namespaces(7)).
953 Virtual effective user ID: effective user ID as seen from the point
954 of view of the current user namespace (see man:user_namespaces(7)).
957 Virtual effective group ID: effective group ID as seen from the
958 point of view of the current user namespace (see
959 man:user_namespaces(7)).
962 Virtual saved set-user ID: saved set-user ID as seen from the point
963 of view of the current user namespace (see man:user_namespaces(7)).
966 Virtual saved set-group ID: saved set-group ID as seen from the
967 point of view of the current user namespace (see
968 man:user_namespaces(7)).
974 If an application that uses `liblttng-ust` becomes part of a tracing
975 session, information about its currently loaded shared objects, their
976 build IDs, and their debug link information are emitted as events
979 The following LTTng-UST state dump events exist and must be enabled
980 to record application state dumps. Note that, during the state dump
981 phase, LTTng-UST can also emit _shared library load/unload_ events
982 (see <<ust-lib,Shared library load/unload tracking>> below).
984 `lttng_ust_statedump:start`::
985 Emitted when the state dump begins.
987 This event has no fields.
989 `lttng_ust_statedump:end`::
990 Emitted when the state dump ends. Once this event is emitted, it
991 is guaranteed that, for a given process, the state dump is
994 This event has no fields.
996 `lttng_ust_statedump:bin_info`::
997 Emitted when information about a currently loaded executable or
998 shared object is found.
1004 |Field name |Description
1007 |Base address of loaded executable.
1010 |Size of loaded executable in memory.
1013 |Path to loaded executable file.
1016 |Whether or not the executable is position-independent code.
1019 |Whether or not the executable has a build ID. If this field is 1, you
1020 can expect that an `lttng_ust_statedump:build_id` event record follows
1021 this one (not necessarily immediately after).
1024 |Whether or not the executable has debug link information. If this field
1025 is 1, you can expect that an `lttng_ust_statedump:debug_link` event
1026 record follows this one (not necessarily immediately after).
1029 `lttng_ust_statedump:build_id`::
1030 Emitted when a build ID is found in a currently loaded shared
1032 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1033 for more information about build IDs.
1039 |Field name |Description
1042 |Base address of loaded library.
1048 `lttng_ust_statedump:debug_link`::
1049 Emitted when debug link information is found in a currently loaded
1051 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1052 for more information about debug links.
1058 |Field name |Description
1061 |Base address of loaded library.
1064 |Debug link file's CRC.
1067 |Debug link file name.
1070 `lttng_ust_statedump:procname`::
1071 The process procname at process start.
1077 |Field name |Description
1086 Shared library load/unload tracking
1087 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1088 The <<state-dump,LTTng-UST state dump>> and the LTTng-UST helper library
1089 to instrument the dynamic linker (see man:liblttng-ust-dl(3)) can emit
1090 **shared library load/unload tracking** events.
1092 The following shared library load/unload tracking events exist and must
1093 be enabled to track the loading and unloading of shared libraries:
1095 `lttng_ust_lib:load`::
1096 Emitted when a shared library (shared object) is loaded.
1102 |Field name |Description
1105 |Base address of loaded library.
1108 |Size of loaded library in memory.
1111 |Path to loaded library file.
1114 |Whether or not the library has a build ID. If this field is 1, you
1115 can expect that an `lttng_ust_lib:build_id` event record follows
1116 this one (not necessarily immediately after).
1119 |Whether or not the library has debug link information. If this field
1120 is 1, you can expect that an `lttng_ust_lib:debug_link` event
1121 record follows this one (not necessarily immediately after).
1124 `lttng_ust_lib:unload`::
1125 Emitted when a shared library (shared object) is unloaded.
1131 |Field name |Description
1134 |Base address of unloaded library.
1137 `lttng_ust_lib:build_id`::
1138 Emitted when a build ID is found in a loaded shared library (shared
1140 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1141 for more information about build IDs.
1147 |Field name |Description
1150 |Base address of loaded library.
1156 `lttng_ust_lib:debug_link`::
1157 Emitted when debug link information is found in a loaded
1158 shared library (shared object). See
1159 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1160 for more information about debug links.
1166 |Field name |Description
1169 |Base address of loaded library.
1172 |Debug link file's CRC.
1175 |Debug link file name.
1179 Detect if LTTng-UST is loaded
1180 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1181 To detect if `liblttng-ust` is loaded from an application:
1183 . Define the `lttng_ust_loaded` weak symbol globally:
1185 ------------------------------------------------------------------------
1186 int lttng_ust_loaded __attribute__((weak));
1187 ------------------------------------------------------------------------
1189 This weak symbol is set by the constructor of `liblttng-ust`.
1191 . Test `lttng_ust_loaded` where needed:
1193 ------------------------------------------------------------------------
1196 if (lttng_ust_loaded) {
1197 /* LTTng-UST is loaded */
1199 /* LTTng-UST is NOT loaded */
1203 ------------------------------------------------------------------------
1209 NOTE: A few examples are available in the
1210 https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples[`doc/examples`]
1211 directory of LTTng-UST's source tree.
1213 This example shows all the features documented in the previous
1214 sections. The <<build-static,static linking>> method is chosen here
1215 to link the application with the tracepoint provider.
1217 You can compile the source files and link them together statically
1224 $ cc -o app tp.o app.o -llttng-ust -ldl
1227 Using the man:lttng(1) tool, create an LTTng tracing session, enable
1228 all the events of this tracepoint provider, and start tracing:
1232 $ lttng create my-session
1233 $ lttng enable-event --userspace 'my_provider:*'
1237 You may also enable specific events:
1241 $ lttng enable-event --userspace my_provider:big_event
1242 $ lttng enable-event --userspace my_provider:event_instance2
1245 Run the application:
1249 $ ./app some arguments
1252 Stop the current tracing session and inspect the recorded events:
1261 Tracepoint provider header file
1262 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1265 ------------------------------------------------------------------------
1266 #undef LTTNG_UST_TRACEPOINT_PROVIDER
1267 #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
1269 #undef LTTNG_USTTRACEPOINT_INCLUDE
1270 #define LTTNG_USTTRACEPOINT_INCLUDE "./tp.h"
1272 #if !defined(_TP_H) || \
1273 defined(LTTNG_UST_TRACEPOINT_HEADER_MULTI_READ)
1276 #include <lttng/tracepoint.h>
1281 LTTNG_UST_TRACEPOINT_EVENT(
1285 int, my_integer_arg,
1286 const char *, my_string_arg
1288 LTTNG_UST_TP_FIELDS(
1289 lttng_ust_field_string(argc, my_string_arg)
1290 lttng_ust_field_integer(int, argv, my_integer_arg)
1294 LTTNG_UST_TRACEPOINT_ENUM(
1297 LTTNG_UST_TP_ENUM_VALUES(
1298 lttng_ust_field_enum_value("ZERO", 0)
1299 lttng_ust_field_enum_value("ONE", 1)
1300 lttng_ust_field_enum_value("TWO", 2)
1301 lttng_ust_field_enum_range("A RANGE", 52, 125)
1302 lttng_ust_field_enum_value("ONE THOUSAND", 1000)
1306 LTTNG_UST_TRACEPOINT_EVENT(
1310 int, my_integer_arg,
1311 const char *, my_string_arg,
1316 LTTNG_UST_TP_FIELDS(
1317 lttng_ust_field_integer(int, int_field1, my_integer_arg * 2)
1318 lttng_ust_field_integer_hex(long int, stream_pos,
1320 lttng_ust_field_float(double, float_field, flt_arg)
1321 lttng_ust_field_string(string_field, my_string_arg)
1322 lttng_ust_field_array(int, array_field, array_arg, 7)
1323 lttng_ust_field_array_text(char, array_text_field,
1325 lttng_ust_field_sequence(int, seq_field, array_arg, int,
1326 my_integer_arg / 10)
1327 lttng_ust_field_sequence_text(char, seq_text_field,
1330 lttng_ust_field_enum(my_provider, my_enum, int,
1331 enum_field, array_arg[1])
1335 LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, big_event,
1336 LTTNG_UST_TRACEPOINT_LOGLEVEL_WARNING)
1338 LTTNG_UST_TRACEPOINT_EVENT_CLASS(
1340 my_tracepoint_class,
1342 int, my_integer_arg,
1343 struct app_struct *, app_struct_arg
1345 LTTNG_UST_TP_FIELDS(
1346 lttng_ust_field_integer(int, a, my_integer_arg)
1347 lttng_ust_field_integer(unsigned long, b, app_struct_arg->b)
1348 lttng_ust_field_string(c, app_struct_arg->c)
1352 LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
1354 my_tracepoint_class,
1358 int, my_integer_arg,
1359 struct app_struct *, app_struct_arg
1363 LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
1365 my_tracepoint_class,
1369 int, my_integer_arg,
1370 struct app_struct *, app_struct_arg
1374 LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, event_instance2,
1375 LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO)
1377 LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
1379 my_tracepoint_class,
1383 int, my_integer_arg,
1384 struct app_struct *, app_struct_arg
1390 #include <lttng/tracepoint-event.h>
1391 ------------------------------------------------------------------------
1394 Tracepoint provider source file
1395 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1398 ------------------------------------------------------------------------
1399 #define LTTNG_UST_TRACEPOINT_CREATE_PROBES
1400 #define LTTNG_UST_TRACEPOINT_DEFINE
1403 ------------------------------------------------------------------------
1406 Application header file
1407 ~~~~~~~~~~~~~~~~~~~~~~~
1410 ------------------------------------------------------------------------
1421 ------------------------------------------------------------------------
1424 Application source file
1425 ~~~~~~~~~~~~~~~~~~~~~~~
1428 ------------------------------------------------------------------------
1435 static int array_of_ints[] = {
1436 100, -35, 1, 23, 14, -6, 28, 1001, -3000,
1439 int main(int argc, char* argv[])
1442 struct app_struct app_struct;
1444 lttng_ust_tracepoint(my_provider, simple_event, argc, argv[0]);
1445 stream = fopen("/tmp/app.txt", "w");
1449 "Error: Cannot open /tmp/app.txt for writing\n");
1450 return EXIT_FAILURE;
1453 if (fprintf(stream, "0123456789") != 10) {
1455 fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
1456 return EXIT_FAILURE;
1459 lttng_ust_tracepoint(my_provider, big_event, 35,
1460 "hello tracepoint", stream, -3.14,
1463 app_struct.b = argc;
1464 app_struct.c = "[the string]";
1465 lttng_ust_tracepoint(my_provider, event_instance1, 23,
1467 app_struct.b = argc * 5;
1468 app_struct.c = "[other string]";
1469 lttng_ust_tracepoint(my_provider, event_instance2, 17,
1472 app_struct.c = "nothing";
1473 lttng_ust_tracepoint(my_provider, event_instance3, -52,
1475 return EXIT_SUCCESS;
1477 ------------------------------------------------------------------------
1480 ENVIRONMENT VARIABLES
1481 ---------------------
1483 Alternative user's home directory. This variable is useful when the
1484 user running the instrumented application has a non-writable home
1487 Unix sockets used for the communication between `liblttng-ust` and the
1488 LTTng session and consumer daemons (part of the LTTng-tools project)
1489 are located in a specific directory under `$LTTNG_HOME` (or `$HOME` if
1490 `$LTTNG_HOME` is not set).
1492 `LTTNG_UST_ALLOW_BLOCKING`::
1493 If set, allow the application to retry event tracing when there's
1494 no space left for the event record in the sub-buffer, therefore
1495 effectively blocking the application until space is made available
1496 or the configured timeout is reached.
1498 To allow an application to block during tracing, you also need to
1499 specify a blocking timeout when you create a channel with the
1500 nloption:--blocking-timeout option of the man:lttng-enable-channel(1)
1503 This option can be useful in workloads generating very large trace data
1504 throughput, where blocking the application is an acceptable trade-off to
1505 prevent discarding event records.
1507 WARNING: Setting this environment variable may significantly
1508 affect application timings.
1510 `LTTNG_UST_CLOCK_PLUGIN`::
1511 Path to the shared object which acts as the clock override plugin.
1512 An example of such a plugin can be found in the LTTng-UST
1514 https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/clock-override[`examples/clock-override`].
1517 If set, enable `liblttng-ust`'s debug and error output.
1519 `LTTNG_UST_GETCPU_PLUGIN`::
1520 Path to the shared object which acts as the `getcpu()` override
1521 plugin. An example of such a plugin can be found in the LTTng-UST
1523 https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/getcpu-override[`examples/getcpu-override`].
1525 `LTTNG_UST_REGISTER_TIMEOUT`::
1526 Waiting time for the _registration done_ session daemon command
1527 before proceeding to execute the main program (milliseconds).
1529 The value `0` means _do not wait_. The value `-1` means _wait forever_.
1530 Setting this environment variable to `0` is recommended for applications
1531 with time constraints on the process startup time.
1535 `LTTNG_UST_WITHOUT_BADDR_STATEDUMP`::
1536 If set, prevents `liblttng-ust` from performing a base address state
1537 dump (see the <<state-dump,LTTng-UST state dump>> section above).
1539 `LTTNG_UST_WITHOUT_PROCNAME_STATEDUMP`::
1540 If set, prevents `liblttng-ust` from performing a procname state
1541 dump (see the <<state-dump,LTTng-UST state dump>> section above).
1544 include::common-footer.txt[]
1546 include::common-copyrights.txt[]
1548 include::common-authors.txt[]
1553 man:lttng_ust_tracef(3),
1554 man:lttng_ust_tracelog(3),
1555 man:lttng-gen-tp(1),
1556 man:lttng-ust-dl(3),
1557 man:lttng-ust-cyg-profile(3),
1559 man:lttng-enable-event(1),
1561 man:lttng-add-context(1),