1LTTNG-UST(3)                     LTTng Manual                     LTTNG-UST(3)
2
3
4

NAME

6       lttng-ust - LTTng user space tracing
7

SYNOPSIS

9       #include <lttng/tracepoint.h>
10
11       #define TRACEPOINT_ENUM(prov_name, enum_name, mappings)
12       #define TRACEPOINT_EVENT(prov_name, t_name, args, fields)
13       #define TRACEPOINT_EVENT_CLASS(prov_name, class_name, args, fields)
14       #define TRACEPOINT_EVENT_INSTANCE(prov_name, class_name, t_name, args)
15       #define TRACEPOINT_LOGLEVEL(prov_name, t_name, level)
16       #define ctf_array(int_type, field_name, expr, count)
17       #define ctf_array_nowrite(int_type, field_name, expr, count)
18       #define ctf_array_hex(int_type, field_name, expr, count)
19       #define ctf_array_nowrite_hex(int_type, field_name, expr, count)
20       #define ctf_array_network(int_type, field_name, expr, count)
21       #define ctf_array_network_nowrite(int_type, field_name, expr, count)
22       #define ctf_array_network_hex(int_type, field_name, expr, count)
23       #define ctf_array_network_nowrite_hex(int_type, field_name, expr, count)
24       #define ctf_array_text(char, field_name, expr, count)
25       #define ctf_array_text_nowrite(char, field_name, expr, count)
26       #define ctf_enum(prov_name, enum_name, int_type, field_name, expr)
27       #define ctf_enum_nowrite(prov_name, enum_name, int_type, field_name,
28                                expr)
29       #define ctf_enum_value(label, value)
30       #define ctf_enum_range(label, start, end)
31       #define ctf_float(float_type, field_name, expr)
32       #define ctf_float_nowrite(float_type, field_name, expr)
33       #define ctf_integer(int_type, field_name, expr)
34       #define ctf_integer_hex(int_type, field_name, expr)
35       #define ctf_integer_network(int_type, field_name, expr)
36       #define ctf_integer_network_hex(int_type, field_name, expr)
37       #define ctf_integer_nowrite(int_type, field_name, expr)
38       #define ctf_sequence(int_type, field_name, expr, len_type, len_expr)
39       #define ctf_sequence_nowrite(int_type, field_name, expr, len_type,
40                                    len_expr)
41       #define ctf_sequence_hex(int_type, field_name, expr, len_type,
42                                len_expr)
43       #define ctf_sequence_nowrite_hex(int_type, field_name, expr, len_type,
44                                        len_expr)
45       #define ctf_sequence_network(int_type, field_name, expr, len_type,
46                                    len_expr)
47       #define ctf_sequence_network_nowrite(int_type, field_name, expr,
48                                            len_type, len_expr)
49       #define ctf_sequence_network_hex(int_type, field_name, expr, len_type,
50                                        len_expr)
51       #define ctf_sequence_network_nowrite_hex(int_type, field_name, expr,
52                                                len_type, len_expr)
53       #define ctf_sequence_text(char, field_name, expr, len_type, len_expr)
54       #define ctf_sequence_text_nowrite(char, field_name, expr, len_type,
55                                         len_expr)
56       #define ctf_string(field_name, expr)
57       #define ctf_string_nowrite(field_name, expr)
58       #define do_tracepoint(prov_name, t_name, ...)
59       #define tracepoint(prov_name, t_name, ...)
60       #define tracepoint_enabled(prov_name, t_name)
61
62       Link with -llttng-ust -ldl, following this man page.
63

DESCRIPTION

