8 lttng-ust - LTTng user space tracing
14 *#include <lttng/tracepoint.h>*
17 #define *TRACEPOINT_ENUM*('prov_name', 'enum_name', 'mappings')
18 #define *TRACEPOINT_EVENT*('prov_name', 't_name', 'args', 'fields')
19 #define *TRACEPOINT_EVENT_CLASS*('prov_name', 'class_name',
21 #define *TRACEPOINT_EVENT_INSTANCE*('prov_name', 'class_name',
23 #define *TRACEPOINT_LOGLEVEL*('prov_name', 't_name', 'level')
24 #define *ctf_array*('int_type', 'field_name', 'expr', 'count')
25 #define *ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count')
26 #define *ctf_array_hex*('int_type', 'field_name', 'expr', 'count')
27 #define *ctf_array_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
28 #define *ctf_array_network*('int_type', 'field_name', 'expr', 'count')
29 #define *ctf_array_network_nowrite*('int_type', 'field_name', 'expr', 'count')
30 #define *ctf_array_network_hex*('int_type', 'field_name', 'expr', 'count')
31 #define *ctf_array_network_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
32 #define *ctf_array_text*(char, 'field_name', 'expr', 'count')
33 #define *ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count')
34 #define *ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
35 #define *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type',
37 #define *ctf_enum_value*('label', 'value')
38 #define *ctf_enum_range*('label', 'start', 'end')
39 #define *ctf_float*('float_type', 'field_name', 'expr')
40 #define *ctf_float_nowrite*('float_type', 'field_name', 'expr')
41 #define *ctf_integer*('int_type', 'field_name', 'expr')
42 #define *ctf_integer_hex*('int_type', 'field_name', 'expr')
43 #define *ctf_integer_network*('int_type', 'field_name', 'expr')
44 #define *ctf_integer_network_hex*('int_type', 'field_name', 'expr')
45 #define *ctf_integer_nowrite*('int_type', 'field_name', 'expr')
46 #define *ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
47 #define *ctf_sequence_nowrite*('int_type', 'field_name', 'expr', 'len_type',
49 #define *ctf_sequence_hex*('int_type', 'field_name', 'expr', 'len_type',
51 #define *ctf_sequence_nowrite_hex*('int_type', 'field_name', 'expr', 'len_type',
53 #define *ctf_sequence_network*('int_type', 'field_name', 'expr', 'len_type',
55 #define *ctf_sequence_network_nowrite*('int_type', 'field_name', 'expr',
56 'len_type', 'len_expr')
57 #define *ctf_sequence_network_hex*('int_type', 'field_name', 'expr', 'len_type',
59 #define *ctf_sequence_network_nowrite_hex*('int_type', 'field_name', 'expr',
60 'len_type', 'len_expr')
61 #define *ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr')
62 #define *ctf_sequence_text_nowrite*(char, 'field_name', 'expr',
63 'len_type', 'len_expr')
64 #define *ctf_string*('field_name', 'expr')
65 #define *ctf_string_nowrite*('field_name', 'expr')
66 #define *do_tracepoint*('prov_name', 't_name', ...)
67 #define *tracepoint*('prov_name', 't_name', ...)
68 #define *tracepoint_enabled*('prov_name', 't_name')
70 Link with `-llttng-ust -ldl`, following this man page.
75 The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
76 source software package used for correlated tracing of the Linux kernel,
77 user applications, and user libraries.
79 LTTng-UST is the user space tracing component of the LTTng project. It
80 is a port to user space of the low-overhead tracing capabilities of the
81 LTTng Linux kernel tracer. The `liblttng-ust` library is used to trace
82 user applications and libraries.
84 NOTE: This man page is about the `liblttng-ust` library. The LTTng-UST
85 project also provides Java and Python packages to trace applications
86 written in those languages. How to instrument and trace Java and Python
87 applications is documented in
88 http://lttng.org/docs/[the online LTTng documentation].
90 There are three ways to use `liblttng-ust`:
92 * Using the man:tracef(3) API, which is similar to man:printf(3).
93 * Using the man:tracelog(3) API, which is man:tracef(3) with
94 a log level parameter.
95 * Defining your own tracepoints. See the
96 <<creating-tp,Creating a tracepoint provider>> section below.
100 Creating a tracepoint provider
101 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102 Creating a tracepoint provider is the first step of using
103 `liblttng-ust`. The next steps are:
105 * <<tracepoint,Instrumenting your application with `tracepoint()` calls>>
106 * Building your application with LTTng-UST support, either
107 <<build-static,statically>> or <<build-dynamic,dynamically>>.
109 A *tracepoint provider* is a compiled object containing the event
110 probes corresponding to your custom tracepoint definitions. A tracepoint
111 provider contains the code to get the size of an event and to serialize
112 it, amongst other things.
114 To create a tracepoint provider, start with the following
115 _tracepoint provider header_ template:
117 ------------------------------------------------------------------------
118 #undef TRACEPOINT_PROVIDER
119 #define TRACEPOINT_PROVIDER my_provider
121 #undef TRACEPOINT_INCLUDE
122 #define TRACEPOINT_INCLUDE "./tp.h"
124 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
127 #include <lttng/tracepoint.h>
130 * TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
131 * TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(),
132 * and `TRACEPOINT_ENUM()` are used here.
137 #include <lttng/tracepoint-event.h>
138 ------------------------------------------------------------------------
140 In this template, the tracepoint provider is named `my_provider`
141 (`TRACEPOINT_PROVIDER` definition). The file needs to bear the
142 name of the `TRACEPOINT_INCLUDE` definition (`tp.h` in this case).
143 Between `#include <lttng/tracepoint.h>` and `#endif` go
144 the invocations of the <<tracepoint-event,`TRACEPOINT_EVENT()`>>,
145 <<tracepoint-event-class,`TRACEPOINT_EVENT_CLASS()`>>,
146 <<tracepoint-event-class,`TRACEPOINT_EVENT_INSTANCE()`>>,
147 <<tracepoint-loglevel,`TRACEPOINT_LOGLEVEL()`>>, and
148 <<tracepoint-enum,`TRACEPOINT_ENUM()`>> macros.
150 NOTE: You can avoid writing the prologue and epilogue boilerplate in the
151 template file above by using the man:lttng-gen-tp(1) tool shipped with
154 The tracepoint provider header file needs to be included in a source
155 file which looks like this:
157 ------------------------------------------------------------------------
158 #define TRACEPOINT_CREATE_PROBES
161 ------------------------------------------------------------------------
163 Together, those two files (let's call them `tp.h` and `tp.c`) form the
164 tracepoint provider sources, ready to be compiled.
166 You can create multiple tracepoint providers to be used in a single
167 application, but each one must have its own header file.
169 The <<tracepoint-event,`TRACEPOINT_EVENT()` usage>> section below
170 shows how to use the `TRACEPOINT_EVENT()` macro to define the actual
171 tracepoints in the tracepoint provider header file.
173 See the <<example,EXAMPLE>> section below for a complete example.
177 `TRACEPOINT_EVENT()` usage
178 ~~~~~~~~~~~~~~~~~~~~~~~~~~
179 The `TRACEPOINT_EVENT()` macro is used in a template provider
180 header file (see the <<creating-tp,Creating a tracepoint provider>>
181 section above) to define LTTng-UST tracepoints.
183 The `TRACEPOINT_EVENT()` usage template is as follows:
185 ------------------------------------------------------------------------
187 /* Tracepoint provider name */
190 /* Tracepoint/event name */
193 /* List of tracepoint arguments (input) */
198 /* List of fields of eventual event (output) */
203 ------------------------------------------------------------------------
205 The `TP_ARGS()` macro contains the input arguments of the tracepoint.
206 Those arguments can be used in the argument expressions of the output
207 fields defined in `TP_FIELDS()`.
209 The format of the `TP_ARGS()` parameters is: C type, then argument name;
210 repeat as needed, up to ten times. For example:
212 ------------------------------------------------------------------------
215 const char *, my_string,
218 struct my_data *, my_data
220 ------------------------------------------------------------------------
222 The `TP_FIELDS()` macro contains the output fields of the tracepoint,
223 that is, the actual data that can be recorded in the payload of an
224 event emitted by this tracepoint.
226 The `TP_FIELDS()` macro contains a list of `ctf_*()` macros
227 :not: separated by commas. The available macros are documented in the
228 <<ctf-macros,Available `ctf_*()` field type macros>> section below.
232 Available `ctf_*()` field type macros
233 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
234 This section documents the available `ctf_*()` macros that can be
235 inserted in the `TP_FIELDS()` macro of the
236 <<tracepoint-event,`TRACEPOINT_EVENT()` macro>>.
238 Standard integer, displayed in base 10:
241 *ctf_integer*('int_type', 'field_name', 'expr')
242 *ctf_integer_nowrite*('int_type', 'field_name', 'expr')
244 Standard integer, displayed in base 16:
247 *ctf_integer_hex*('int_type', 'field_name', 'expr')
249 Integer in network byte order (big endian), displayed in base 10:
252 *ctf_integer_network*('int_type', 'field_name', 'expr')
254 Integer in network byte order, displayed in base 16:
257 *ctf_integer_network_hex*('int_type', 'field_name', 'expr')
259 Floating point number:
262 *ctf_float*('float_type', 'field_name', 'expr')
263 *ctf_float_nowrite*('float_type', 'field_name', 'expr')
265 Null-terminated string:
268 *ctf_string*('field_name', 'expr')
269 *ctf_string_nowrite*('field_name', 'expr')
271 Statically-sized array of integers (`_hex` versions displayed in
272 hexadecimal, `_network` versions in network byte order):
275 *ctf_array*('int_type', 'field_name', 'expr', 'count')
276 *ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count')
277 *ctf_array_hex*('int_type', 'field_name', 'expr', 'count')
278 *ctf_array_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
279 *ctf_array_network*('int_type', 'field_name', 'expr', 'count')
280 *ctf_array_network_nowrite*('int_type', 'field_name', 'expr', 'count')
281 *ctf_array_network_hex*('int_type', 'field_name', 'expr', 'count')
282 *ctf_array_network_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
284 Statically-sized array, printed as text; no need to be null-terminated:
287 *ctf_array_text*(char, 'field_name', 'expr', 'count')
288 *ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count')
290 Dynamically-sized array of integers (`_hex` versions displayed in
291 hexadecimal, `_network` versions in network byte order):
294 *ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
295 *ctf_sequence_nowrite*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
296 *ctf_sequence_hex*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
297 *ctf_sequence_nowrite_hex*('int_type', 'field_name', 'expr', 'len_type',
299 *ctf_sequence_network*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
300 *ctf_sequence_network_nowrite*('int_type', 'field_name', 'expr', 'len_type',
302 *ctf_sequence_network_hex*('int_type', 'field_name', 'expr', 'len_type',
304 *ctf_sequence_network_nowrite_hex*('int_type', 'field_name', 'expr', 'len_type',
307 Dynamically-sized array, displayed as text; no need to be null-terminated:
310 *ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr')
311 *ctf_sequence_text_nowrite*(char, 'field_name', 'expr', 'len_type', 'len_expr')
313 Enumeration. The enumeration field must be defined before using this
314 macro with the `TRACEPOINT_ENUM()` macro. See the
315 <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more
319 *ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
320 *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
325 Integer C type. The size of this type determines the size of the
326 integer/enumeration field.
329 Float C type (`float` or `double`). The size of this type determines
330 the size of the floating point number field.
333 Event field name (C identifier syntax, :not: a literal string).
336 C expression resulting in the field's value. This expression can
337 use one or more arguments passed to the tracepoint. The arguments
338 of a given tracepoint are defined in the `TP_ARGS()` macro (see
339 the <<creating-tp,Creating a tracepoint provider>> section above).
342 Number of elements in array/sequence. This must be known at
346 Unsigned integer C type of sequence's length.
349 C expression resulting in the sequence's length. This expression
350 can use one or more arguments passed to the tracepoint.
353 Tracepoint provider name. This must be the same as the tracepoint
354 provider name used in a previous field definition.
357 Name of an enumeration field previously defined with the
358 `TRACEPOINT_ENUM()` macro. See the
359 <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more
362 The `_nowrite` versions omit themselves from the recorded trace, but are
363 otherwise identical. Their primary purpose is to make some of the
364 event context available to the event filters without having to commit
365 the data to sub-buffers. See man:lttng-enable-event(1) to learn more
366 about dynamic event filtering.
368 See the <<example,EXAMPLE>> section below for a complete example.
372 `TRACEPOINT_ENUM()` usage
373 ~~~~~~~~~~~~~~~~~~~~~~~~~
374 An enumeration field is a list of mappings between an integers, or a
375 range of integers, and strings (sometimes called _labels_ or
376 _enumerators_). Enumeration fields can be used to have a more compact
377 trace when the possible values for a field are limited.
379 An enumeration field is defined with the `TRACEPOINT_ENUM()` macro:
381 ------------------------------------------------------------------------
383 /* Tracepoint provider name */
386 /* Enumeration name (unique in the whole tracepoint provider) */
389 /* Enumeration mappings */
394 ------------------------------------------------------------------------
396 `TP_ENUM_VALUES()` contains a list of enumeration mappings, :not:
397 separated by commas. Two macros can be used in the `TP_ENUM_VALUES()`:
398 `ctf_enum_value()` and `ctf_enum_range()`.
400 `ctf_enum_value()` is a single value mapping:
403 *ctf_enum_value*('label', 'value')
405 This macro maps the given 'label' string to the value 'value'.
407 `ctf_enum_range()` is a range mapping:
410 *ctf_enum_range*('label', 'start', 'end')
412 This macro maps the given 'label' string to the range of integers from
413 'start' to 'end', inclusively. Range mappings may overlap, but the
414 behaviour is implementation-defined: each trace reader handles
415 overlapping ranges as it wishes.
417 See the <<example,EXAMPLE>> section below for a complete example.
420 [[tracepoint-event-class]]
421 `TRACEPOINT_EVENT_CLASS()` usage
422 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
423 A *tracepoint class* is a class of tracepoints sharing the
424 same field types and names. A tracepoint instance is one instance of
425 such a declared tracepoint class, with its own event name.
427 LTTng-UST creates one event serialization function per tracepoint
428 class. Using `TRACEPOINT_EVENT()` creates one tracepoint class per
429 tracepoint definition, whereas using `TRACEPOINT_EVENT_CLASS()` and
430 `TRACEPOINT_EVENT_INSTANCE()` creates one tracepoint class, and one or
431 more tracepoint instances of this class. In other words, many
432 tracepoints can reuse the same serialization code. Reusing the same
433 code, when possible, can reduce cache pollution, thus improve
436 The `TRACEPOINT_EVENT_CLASS()` macro accepts the same parameters as
437 the `TRACEPOINT_EVENT()` macro, except that instead of an event name,
438 its second parameter is the _tracepoint class name_:
440 ------------------------------------------------------------------------
441 TRACEPOINT_EVENT_CLASS(
442 /* Tracepoint provider name */
445 /* Tracepoint class name */
448 /* List of tracepoint arguments (input) */
453 /* List of fields of eventual event (output) */
458 ------------------------------------------------------------------------
460 Once the tracepoint class is defined, you can create as many tracepoint
463 -------------------------------------------------------------------------
464 TRACEPOINT_EVENT_INSTANCE(
465 /* Tracepoint provider name */
468 /* Tracepoint class name */
471 /* Tracepoint/event name */
474 /* List of tracepoint arguments (input) */
479 ------------------------------------------------------------------------
481 As you can see, the `TRACEPOINT_EVENT_INSTANCE()` does not contain
482 the `TP_FIELDS()` macro, because they are defined at the
483 `TRACEPOINT_EVENT_CLASS()` level.
485 See the <<example,EXAMPLE>> section below for a complete example.
488 [[tracepoint-loglevel]]
489 `TRACEPOINT_LOGLEVEL()` usage
490 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
491 Optionally, a *log level* can be assigned to a defined tracepoint.
492 Assigning different levels of severity to tracepoints can be useful:
493 when controlling tracing sessions, you can choose to only enable
494 events falling into a specific log level range using the
495 nloption:--loglevel and nloption:--loglevel-only options of the
496 man:lttng-enable-event(1) command.
498 Log levels are assigned to tracepoints that are already defined using
499 the `TRACEPOINT_LOGLEVEL()` macro. The latter must be used after having
500 used `TRACEPOINT_EVENT()` or `TRACEPOINT_EVENT_INSTANCE()` for a given
501 tracepoint. The `TRACEPOINT_LOGLEVEL()` macro is used as follows:
503 ------------------------------------------------------------------------
505 /* Tracepoint provider name */
508 /* Tracepoint/event name */
514 ------------------------------------------------------------------------
516 The available log level definitions are:
518 include::log-levels.txt[]
520 See the <<example,EXAMPLE>> section below for a complete example.
524 Instrumenting your application
525 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
526 Once the tracepoint provider is created (see the
527 <<creating-tp,Creating a tracepoint provider>> section above), you can
528 instrument your application with the defined tracepoints thanks to the
529 `tracepoint()` macro:
532 #define *tracepoint*('prov_name', 't_name', ...)
537 Tracepoint provider name.
540 Tracepoint/event name.
543 Tracepoint arguments, if any.
545 Make sure to include the tracepoint provider header file anywhere you
546 use `tracepoint()` for this provider.
548 NOTE: Even though LTTng-UST supports `tracepoint()` call site duplicates
549 having the same provider and tracepoint names, it is recommended to use
550 a provider/tracepoint name pair only once within the application source
551 code to help map events back to their call sites when analyzing the
554 Sometimes, arguments to the tracepoint are expensive to compute (take
555 call stack, for example). To avoid the computation when the tracepoint
556 is disabled, you can use the `tracepoint_enabled()` and
557 `do_tracepoint()` macros:
560 #define *tracepoint_enabled*('prov_name', 't_name')
561 #define *do_tracepoint*('prov_name', 't_name', ...)
563 `tracepoint_enabled()` returns a non-zero value if the tracepoint
564 named 't_name' from the provider named 'prov_name' is enabled at
567 `do_tracepoint()` is like `tracepoint()`, except that it doesn't check
568 if the tracepoint is enabled. Using `tracepoint()` with
569 `tracepoint_enabled()` is dangerous since `tracepoint()` also contains
570 the `tracepoint_enabled()` check, thus a race condition is possible
573 ------------------------------------------------------------------------
574 if (tracepoint_enabled(my_provider, my_tracepoint)) {
575 stuff = prepare_stuff();
578 tracepoint(my_provider, my_tracepoint, stuff);
579 ------------------------------------------------------------------------
581 If the tracepoint is enabled after the condition, then `stuff` is not
582 prepared: the emitted event will either contain wrong data, or the
583 whole application could crash (segmentation fault, for example).
585 NOTE: Neither `tracepoint_enabled()` nor `do_tracepoint()` have
586 a `STAP_PROBEV()` call, so if you need it, you should emit this call
591 Statically linking the tracepoint provider
592 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
593 With the static linking method, compiled tracepoint providers are copied
594 into the target application.
596 Define `TRACEPOINT_DEFINE` definition below the
597 `TRACEPOINT_CREATE_PROBES` definition in the tracepoint provider
600 ------------------------------------------------------------------------
601 #define TRACEPOINT_CREATE_PROBES
602 #define TRACEPOINT_DEFINE
605 ------------------------------------------------------------------------
607 Create the tracepoint provider object file:
614 NOTE: Although an application instrumented with LTTng-UST tracepoints
615 can be compiled with a C++ compiler, tracepoint probes should be
616 compiled with a C compiler.
618 At this point, you _can_ archive this tracepoint provider object file,
619 possibly with other object files of your application or with other
620 tracepoint provider object files, as a static library:
627 Using a static library does have the advantage of centralising the
628 tracepoint providers objects so they can be shared between multiple
629 applications. This way, when the tracepoint provider is modified, the
630 source code changes don't have to be patched into each application's
631 source code tree. The applications need to be relinked after each
632 change, but need not to be otherwise recompiled (unless the tracepoint
633 provider's API changes).
635 Then, link your application with this object file (or with the static
636 library containing it) and with `liblttng-ust` and `libdl`
637 (`libc` on a BSD system):
640 -------------------------------------
641 cc -o app tp.o app.o -llttng-ust -ldl
642 -------------------------------------
646 Dynamically loading the tracepoint provider
647 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
648 The second approach to package the tracepoint provider is to use the
649 dynamic loader: the library and its member functions are explicitly
650 sought, loaded at run time.
652 In this scenario, the tracepoint provider is compiled as a shared
655 The process to create the tracepoint provider shared object is pretty
656 much the same as the <<build-static,static linking method>>, except
659 * Since the tracepoint provider is not part of the application,
660 `TRACEPOINT_DEFINE` must be defined, for each tracepoint
661 provider, in exactly one source file of the
663 * `TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next
664 to `TRACEPOINT_DEFINE`
666 Regarding `TRACEPOINT_DEFINE` and `TRACEPOINT_PROBE_DYNAMIC_LINKAGE`,
667 the recommended practice is to use a separate C source file in your
668 application to define them, then include the tracepoint provider header
669 files afterwards. For example, as `tp-define.c`:
671 ------------------------------------------------------------------------
672 #define TRACEPOINT_DEFINE
673 #define TRACEPOINT_PROBE_DYNAMIC_LINKAGE
676 ------------------------------------------------------------------------
678 The tracepoint provider object file used to create the shared library is
679 built like it is using the static linking method, but with the
680 nloption:-fpic option:
687 It is then linked as a shared library like this:
690 -------------------------------------------------------
691 cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
692 -------------------------------------------------------
694 This tracepoint provider shared object isn't linked with the user
695 application: it must be loaded manually. This is why the application is
696 built with no mention of this tracepoint provider, but still needs
700 --------------------------------
701 cc -o app app.o tp-define.o -ldl
702 --------------------------------
704 There are two ways to dynamically load the tracepoint provider shared
707 * Load it manually from the application using man:dlopen(3)
708 * Make the dynamic loader load it with the `LD_PRELOAD`
709 environment variable (see man:ld.so(8))
711 If the application does not dynamically load the tracepoint provider
712 shared object using one of the methods above, tracing is disabled for
713 this application, and the events are not listed in the output of
716 Note that it is not safe to use man:dlclose(3) on a tracepoint provider
717 shared object that is being actively used for tracing, due to a lack of
718 reference counting from LTTng-UST to the shared object.
720 For example, statically linking a tracepoint provider to a shared object
721 which is to be dynamically loaded by an application (a plugin, for
722 example) is not safe: the shared object, which contains the tracepoint
723 provider, could be dynamically closed (man:dlclose(3)) at any time by
726 To instrument a shared object, either:
728 * Statically link the tracepoint provider to the application, or
729 * Build the tracepoint provider as a shared object (following the
730 procedure shown in this section), and preload it when tracing is
731 needed using the `LD_PRELOAD` environment variable.
734 Using LTTng-UST with daemons
735 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
736 Some extra care is needed when using `liblttng-ust` with daemon
737 applications that call man:fork(2), man:clone(2), or BSD's man:rfork(2)
738 without a following man:exec(3) family system call. The library
739 `liblttng-ust-fork.so` needs to be preloaded before starting the
740 application with the `LD_PRELOAD` environment variable (see
746 Context information can be prepended by the LTTng-UST tracer before
747 each event, or before specific events.
749 Context fields can be added to specific channels using
750 man:lttng-add-context(1).
752 The following context fields are supported by LTTng-UST:
757 NOTE: This context field is always enabled, and it cannot be added
758 with man:lttng-add-context(1). Its main purpose is to be used for
759 dynamic event filtering. See man:lttng-enable-event(1) for more
760 information about event filtering.
763 Instruction pointer: enables recording the exact address from which
764 an event was emitted. This context field can be used to
765 reverse-lookup the source location that caused the event
768 +perf:thread:COUNTER+::
769 perf counter named 'COUNTER'. Use `lttng add-context --list` to
770 list the available perf counters.
772 Only available on IA-32 and x86-64 architectures.
775 POSIX thread identifier. Can be used on architectures where
776 `pthread_t` maps nicely to an `unsigned long` type.
779 Thread name, as set by man:exec(3) or man:prctl(2). It is
780 recommended that programs set their thread name with man:prctl(2)
781 before hitting the first tracepoint for that thread.
784 Virtual process ID: process ID as seen from the point of view of
785 the process namespace.
788 Virtual thread ID: thread ID as seen from the point of view of
789 the process namespace.
795 If an application that uses `liblttng-ust` becomes part of a tracing
796 session, information about its currently loaded shared objects, their
797 build IDs, and their debug link information are emitted as events
800 The following LTTng-UST state dump events exist and must be enabled
801 to record application state dumps.
803 `lttng_ust_statedump:start`::
804 Emitted when the state dump begins.
806 This event has no fields.
808 `lttng_ust_statedump:end`::
809 Emitted when the state dump ends. Once this event is emitted, it
810 is guaranteed that, for a given process, the state dump is
813 This event has no fields.
815 `lttng_ust_statedump:bin_info`::
816 Emitted when information about a currently loaded executable or
817 shared object is found.
822 |==================================================================
823 | Field name | Description
824 | `baddr` | Base address of loaded executable
825 | `memsz` | Size of loaded executable in memory
826 | `path` | Path to loaded executable file
827 | `is_pic` | Whether the executable is
828 position-independent code
829 |==================================================================
831 `lttng_ust_statedump:build_id`::
832 Emitted when a build ID is found in a currently loaded shared
834 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
835 for more information about build IDs.
840 |==============================================================
841 | Field name | Description
842 | `baddr` | Base address of loaded library
843 | `build_id` | Build ID
844 |==============================================================
846 `lttng_ust_statedump:debug_link`::
847 Emitted when debug link information is found in a currently loaded
849 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
850 for more information about debug links.
855 |==============================================================
856 | Field name | Description
857 | `baddr` | Base address of loaded library
858 | `crc` | Debug link file's CRC
859 | `filename` | Debug link file name
860 |==============================================================
866 NOTE: A few examples are available in the
867 https://github.com/lttng/lttng-ust/tree/master/doc/examples[`doc/examples`]
868 directory of LTTng-UST's source tree.
870 This example shows all the features documented in the previous
871 sections. The <<build-static,static linking>> method is chosen here
872 to link the application with the tracepoint provider.
874 You can compile the source files and link them together statically
878 -------------------------------------
881 cc -o app tp.o app.o -llttng-ust -ldl
882 -------------------------------------
884 Using the man:lttng(1) tool, create an LTTng tracing session, enable
885 all the events of this tracepoint provider, and start tracing:
888 ----------------------------------------------
889 lttng create my-session
890 lttng enable-event --userspace 'my_provider:*'
892 ----------------------------------------------
894 You may also enable specific events:
897 ----------------------------------------------------------
898 lttng enable-event --userspace my_provider:big_event
899 lttng enable-event --userspace my_provider:event_instance2
900 ----------------------------------------------------------
909 Stop the current tracing session and inspect the recorded events:
918 Tracepoint provider header file
919 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
922 ------------------------------------------------------------------------
923 #undef TRACEPOINT_PROVIDER
924 #define TRACEPOINT_PROVIDER my_provider
926 #undef TRACEPOINT_INCLUDE
927 #define TRACEPOINT_INCLUDE "./tp.h"
929 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
932 #include <lttng/tracepoint.h>
942 const char *, my_string_arg
945 ctf_string(argc, my_string_arg)
946 ctf_integer(int, argv, my_integer_arg)
954 ctf_enum_value("ZERO", 0)
955 ctf_enum_value("ONE", 1)
956 ctf_enum_value("TWO", 2)
957 ctf_enum_range("A RANGE", 52, 125)
958 ctf_enum_value("ONE THOUSAND", 1000)
967 const char *, my_string_arg,
973 ctf_integer(int, int_field1, my_integer_arg * 2)
974 ctf_integer_hex(long int, stream_pos, ftell(stream))
975 ctf_float(double, float_field, flt_arg)
976 ctf_string(string_field, my_string_arg)
977 ctf_array(int, array_field, array_arg, 7)
978 ctf_array_text(char, array_text_field, array_arg, 5)
979 ctf_sequence(int, seq_field, array_arg, int,
981 ctf_sequence_text(char, seq_text_field, array_arg,
982 int, my_integer_arg / 5)
983 ctf_enum(my_provider, my_enum, int,
984 enum_field, array_arg[1])
988 TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING)
990 TRACEPOINT_EVENT_CLASS(
995 struct app_struct *, app_struct_arg
998 ctf_integer(int, a, my_integer_arg)
999 ctf_integer(unsigned long, b, app_struct_arg->b)
1000 ctf_string(c, app_struct_arg->c)
1004 TRACEPOINT_EVENT_INSTANCE(
1006 my_tracepoint_class,
1009 int, my_integer_arg,
1010 struct app_struct *, app_struct_arg
1014 TRACEPOINT_EVENT_INSTANCE(
1016 my_tracepoint_class,
1019 int, my_integer_arg,
1020 struct app_struct *, app_struct_arg
1024 TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO)
1026 TRACEPOINT_EVENT_INSTANCE(
1028 my_tracepoint_class,
1031 int, my_integer_arg,
1032 struct app_struct *, app_struct_arg
1038 #include <lttng/tracepoint-event.h>
1039 ------------------------------------------------------------------------
1042 Tracepoint provider source file
1043 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1046 ------------------------------------------------------------------------
1047 #define TRACEPOINT_CREATE_PROBES
1048 #define TRACEPOINT_DEFINE
1051 ------------------------------------------------------------------------
1054 Application header file
1055 ~~~~~~~~~~~~~~~~~~~~~~~
1058 ------------------------------------------------------------------------
1069 ------------------------------------------------------------------------
1072 Application source file
1073 ~~~~~~~~~~~~~~~~~~~~~~~
1076 ------------------------------------------------------------------------
1083 static int array_of_ints[] = {
1084 100, -35, 1, 23, 14, -6, 28, 1001, -3000,
1087 int main(int argc, char* argv[])
1090 struct app_struct app_struct;
1092 tracepoint(my_provider, simple_event, argc, argv[0]);
1093 stream = fopen("/tmp/app.txt", "w");
1097 "Error: Cannot open /tmp/app.txt for writing\n");
1098 return EXIT_FAILURE;
1101 if (fprintf(stream, "0123456789") != 10) {
1103 fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
1104 return EXIT_FAILURE;
1107 tracepoint(my_provider, big_event, 35, "hello tracepoint",
1108 stream, -3.14, array_of_ints);
1110 app_struct.b = argc;
1111 app_struct.c = "[the string]";
1112 tracepoint(my_provider, event_instance1, 23, &app_struct);
1113 app_struct.b = argc * 5;
1114 app_struct.c = "[other string]";
1115 tracepoint(my_provider, event_instance2, 17, &app_struct);
1117 app_struct.c = "nothing";
1118 tracepoint(my_provider, event_instance3, -52, &app_struct);
1120 return EXIT_SUCCESS;
1122 ------------------------------------------------------------------------
1125 ENVIRONMENT VARIABLES
1126 ---------------------
1128 Alternative user's home directory. This variable is useful when the
1129 user running the instrumented application has a non-writable home
1132 Unix sockets used for the communication between `liblttng-ust` and the
1133 LTTng session and consumer daemons (part of the LTTng-tools project)
1134 are located in a specific directory under `$LTTNG_HOME` (or `$HOME` if
1135 `$LTTNG_HOME` is not set).
1137 `LTTNG_UST_BLOCKING_RETRY_TIMEOUT`::
1138 Maximum duration (milliseconds) to retry event tracing when
1139 there's no space left for the event record in the sub-buffer.
1143 Never block the application.
1146 Block the application for the specified number of milliseconds. If
1147 there's no space left after this duration, discard the event
1151 Block the application until there's space left for the event record.
1154 This option can be useful in workloads generating very large trace data
1155 throughput, where blocking the application is an acceptable trade-off to
1156 prevent discarding event records.
1158 WARNING: Setting this environment variable to a non-zero value may
1159 significantly affect application timings.
1161 `LTTNG_UST_CLOCK_PLUGIN`::
1162 Path to the shared object which acts as the clock override plugin.
1163 An example of such a plugin can be found in the LTTng-UST
1165 https://github.com/lttng/lttng-ust/tree/master/doc/examples/clock-override[`examples/clock-override`].
1168 Activates `liblttng-ust`'s debug and error output if set to `1`.
1170 `LTTNG_UST_GETCPU_PLUGIN`::
1171 Path to the shared object which acts as the `getcpu()` override
1172 plugin. An example of such a plugin can be found in the LTTng-UST
1174 https://github.com/lttng/lttng-ust/tree/master/doc/examples/getcpu-override[`examples/getcpu-override`].
1176 `LTTNG_UST_REGISTER_TIMEOUT`::
1177 Waiting time for the _registration done_ session daemon command
1178 before proceeding to execute the main program (milliseconds).
1180 The value `0` means _do not wait_. The value `-1` means _wait forever_.
1181 Setting this environment variable to `0` is recommended for applications
1182 with time constraints on the process startup time.
1184 Default: {lttng_ust_register_timeout}.
1186 `LTTNG_UST_BLOCKING_RETRY_TIMEOUT`::
1187 Maximum time during which event tracing retry is attempted on buffer
1188 full condition (millliseconds). Setting this environment to non-zero
1189 value effectively blocks the application on buffer full condition.
1190 Setting this environment variable to non-zero values may
1191 significantly affect application timings. Setting this to a negative
1192 value may block the application indefinitely if there is no consumer
1193 emptying the ring buffer. The delay between retry attempts is the
1194 minimum between the specified timeout value and 100ms. This option
1195 can be useful in workloads generating very large trace data
1196 throughput, where blocking the application is an acceptable
1197 trade-off to not discard events. _Use with caution_.
1199 The value `0` means _do not retry_. The value `-1` means _retry forever_.
1200 Value > `0` means a maximum timeout of the given value.
1202 Default: {lttng_ust_blocking_retry_timeout}.
1204 `LTTNG_UST_WITHOUT_BADDR_STATEDUMP`::
1205 Prevents `liblttng-ust` from performing a base address state dump
1206 (see the <<state-dump,LTTng-UST state dump>> section above) if
1210 include::common-footer.txt[]
1212 include::common-copyrights.txt[]
1214 include::common-authors.txt[]
1221 man:lttng-gen-tp(1),
1222 man:lttng-ust-dl(3),
1223 man:lttng-ust-cyg-profile(3),
1225 man:lttng-enable-event(1),
1227 man:lttng-add-context(1),