65       The Linux Trace Toolkit: next generation <http://lttng.org/> is an open
66       source software package used for correlated tracing of the Linux
67       kernel, user applications, and user libraries.
68
69       LTTng-UST is the user space tracing component of the LTTng project. It
70       is a port to user space of the low-overhead tracing capabilities of the
71       LTTng Linux kernel tracer. The liblttng-ust library is used to trace
72       user applications and libraries.
73
74           Note
75           This man page is about the liblttng-ust library. The LTTng-UST
76           project also provides Java and Python packages to trace
77           applications written in those languages. How to instrument and
78           trace Java and Python applications is documented in the online
79           LTTng documentation <http://lttng.org/docs/>.
80
81       There are three ways to use liblttng-ust:
82
83       ·   Using the tracef(3) API, which is similar to printf(3).
84
85       ·   Using the tracelog(3) API, which is tracef(3) with a log level
86           parameter.
87
88       ·   Defining your own tracepoints. See the Creating a tracepoint
89           provider section below.
90
91   Creating a tracepoint provider
92       Creating a tracepoint provider is the first step of using liblttng-ust.
93       The next steps are:
94
95       ·   Instrumenting your application with tracepoint() calls
96
97       ·   Building your application with LTTng-UST support, either statically
98           or dynamically.
99
100       A tracepoint provider is a compiled object containing the event probes
101       corresponding to your custom tracepoint definitions. A tracepoint
102       provider contains the code to get the size of an event and to serialize
103       it, amongst other things.
104
105       To create a tracepoint provider, start with the following tracepoint
106       provider header template:
107
108           #undef TRACEPOINT_PROVIDER
109           #define TRACEPOINT_PROVIDER my_provider
110
111           #undef TRACEPOINT_INCLUDE
112           #define TRACEPOINT_INCLUDE "./tp.h"
113
114           #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
115           #define _TP_H
116
117           #include <lttng/tracepoint.h>
118
119           /*
120            * TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
121            * TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(),
122            * and `TRACEPOINT_ENUM()` are used here.
123            */
124
125           #endif /* _TP_H */
126
127           #include <lttng/tracepoint-event.h>
128
129       In this template, the tracepoint provider is named my_provider
130       (TRACEPOINT_PROVIDER definition). The file needs to bear the name of
131       the TRACEPOINT_INCLUDE definition (tp.h in this case). Between #include
132       <lttng/tracepoint.h> and #endif go the invocations of the
133       TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
134       TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(), and
135       TRACEPOINT_ENUM() macros.
136
137           Note
138           You can avoid writing the prologue and epilogue boilerplate in the
139           template file above by using the lttng-gen-tp(1) tool shipped with
140           LTTng-UST.
141
142       The tracepoint provider header file needs to be included in a source
143       file which looks like this:
144
145           #define TRACEPOINT_CREATE_PROBES
146
147           #include "tp.h"
148
149       Together, those two files (let’s call them tp.h and tp.c) form the
150       tracepoint provider sources, ready to be compiled.
151
152       You can create multiple tracepoint providers to be used in a single
153       application, but each one must have its own header file.
154
155       The TRACEPOINT_EVENT() usage section below shows how to use the
156       TRACEPOINT_EVENT() macro to define the actual tracepoints in the
157       tracepoint provider header file.
158
159       See the EXAMPLE section below for a complete example.
160
161   TRACEPOINT_EVENT() usage
162       The TRACEPOINT_EVENT() macro is used in a template provider header file
163       (see the Creating a tracepoint provider section above) to define
164       LTTng-UST tracepoints.
165
166       The TRACEPOINT_EVENT() usage template is as follows:
167
168           TRACEPOINT_EVENT(
169               /* Tracepoint provider name */
170               my_provider,
171
172               /* Tracepoint/event name */
173               my_tracepoint,
174
175               /* List of tracepoint arguments (input) */
176               TP_ARGS(
177                   ...
178               ),
179
180               /* List of fields of eventual event (output) */
181               TP_FIELDS(
182                   ...
183               )
184           )
185
186       The TP_ARGS() macro contains the input arguments of the tracepoint.
187       Those arguments can be used in the argument expressions of the output
188       fields defined in TP_FIELDS().
189
190       The format of the TP_ARGS() parameters is: C type, then argument name;
191       repeat as needed, up to ten times. For example:
192
193           TP_ARGS(
194               int, my_int,
195               const char *, my_string,
196               FILE *, my_file,
197               double, my_float,
198               struct my_data *, my_data
199           )
200
201       The TP_FIELDS() macro contains the output fields of the tracepoint,
202       that is, the actual data that can be recorded in the payload of an
203       event emitted by this tracepoint.
204
205       The TP_FIELDS() macro contains a list of ctf_*() macros NOT separated
206       by commas. The available macros are documented in the Available ctf_*()
207       field type macros section below.
208
209   Available ctf_*() field type macros
210       This section documents the available ctf_*() macros that can be
211       inserted in the TP_FIELDS() macro of the TRACEPOINT_EVENT() macro.
212
213       Standard integer, displayed in base 10:
214
215           ctf_integer(int_type, field_name, expr)
216           ctf_integer_nowrite(int_type, field_name, expr)
217
218       Standard integer, displayed in base 16:
219
220           ctf_integer_hex(int_type, field_name, expr)
221
222       Integer in network byte order (big endian), displayed in base 10:
223
224           ctf_integer_network(int_type, field_name, expr)
225
226       Integer in network byte order, displayed in base 16:
227
228           ctf_integer_network_hex(int_type, field_name, expr)
229
230       Floating point number:
231
232           ctf_float(float_type, field_name, expr)
233           ctf_float_nowrite(float_type, field_name, expr)
234
235       Null-terminated string:
236
237           ctf_string(field_name, expr)
238           ctf_string_nowrite(field_name, expr)
239
240       Statically-sized array of integers (_hex versions displayed in
241       hexadecimal, _network versions in network byte order):
242
243           ctf_array(int_type, field_name, expr, count)
244           ctf_array_nowrite(int_type, field_name, expr, count)
245           ctf_array_hex(int_type, field_name, expr, count)
246           ctf_array_nowrite_hex(int_type, field_name, expr, count)
247           ctf_array_network(int_type, field_name, expr, count)
248           ctf_array_network_nowrite(int_type, field_name, expr, count)
249           ctf_array_network_hex(int_type, field_name, expr, count)
250           ctf_array_network_nowrite_hex(int_type, field_name, expr, count)
251
252       Statically-sized array, printed as text; no need to be null-terminated:
253
254           ctf_array_text(char, field_name, expr, count)
255           ctf_array_text_nowrite(char, field_name, expr, count)
256
257       Dynamically-sized array of integers (_hex versions displayed in
258       hexadecimal, _network versions in network byte order):
259
260           ctf_sequence(int_type, field_name, expr, len_type, len_expr)
261           ctf_sequence_nowrite(int_type, field_name, expr, len_type, len_expr)
262           ctf_sequence_hex(int_type, field_name, expr, len_type, len_expr)
263           ctf_sequence_nowrite_hex(int_type, field_name, expr, len_type,
264                                    len_expr)
265           ctf_sequence_network(int_type, field_name, expr, len_type, len_expr)
266           ctf_sequence_network_nowrite(int_type, field_name, expr, len_type,
267                                        len_expr)
268           ctf_sequence_network_hex(int_type, field_name, expr, len_type,
269                                    len_expr)
270           ctf_sequence_network_nowrite_hex(int_type, field_name, expr,
271                                            len_type, len_expr)
272
273       Dynamically-sized array, displayed as text; no need to be
274       null-terminated:
275
276           ctf_sequence_text(char, field_name, expr, len_type, len_expr)
277           ctf_sequence_text_nowrite(char, field_name, expr, len_type, len_expr)
278
279       Enumeration. The enumeration field must be defined before using this
280       macro with the TRACEPOINT_ENUM() macro. See the TRACEPOINT_ENUM() usage
281       section for more information.
282
283           ctf_enum(prov_name, enum_name, int_type, field_name, expr)
284           ctf_enum_nowrite(prov_name, enum_name, int_type, field_name, expr)
285
286       The parameters are:
287
288       count
289           Number of elements in array/sequence. This must be known at compile
290           time.
291
292       enum_name
293           Name of an enumeration field previously defined with the
294           TRACEPOINT_ENUM() macro. See the TRACEPOINT_ENUM() usage section
295           for more information.
296
297       expr
298           C expression resulting in the field’s value. This expression can
299           use one or more arguments passed to the tracepoint. The arguments
300           of a given tracepoint are defined in the TP_ARGS() macro (see the
301           Creating a tracepoint provider section above).
302
303       field_name
304           Event field name (C identifier syntax, NOT a literal string).
305
306       float_type
307           Float C type (float or double). The size of this type determines
308           the size of the floating point number field.
309
310       int_type
311           Integer C type. The size of this type determines the size of the
312           integer/enumeration field.
313
314       len_expr
315           C expression resulting in the sequence’s length. This expression
316           can use one or more arguments passed to the tracepoint.
317
318       len_type
319           Unsigned integer C type of sequence’s length.
320
321       prov_name
322           Tracepoint provider name. This must be the same as the tracepoint
323           provider name used in a previous field definition.
324
325       The _nowrite versions omit themselves from the recorded trace, but are
326       otherwise identical. Their primary purpose is to make some of the event
327       context available to the event filters without having to commit the
328       data to sub-buffers. See lttng-enable-event(1) to learn more about
329       dynamic event filtering.
330
331       See the EXAMPLE section below for a complete example.
332
333   TRACEPOINT_ENUM() usage
334       An enumeration field is a list of mappings between an integers, or a
335       range of integers, and strings (sometimes called labels or
336       enumerators). Enumeration fields can be used to have a more compact
337       trace when the possible values for a field are limited.
338
339       An enumeration field is defined with the TRACEPOINT_ENUM() macro:
340
341           TRACEPOINT_ENUM(
342               /* Tracepoint provider name */
343               my_provider,
344
345               /* Enumeration name (unique in the whole tracepoint provider) */
346               my_enum,
347
348               /* Enumeration mappings */
349               TP_ENUM_VALUES(
350                   ...
351               )
352           )
353
354       TP_ENUM_VALUES() contains a list of enumeration mappings, NOT separated
355       by commas. Two macros can be used in the TP_ENUM_VALUES():
356       ctf_enum_value() and ctf_enum_range().
357
358       ctf_enum_value() is a single value mapping:
359
360           ctf_enum_value(label, value)
361
362       This macro maps the given label string to the value value.
363
364       ctf_enum_range() is a range mapping:
365
366           ctf_enum_range(label, start, end)
367
368       This macro maps the given label string to the range of integers from
369       start to end, inclusively. Range mappings may overlap, but the
370       behaviour is implementation-defined: each trace reader handles
371       overlapping ranges as it wishes.
372
373       See the EXAMPLE section below for a complete example.
374
375   TRACEPOINT_EVENT_CLASS() usage
376       A tracepoint class is a class of tracepoints sharing the same field
377       types and names. A tracepoint instance is one instance of such a
378       declared tracepoint class, with its own event name.
379
380       LTTng-UST creates one event serialization function per tracepoint
381       class. Using TRACEPOINT_EVENT() creates one tracepoint class per
382       tracepoint definition, whereas using TRACEPOINT_EVENT_CLASS() and
383       TRACEPOINT_EVENT_INSTANCE() creates one tracepoint class, and one or
384       more tracepoint instances of this class. In other words, many
385       tracepoints can reuse the same serialization code. Reusing the same
386       code, when possible, can reduce cache pollution, thus improve
387       performance.
388
389       The TRACEPOINT_EVENT_CLASS() macro accepts the same parameters as the
390       TRACEPOINT_EVENT() macro, except that instead of an event name, its
391       second parameter is the tracepoint class name:
392
393           TRACEPOINT_EVENT_CLASS(
394               /* Tracepoint provider name */
395               my_provider,
396
397               /* Tracepoint class name */
398               my_tracepoint_class,
399
400               /* List of tracepoint arguments (input) */
401               TP_ARGS(
402                   ...
403               ),
404
405               /* List of fields of eventual event (output) */
406               TP_FIELDS(
407                   ...
408               )
409           )
410
411       Once the tracepoint class is defined, you can create as many tracepoint
412       instances as needed:
413
414           TRACEPOINT_EVENT_INSTANCE(
415               /* Tracepoint provider name */
416               my_provider,
417
418               /* Tracepoint class name */
419               my_tracepoint_class,
420
421               /* Tracepoint/event name */
422               my_tracepoint,
423
424               /* List of tracepoint arguments (input) */
425               TP_ARGS(
426                   ...
427               )
428           )
429
430       As you can see, the TRACEPOINT_EVENT_INSTANCE() does not contain the
431       TP_FIELDS() macro, because they are defined at the
432       TRACEPOINT_EVENT_CLASS() level.
433
434       See the EXAMPLE section below for a complete example.
435
436   TRACEPOINT_LOGLEVEL() usage
437       Optionally, a log level can be assigned to a defined tracepoint.
438       Assigning different levels of severity to tracepoints can be useful:
439       when controlling tracing sessions, you can choose to only enable events
440       falling into a specific log level range using the --loglevel and
441       --loglevel-only options of the lttng-enable-event(1) command.
442
443       Log levels are assigned to tracepoints that are already defined using
444       the TRACEPOINT_LOGLEVEL() macro. The latter must be used after having
445       used TRACEPOINT_EVENT() or TRACEPOINT_EVENT_INSTANCE() for a given
446       tracepoint. The TRACEPOINT_LOGLEVEL() macro is used as follows:
447
448           TRACEPOINT_LOGLEVEL(
449               /* Tracepoint provider name */
450               my_provider,
451
452               /* Tracepoint/event name */
453               my_tracepoint,
454
455               /* Log level */
456               TRACE_INFO
457           )
458
459       The available log level definitions are:
460
461       TRACE_EMERG
462           System is unusable.
463
464       TRACE_ALERT
465           Action must be taken immediately.
466
467       TRACE_CRIT
468           Critical conditions.
469
470       TRACE_ERR
471           Error conditions.
472
473       TRACE_WARNING
474           Warning conditions.
475
476       TRACE_NOTICE
477           Normal, but significant, condition.
478
479       TRACE_INFO
480           Informational message.
481
482       TRACE_DEBUG_SYSTEM
483           Debug information with system-level scope (set of programs).
484
485       TRACE_DEBUG_PROGRAM
486           Debug information with program-level scope (set of processes).
487
488       TRACE_DEBUG_PROCESS
489           Debug information with process-level scope (set of modules).
490
491       TRACE_DEBUG_MODULE
492           Debug information with module (executable/library) scope (set of
493           units).
494
495       TRACE_DEBUG_UNIT
496           Debug information with compilation unit scope (set of functions).
497
498       TRACE_DEBUG_FUNCTION
499           Debug information with function-level scope.
500
501       TRACE_DEBUG_LINE
502           Debug information with line-level scope (default log level).
503
504       TRACE_DEBUG
505           Debug-level message.
506
507       See the EXAMPLE section below for a complete example.
508
509   Instrumenting your application
510       Once the tracepoint provider is created (see the Creating a tracepoint
511       provider section above), you can instrument your application with the
512       defined tracepoints thanks to the tracepoint() macro:
513
514           #define tracepoint(prov_name, t_name, ...)
515
516       With:
517
518       prov_name
519           Tracepoint provider name.
520
521       t_name
522           Tracepoint/event name.
523
524       ...
525           Tracepoint arguments, if any.
526
527       Make sure to include the tracepoint provider header file anywhere you
528       use tracepoint() for this provider.
529
530           Note
531           Even though LTTng-UST supports tracepoint() call site duplicates
532           having the same provider and tracepoint names, it is recommended to
533           use a provider/tracepoint name pair only once within the
534           application source code to help map events back to their call sites
535           when analyzing the trace.
536
537       Sometimes, arguments to the tracepoint are expensive to compute (take
538       call stack, for example). To avoid the computation when the tracepoint
539       is disabled, you can use the tracepoint_enabled() and do_tracepoint()
540       macros:
541
542           #define tracepoint_enabled(prov_name, t_name)
543           #define do_tracepoint(prov_name, t_name, ...)
544
545       tracepoint_enabled() returns a non-zero value if the tracepoint named
546       t_name from the provider named prov_name is enabled at run time.
547
548       do_tracepoint() is like tracepoint(), except that it doesn’t check if
549       the tracepoint is enabled. Using tracepoint() with tracepoint_enabled()
550       is dangerous since tracepoint() also contains the tracepoint_enabled()
551       check, thus a race condition is possible in this situation:
552
553           if (tracepoint_enabled(my_provider, my_tracepoint)) {
554               stuff = prepare_stuff();
555           }
556
557           tracepoint(my_provider, my_tracepoint, stuff);
558
559       If the tracepoint is enabled after the condition, then stuff is not
560       prepared: the emitted event will either contain wrong data, or the
561       whole application could crash (segmentation fault, for example).
562
563           Note
564           Neither tracepoint_enabled() nor do_tracepoint() have a
565           STAP_PROBEV() call, so if you need it, you should emit this call
566           yourself.
567
568   Statically linking the tracepoint provider
569       With the static linking method, compiled tracepoint providers are
570       copied into the target application.
571
572       Define TRACEPOINT_DEFINE definition below the TRACEPOINT_CREATE_PROBES
573       definition in the tracepoint provider source:
574
575           #define TRACEPOINT_CREATE_PROBES
576           #define TRACEPOINT_DEFINE
577
578           #include "tp.h"
579
580       Create the tracepoint provider object file:
581
582           $ cc -c -I. tp.c
583
584
585           Note
586           Although an application instrumented with LTTng-UST tracepoints can
587           be compiled with a C++ compiler, tracepoint probes should be
588           compiled with a C compiler.
589
590       At this point, you can archive this tracepoint provider object file,
591       possibly with other object files of your application or with other
592       tracepoint provider object files, as a static library:
593
594           $ ar rc tp.a tp.o
595
596       Using a static library does have the advantage of centralising the
597       tracepoint providers objects so they can be shared between multiple
598       applications. This way, when the tracepoint provider is modified, the
599       source code changes don’t have to be patched into each application’s
600       source code tree. The applications need to be relinked after each
601       change, but need not to be otherwise recompiled (unless the tracepoint
602       provider’s API changes).
603
604       Then, link your application with this object file (or with the static
605       library containing it) and with liblttng-ust and libdl (libc on a BSD
606       system):
607
608           $ cc -o app tp.o app.o -llttng-ust -ldl
609
610   Dynamically loading the tracepoint provider
611       The second approach to package the tracepoint provider is to use the
612       dynamic loader: the library and its member functions are explicitly
613       sought, loaded at run time.
614
615       In this scenario, the tracepoint provider is compiled as a shared
616       object.
617
618       The process to create the tracepoint provider shared object is pretty
619       much the same as the static linking method, except that:
620
621       ·   Since the tracepoint provider is not part of the application,
622           TRACEPOINT_DEFINE must be defined, for each tracepoint provider, in
623           exactly one source file of the application
624
625       ·   TRACEPOINT_PROBE_DYNAMIC_LINKAGE must be defined next to
626           TRACEPOINT_DEFINE
627
628       Regarding TRACEPOINT_DEFINE and TRACEPOINT_PROBE_DYNAMIC_LINKAGE, the
629       recommended practice is to use a separate C source file in your
630       application to define them, then include the tracepoint provider header
631       files afterwards. For example, as tp-define.c:
632
633           #define TRACEPOINT_DEFINE
634           #define TRACEPOINT_PROBE_DYNAMIC_LINKAGE
635
636           #include "tp.h"
637
638       The tracepoint provider object file used to create the shared library
639       is built like it is using the static linking method, but with the -fpic
640       option:
641
642           $ cc -c -fpic -I. tp.c
643
644       It is then linked as a shared library like this:
645
646           $ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
647
648       This tracepoint provider shared object isn’t linked with the user
649       application: it must be loaded manually. This is why the application is
650       built with no mention of this tracepoint provider, but still needs
651       libdl:
652
653           $ cc -o app app.o tp-define.o -ldl
654
655       There are two ways to dynamically load the tracepoint provider shared
656       object:
657
658       ·   Load it manually from the application using dlopen(3)
659
660       ·   Make the dynamic loader load it with the LD_PRELOAD environment
661           variable (see ld.so(8))
662
663       If the application does not dynamically load the tracepoint provider
664       shared object using one of the methods above, tracing is disabled for
665       this application, and the events are not listed in the output of lttng-
666       list(1).
667
668       Note that it is not safe to use dlclose(3) on a tracepoint provider
669       shared object that is being actively used for tracing, due to a lack of
670       reference counting from LTTng-UST to the shared object.
671
672       For example, statically linking a tracepoint provider to a shared
673       object which is to be dynamically loaded by an application (a plugin,
674       for example) is not safe: the shared object, which contains the
675       tracepoint provider, could be dynamically closed (dlclose(3)) at any
676       time by the application.
677
678       To instrument a shared object, either:
679
680       ·   Statically link the tracepoint provider to the application, or
681
682       ·   Build the tracepoint provider as a shared object (following the
683           procedure shown in this section), and preload it when tracing is
684           needed using the LD_PRELOAD environment variable.
685
686   Using LTTng-UST with daemons
687       Some extra care is needed when using liblttng-ust with daemon
688       applications that call fork(2), clone(2), or BSD’s rfork(2) without a
689       following exec(3) family system call. The library liblttng-ust-fork.so
690       needs to be preloaded before starting the application with the
691       LD_PRELOAD environment variable (see ld.so(8)).
692
693       To use liblttng-ust with a daemon application which closes file
694       descriptors that were not opened by it, preload the liblttng-ust-fd.so
695       library before you start the application. Typical use cases include
696       daemons closing all file descriptors after fork(2), and buggy
697       applications doing “double-closes”.
698
699   Context information
700       Context information can be prepended by the LTTng-UST tracer before
701       each event, or before specific events.
702
703       Context fields can be added to specific channels using lttng-add-
704       context(1).
705
706       The following context fields are supported by LTTng-UST:
707
708       cpu_id
709           CPU ID.
710
711               Note
712               This context field is always enabled, and it cannot be added
713               with lttng-add-context(1). Its main purpose is to be used for
714               dynamic event filtering. See lttng-enable-event(1) for more
715               information about event filtering.
716
717       ip
718           Instruction pointer: enables recording the exact address from which
719           an event was emitted. This context field can be used to
720           reverse-lookup the source location that caused the event to be
721           emitted.
722
723       perf:thread:COUNTER
724           perf counter named COUNTER. Use lttng add-context --list to list
725           the available perf counters.
726
727           Only available on IA-32 and x86-64 architectures.
728
729       perf:thread:raw:rN:NAME
730           perf counter with raw ID N and custom name NAME. See lttng-add-
731           context(1) for more details.
732
733       pthread_id
734           POSIX thread identifier. Can be used on architectures where
735           pthread_t maps nicely to an unsigned long type.
736
737       procname
738           Thread name, as set by exec(3) or prctl(2). It is recommended that
739           programs set their thread name with prctl(2) before hitting the
740           first tracepoint for that thread.
741
742       vpid
743           Virtual process ID: process ID as seen from the point of view of
744           the process namespace.
745
746       vtid
747           Virtual thread ID: thread ID as seen from the point of view of the
748           process namespace.
749
750   LTTng-UST state dump
751       If an application that uses liblttng-ust becomes part of a tracing
752       session, information about its currently loaded shared objects, their
753       build IDs, and their debug link information are emitted as events by
754       the tracer.
755
756       The following LTTng-UST state dump events exist and must be enabled to
757       record application state dumps. Note that, during the state dump phase,
758       LTTng-UST can also emit shared library load/unload events (see Shared
759       library load/unload tracking below).
760
761       lttng_ust_statedump:start
762           Emitted when the state dump begins.
763
764           This event has no fields.
765
766       lttng_ust_statedump:end
767           Emitted when the state dump ends. Once this event is emitted, it is
768           guaranteed that, for a given process, the state dump is complete.
769
770           This event has no fields.
771
772       lttng_ust_statedump:bin_info
773           Emitted when information about a currently loaded executable or
774           shared object is found.
775
776           Fields:
777
778           ┌───────────────┬────────────────────────────────┐
779Field name     Description                    
780           ├───────────────┼────────────────────────────────┤
781baddr          │ Base address of loaded         │
782           │               │ executable.                    │
783           ├───────────────┼────────────────────────────────┤
784memsz          │ Size of loaded executable      │
785           │               │ in memory.                     │
786           ├───────────────┼────────────────────────────────┤
787path           │ Path to loaded executable      │
788           │               │ file.                          │
789           ├───────────────┼────────────────────────────────┤
790is_pic         │ Whether or not the             │
791           │               │ executable is                  │
792           │               │ position-independent code.     │
793           ├───────────────┼────────────────────────────────┤
794has_build_id   │ Whether or not the             │
795           │               │ executable has a build ID.     │
796           │               │ If this field is 1, you        │
797           │               │ can expect that an             │
798           │               │ lttng_ust_statedump:build_id   
799           │               │ event record follows this      │
800           │               │ one (not necessarily           │
801           │               │ immediately after).            │
802           ├───────────────┼────────────────────────────────┤
803has_debug_link │ Whether or not the             │
804           │               │ executable has debug link      │
805           │               │ information. If this field     │
806           │               │ is 1, you can expect that an   │
807           │               │ lttng_ust_statedump:debug_link 
808           │               │ event record follows this      │
809           │               │ one (not necessarily           │
810           │               │ immediately after).            │
811           └───────────────┴────────────────────────────────┘
812
813       lttng_ust_statedump:build_id
814           Emitted when a build ID is found in a currently loaded shared
815           library. See Debugging Information in Separate Files
816           <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
817           Files.html> for more information about build IDs.
818
819           Fields:
820
821           ┌───────────┬────────────────────────┐
822Field name Description            
823           ├───────────┼────────────────────────┤
824baddr      │ Base address of loaded │
825           │           │ library.               │
826           ├───────────┼────────────────────────┤
827build_id   │ Build ID.              │
828           └───────────┴────────────────────────┘
829
830       lttng_ust_statedump:debug_link
831           Emitted when debug link information is found in a currently loaded
832           shared library. See Debugging Information in Separate Files
833           <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
834           Files.html> for more information about debug links.
835
836           Fields:
837
838           ┌───────────┬────────────────────────┐
839Field name Description            
840           ├───────────┼────────────────────────┤
841baddr      │ Base address of loaded │
842           │           │ library.               │
843           ├───────────┼────────────────────────┤
844crc        │ Debug link file’s CRC. │
845           ├───────────┼────────────────────────┤
846filename   │ Debug link file name.  │
847           └───────────┴────────────────────────┘
848
849   Shared library load/unload tracking
850       The LTTng-UST state dump and the LTTng-UST helper library to instrument
851       the dynamic linker (see liblttng-ust-dl(3)) can emit shared library
852       load/unload tracking events.
853
854       The following shared library load/unload tracking events exist and must
855       be enabled to track the loading and unloading of shared libraries:
856
857       lttng_ust_lib:load
858           Emitted when a shared library (shared object) is loaded.
859
860           Fields:
861
862           ┌───────────────┬────────────────────────────┐
863Field name     Description                
864           ├───────────────┼────────────────────────────┤
865baddr          │ Base address of loaded     │
866           │               │ library.                   │
867           ├───────────────┼────────────────────────────┤
868memsz          │ Size of loaded library in  │
869           │               │ memory.                    │
870           ├───────────────┼────────────────────────────┤
871path           │ Path to loaded library     │
872           │               │ file.                      │
873           ├───────────────┼────────────────────────────┤
874has_build_id   │ Whether or not the library │
875           │               │ has a build ID. If this    │
876           │               │ field is 1, you can expect │
877           │               │ that an                    │
878           │               │ lttng_ust_lib:build_id     
879           │               │ event record follows this  │
880           │               │ one (not necessarily       │
881           │               │ immediately after).        │
882           ├───────────────┼────────────────────────────┤
883has_debug_link │ Whether or not the library │
884           │               │ has debug link             │
885           │               │ information. If this field │
886           │               │ is 1, you can expect that  │
887           │               │ an                         │
888           │               │ lttng_ust_lib:debug_link   
889           │               │ event record follows this  │
890           │               │ one (not necessarily       │
891           │               │ immediately after).        │
892           └───────────────┴────────────────────────────┘
893
894       lttng_ust_lib:unload
895           Emitted when a shared library (shared object) is unloaded.
896
897           Fields:
898
899           ┌───────────┬──────────────────────────┐
900Field name Description              
901           ├───────────┼──────────────────────────┤
902baddr      │ Base address of unloaded │
903           │           │ library.                 │
904           └───────────┴──────────────────────────┘
905
906       lttng_ust_lib:build_id
907           Emitted when a build ID is found in a loaded shared library (shared
908           object). See Debugging Information in Separate Files
909           <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
910           Files.html> for more information about build IDs.
911
912           Fields:
913
914           ┌───────────┬────────────────────────┐
915Field name Description            
916           ├───────────┼────────────────────────┤
917baddr      │ Base address of loaded │
918           │           │ library.               │
919           ├───────────┼────────────────────────┤
920build_id   │ Build ID.              │
921           └───────────┴────────────────────────┘
922
923       lttng_ust_lib:debug_link
924           Emitted when debug link information is found in a loaded shared
925           library (shared object). See Debugging Information in Separate
926           Files <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
927           Files.html> for more information about debug links.
928
929           Fields:
930
931           ┌───────────┬────────────────────────┐
932Field name Description            
933           ├───────────┼────────────────────────┤
934baddr      │ Base address of loaded │
935           │           │ library.               │
936           ├───────────┼────────────────────────┤
937crc        │ Debug link file’s CRC. │
938           ├───────────┼────────────────────────┤
939filename   │ Debug link file name.  │
940           └───────────┴────────────────────────┘
941
942   Detect if LTTng-UST is loaded
943       To detect if liblttng-ust is loaded from an application:
944
945        1. Define the lttng_ust_loaded weak symbol globally:
946
947               int lttng_ust_loaded __attribute__((weak));
948
949           This weak symbol is set by the constructor of liblttng-ust.
950
951        2. Test lttng_ust_loaded where needed:
952
953               /* ... */
954
955               if (lttng_ust_loaded) {
956                   /* LTTng-UST is loaded */
957               } else {
958                   /* LTTng-UST is NOT loaded */
959               }
960
961               /* ... */
962

EXAMPLE

964           Note
965           A few examples are available in the doc/examples
966           <https://github.com/lttng/lttng-ust/tree/v2.10.6/doc/examples>
967           directory of LTTng-UST’s source tree.
968
969       This example shows all the features documented in the previous
970       sections. The static linking method is chosen here to link the
971       application with the tracepoint provider.
972
973       You can compile the source files and link them together statically like
974       this:
975
976           $ cc -c -I. tp.c
977           $ cc -c app.c
978           $ cc -o app tp.o app.o -llttng-ust -ldl
979
980       Using the lttng(1) tool, create an LTTng tracing session, enable all
981       the events of this tracepoint provider, and start tracing:
982
983           $ lttng create my-session
984           $ lttng enable-event --userspace 'my_provider:*'
985           $ lttng start
986
987       You may also enable specific events:
988
989           $ lttng enable-event --userspace my_provider:big_event
990           $ lttng enable-event --userspace my_provider:event_instance2
991
992       Run the application:
993
994           $ ./app some arguments
995
996       Stop the current tracing session and inspect the recorded events:
997
998           $ lttng stop
999           $ lttng view
1000
1001   Tracepoint provider header file
1002       tp.h:
1003
1004           #undef TRACEPOINT_PROVIDER
1005           #define TRACEPOINT_PROVIDER my_provider
1006
1007           #undef TRACEPOINT_INCLUDE
1008           #define TRACEPOINT_INCLUDE "./tp.h"
1009
1010           #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
1011           #define _TP_H
1012
1013           #include <lttng/tracepoint.h>
1014           #include <stdio.h>
1015
1016           #include "app.h"
1017
1018           TRACEPOINT_EVENT(
1019               my_provider,
1020               simple_event,
1021               TP_ARGS(
1022                   int, my_integer_arg,
1023                   const char *, my_string_arg
1024               ),
1025               TP_FIELDS(
1026                   ctf_string(argc, my_string_arg)
1027                   ctf_integer(int, argv, my_integer_arg)
1028               )
1029           )
1030
1031           TRACEPOINT_ENUM(
1032               my_provider,
1033               my_enum,
1034               TP_ENUM_VALUES(
1035                   ctf_enum_value("ZERO", 0)
1036                   ctf_enum_value("ONE", 1)
1037                   ctf_enum_value("TWO", 2)
1038                   ctf_enum_range("A RANGE", 52, 125)
1039                   ctf_enum_value("ONE THOUSAND", 1000)
1040               )
1041           )
1042
1043           TRACEPOINT_EVENT(
1044               my_provider,
1045               big_event,
1046               TP_ARGS(
1047                   int, my_integer_arg,
1048                   const char *, my_string_arg,
1049                   FILE *, stream,
1050                   double, flt_arg,
1051                   int *, array_arg
1052               ),
1053               TP_FIELDS(
1054                   ctf_integer(int, int_field1, my_integer_arg * 2)
1055                   ctf_integer_hex(long int, stream_pos, ftell(stream))
1056                   ctf_float(double, float_field, flt_arg)
1057                   ctf_string(string_field, my_string_arg)
1058                   ctf_array(int, array_field, array_arg, 7)
1059                   ctf_array_text(char, array_text_field, array_arg, 5)
1060                   ctf_sequence(int, seq_field, array_arg, int,
1061                                my_integer_arg / 10)
1062                   ctf_sequence_text(char, seq_text_field, array_arg,
1063                                     int, my_integer_arg / 5)
1064                   ctf_enum(my_provider, my_enum, int,
1065                            enum_field, array_arg[1])
1066               )
1067           )
1068
1069           TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING)
1070
1071           TRACEPOINT_EVENT_CLASS(
1072               my_provider,
1073               my_tracepoint_class,
1074               TP_ARGS(
1075                   int, my_integer_arg,
1076                   struct app_struct *, app_struct_arg
1077               ),
1078               TP_FIELDS(
1079                   ctf_integer(int, a, my_integer_arg)
1080                   ctf_integer(unsigned long, b, app_struct_arg->b)
1081                   ctf_string(c, app_struct_arg->c)
1082               )
1083           )
1084
1085           TRACEPOINT_EVENT_INSTANCE(
1086               my_provider,
1087               my_tracepoint_class,
1088               event_instance1,
1089               TP_ARGS(
1090                   int, my_integer_arg,
1091                   struct app_struct *, app_struct_arg
1092               )
1093           )
1094
1095           TRACEPOINT_EVENT_INSTANCE(
1096               my_provider,
1097               my_tracepoint_class,
1098               event_instance2,
1099               TP_ARGS(
1100                   int, my_integer_arg,
1101                   struct app_struct *, app_struct_arg
1102               )
1103           )
1104
1105           TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO)
1106
1107           TRACEPOINT_EVENT_INSTANCE(
1108               my_provider,
1109               my_tracepoint_class,
1110               event_instance3,
1111               TP_ARGS(
1112                   int, my_integer_arg,
1113                   struct app_struct *, app_struct_arg
1114               )
1115           )
1116
1117           #endif /* _TP_H */
1118
1119           #include <lttng/tracepoint-event.h>
1120
1121   Tracepoint provider source file
1122       tp.c:
1123
1124           #define TRACEPOINT_CREATE_PROBES
1125           #define TRACEPOINT_DEFINE
1126
1127           #include "tp.h"
1128
1129   Application header file
1130       app.h:
1131
1132           #ifndef _APP_H
1133           #define _APP_H
1134
1135           struct app_struct {
1136               unsigned long b;
1137               const char *c;
1138               double d;
1139           };
1140
1141           #endif /* _APP_H */
1142
1143   Application source file
1144       app.c:
1145
1146           #include <stdlib.h>
1147           #include <stdio.h>
1148
1149           #include "tp.h"
1150           #include "app.h"
1151
1152           static int array_of_ints[] = {
1153               100, -35, 1, 23, 14, -6, 28, 1001, -3000,
1154           };
1155
1156           int main(int argc, char* argv[])
1157           {
1158               FILE *stream;
1159               struct app_struct app_struct;
1160
1161               tracepoint(my_provider, simple_event, argc, argv[0]);
1162               stream = fopen("/tmp/app.txt", "w");
1163
1164               if (!stream) {
1165                   fprintf(stderr,
1166                           "Error: Cannot open /tmp/app.txt for writing\n");
1167                   return EXIT_FAILURE;
1168               }
1169
1170               if (fprintf(stream, "0123456789") != 10) {
1171                   fclose(stream);
1172                   fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
1173                   return EXIT_FAILURE;
1174               }
1175
1176               tracepoint(my_provider, big_event, 35, "hello tracepoint",
1177                          stream, -3.14, array_of_ints);
1178               fclose(stream);
1179               app_struct.b = argc;
1180               app_struct.c = "[the string]";
1181               tracepoint(my_provider, event_instance1, 23, &app_struct);
1182               app_struct.b = argc * 5;
1183               app_struct.c = "[other string]";
1184               tracepoint(my_provider, event_instance2, 17, &app_struct);
1185               app_struct.b = 23;
1186               app_struct.c = "nothing";
1187               tracepoint(my_provider, event_instance3, -52, &app_struct);
1188
1189               return EXIT_SUCCESS;
1190           }
1191

ENVIRONMENT VARIABLES

1193       LTTNG_HOME
1194           Alternative user’s home directory. This variable is useful when the
1195           user running the instrumented application has a non-writable home
1196           directory.
1197
1198           Unix sockets used for the communication between liblttng-ust and
1199           the LTTng session and consumer daemons (part of the LTTng-tools
1200           project) are located in a specific directory under $LTTNG_HOME (or
1201           $HOME if $LTTNG_HOME is not set).
1202
1203       LTTNG_UST_ALLOW_BLOCKING
1204           If set, allow the application to retry event tracing when there’s
1205           no space left for the event record in the sub-buffer, therefore
1206           effectively blocking the application until space is made available
1207           or the configured timeout is reached.
1208
1209           To allow an application to block during tracing, you also need to
1210           specify a blocking timeout when you create a channel with the
1211           --blocking-timeout option of the lttng-enable-channel(1) command.
1212
1213           This option can be useful in workloads generating very large trace
1214           data throughput, where blocking the application is an acceptable
1215           trade-off to prevent discarding event records.
1216
1217               Warning
1218               Setting this environment variable may significantly affect
1219               application timings.
1220
1221       LTTNG_UST_CLOCK_PLUGIN
1222           Path to the shared object which acts as the clock override plugin.
1223           An example of such a plugin can be found in the LTTng-UST
1224           documentation under examples/clock-override
1225           <https://github.com/lttng/lttng-
1226           ust/tree/v2.10.6/doc/examples/clock-override>.
1227
1228       LTTNG_UST_DEBUG
1229           If set, enable liblttng-ust's debug and error output.
1230
1231       LTTNG_UST_GETCPU_PLUGIN
1232           Path to the shared object which acts as the getcpu() override
1233           plugin. An example of such a plugin can be found in the LTTng-UST
1234           documentation under examples/getcpu-override
1235           <https://github.com/lttng/lttng-
1236           ust/tree/v2.10.6/doc/examples/getcpu-override>.
1237
1238       LTTNG_UST_REGISTER_TIMEOUT
1239           Waiting time for the registration done session daemon command
1240           before proceeding to execute the main program (milliseconds).
1241
1242           The value 0 means do not wait. The value -1 means wait forever.
1243           Setting this environment variable to 0 is recommended for
1244           applications with time constraints on the process startup time.
1245
1246           Default: 3000.
1247
1248       LTTNG_UST_WITHOUT_BADDR_STATEDUMP
1249           If set, prevents liblttng-ust from performing a base address state
1250           dump (see the LTTng-UST state dump section above).
1251

BUGS

1253       If you encounter any issue or usability problem, please report it on
1254       the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>.
1255

RESOURCES

1257       ·   LTTng project website <http://lttng.org>
1258
1259       ·   LTTng documentation <http://lttng.org/docs>
1260
1261       ·   Git repositories <http://git.lttng.org>
1262
1263       ·   GitHub organization <http://github.com/lttng>
1264
1265       ·   Continuous integration <http://ci.lttng.org/>
1266
1267       ·   Mailing list <http://lists.lttng.org> for support and development:
1268           lttng-dev@lists.lttng.org
1269
1270       ·   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
1271

COPYRIGHTS

1273       This library is part of the LTTng-UST project.
1274
1275       This library is distributed under the GNU Lesser General Public
1276       License, version 2.1 <http://www.gnu.org/licenses/old-
1277       licenses/lgpl-2.1.en.html>. See the COPYING
1278       <https://github.com/lttng/lttng-ust/blob/v2.10.6/COPYING> file for more
1279       details.
1280

THANKS

1282       Thanks to Ericsson for funding this work, providing real-life use
1283       cases, and testing.
1284
1285       Special thanks to Michel Dagenais and the DORSAL laboratory
1286       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
1287       the LTTng journey.
1288

AUTHORS

1290       LTTng-UST was originally written by Mathieu Desnoyers, with additional
1291       contributions from various other people. It is currently maintained by
1292       Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
1293

SEE ALSO

1295       tracef(3), tracelog(3), lttng-gen-tp(1), lttng-ust-dl(3), lttng-ust-
1296       cyg-profile(3), lttng(1), lttng-enable-event(1), lttng-list(1), lttng-
1297       add-context(1), babeltrace(1), dlopen(3), ld.so(8)
1298
1299
1300
1301LTTng 2.10.6                      10/17/2019                      LTTNG-UST(3)
Impressum