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,
14                                      args, fields)
15       #define TRACEPOINT_EVENT_INSTANCE(prov_name, class_name,
16                                         t_name, args)
17       #define TRACEPOINT_LOGLEVEL(prov_name, t_name, level)
18       #define ctf_array(int_type, field_name, expr, count)
19       #define ctf_array_nowrite(int_type, field_name, expr, count)
20       #define ctf_array_text(char, field_name, expr, count)
21       #define ctf_array_text_nowrite(char, field_name, expr, count)
22       #define ctf_enum(prov_name, enum_name, int_type, field_name, expr)
23       #define ctf_enum_nowrite(prov_name, enum_name, int_type,
24                                field_name, expr)
25       #define ctf_enum_value(label, value)
26       #define ctf_enum_range(label, start, end)
27       #define ctf_float(float_type, field_name, expr)
28       #define ctf_float_nowrite(float_type, field_name, expr)
29       #define ctf_integer(int_type, field_name, expr)
30       #define ctf_integer_hex(int_type, field_name, expr)
31       #define ctf_integer_network(int_type, field_name, expr)
32       #define ctf_integer_network_hex(int_type, field_name, expr)
33       #define ctf_integer_nowrite(int_type, field_name, expr)
34       #define ctf_sequence(int_type, field_name, expr, len_type, len_expr)
35       #define ctf_sequence_nowrite(int_type, field_name, expr,
36                                    len_type, len_expr)
37       #define ctf_sequence_text(char, field_name, expr, len_type, len_expr)
38       #define ctf_sequence_text_nowrite(char, field_name, expr,
39                                         len_type, len_expr)
40       #define ctf_string(field_name, expr)
41       #define ctf_string_nowrite(field_name, expr)
42       #define do_tracepoint(prov_name, t_name, ...)
43       #define tracepoint(prov_name, t_name, ...)
44       #define tracepoint_enabled(prov_name, t_name)
45
46       Link with -llttng-ust -ldl, following this man page.
47

DESCRIPTION

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

EXAMPLE

785           Note
786           A few examples are available in the doc/examples
787           <https://github.com/lttng/lttng-ust/tree/master/doc/examples>
788           directory of LTTng-UST’s source tree.
789
790       This example shows all the features documented in the previous
791       sections. The static linking method is chosen here to link the
792       application with the tracepoint provider.
793
794       You can compile the source files and link them together statically like
795       this:
796
797           cc -c -I. tp.c
798           cc -c app.c
799           cc -o app tp.o app.o -llttng-ust -ldl
800
801       Using the lttng(1) tool, create an LTTng tracing session, enable all
802       the events of this tracepoint provider, and start tracing:
803
804           lttng create my-session
805           lttng enable-event --userspace 'my_provider:*'
806           lttng start
807
808       You may also enable specific events:
809
810           lttng enable-event --userspace my_provider:big_event
811           lttng enable-event --userspace my_provider:event_instance2
812
813       Run the application:
814
815           ./app some arguments
816
817       Stop the current tracing session and inspect the recorded events:
818
819           lttng stop
820           lttng view
821
822   Tracepoint provider header file
823       tp.h:
824
825           #undef TRACEPOINT_PROVIDER
826           #define TRACEPOINT_PROVIDER my_provider
827
828           #undef TRACEPOINT_INCLUDE
829           #define TRACEPOINT_INCLUDE "./tp.h"
830
831           #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
832           #define _TP_H
833
834           #include <lttng/tracepoint.h>
835           #include <stdio.h>
836
837           #include "app.h"
838
839           TRACEPOINT_EVENT(
840               my_provider,
841               simple_event,
842               TP_ARGS(
843                   int, my_integer_arg,
844                   const char *, my_string_arg
845               ),
846               TP_FIELDS(
847                   ctf_string(argc, my_string_arg)
848                   ctf_integer(int, argv, my_integer_arg)
849               )
850           )
851
852           TRACEPOINT_ENUM(
853               my_provider,
854               my_enum,
855               TP_ENUM_VALUES(
856                   ctf_enum_value("ZERO", 0)
857                   ctf_enum_value("ONE", 1)
858                   ctf_enum_value("TWO", 2)
859                   ctf_enum_range("A RANGE", 52, 125)
860                   ctf_enum_value("ONE THOUSAND", 1000)
861               )
862           )
863
864           TRACEPOINT_EVENT(
865               my_provider,
866               big_event,
867               TP_ARGS(
868                   int, my_integer_arg,
869                   const char *, my_string_arg,
870                   FILE *, stream,
871                   double, flt_arg,
872                   int *, array_arg
873               ),
874               TP_FIELDS(
875                   ctf_integer(int, int_field1, my_integer_arg * 2)
876                   ctf_integer_hex(long int, stream_pos, ftell(stream))
877                   ctf_float(double, float_field, flt_arg)
878                   ctf_string(string_field, my_string_arg)
879                   ctf_array(int, array_field, array_arg, 7)
880                   ctf_array_text(char, array_text_field, array_arg, 5)
881                   ctf_sequence(int, seq_field, array_arg, int,
882                                my_integer_arg / 10)
883                   ctf_sequence_text(char, seq_text_field, array_arg,
884                                     int, my_integer_arg / 5)
885                   ctf_enum(my_provider, my_enum, int,
886                            enum_field, array_arg[1])
887               )
888           )
889
890           TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING)
891
892           TRACEPOINT_EVENT_CLASS(
893               my_provider,
894               my_tracepoint_class,
895               TP_ARGS(
896                   int, my_integer_arg,
897                   struct app_struct *, app_struct_arg
898               ),
899               TP_FIELDS(
900                   ctf_integer(int, a, my_integer_arg)
901                   ctf_integer(unsigned long, b, app_struct_arg->b)
902                   ctf_string(c, app_struct_arg->c)
903               )
904           )
905
906           TRACEPOINT_EVENT_INSTANCE(
907               my_provider,
908               my_tracepoint_class,
909               event_instance1,
910               TP_ARGS(
911                   int, my_integer_arg,
912                   struct app_struct *, app_struct_arg
913               )
914           )
915
916           TRACEPOINT_EVENT_INSTANCE(
917               my_provider,
918               my_tracepoint_class,
919               event_instance2,
920               TP_ARGS(
921                   int, my_integer_arg,
922                   struct app_struct *, app_struct_arg
923               )
924           )
925
926           TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO)
927
928           TRACEPOINT_EVENT_INSTANCE(
929               my_provider,
930               my_tracepoint_class,
931               event_instance3,
932               TP_ARGS(
933                   int, my_integer_arg,
934                   struct app_struct *, app_struct_arg
935               )
936           )
937
938           #endif /* _TP_H */
939
940           #include <lttng/tracepoint-event.h>
941
942   Tracepoint provider source file
943       tp.c:
944
945           #define TRACEPOINT_CREATE_PROBES
946           #define TRACEPOINT_DEFINE
947
948           #include "tp.h"
949
950   Application header file
951       app.h:
952
953           #ifndef _APP_H
954           #define _APP_H
955
956           struct app_struct {
957               unsigned long b;
958               const char *c;
959               double d;
960           };
961
962           #endif /* _APP_H */
963
964   Application source file
965       app.c:
966
967           #include <stdlib.h>
968           #include <stdio.h>
969
970           #include "tp.h"
971           #include "app.h"
972
973           static int array_of_ints[] = {
974               100, -35, 1, 23, 14, -6, 28, 1001, -3000,
975           };
976
977           int main(int argc, char* argv[])
978           {
979               FILE *stream;
980               struct app_struct app_struct;
981
982               tracepoint(my_provider, simple_event, argc, argv[0]);
983               stream = fopen("/tmp/app.txt", "w");
984
985               if (!stream) {
986                   fprintf(stderr,
987                           "Error: Cannot open /tmp/app.txt for writing\n");
988                   return EXIT_FAILURE;
989               }
990
991               if (fprintf(stream, "0123456789") != 10) {
992                   fclose(stream);
993                   fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
994                   return EXIT_FAILURE;
995               }
996
997               tracepoint(my_provider, big_event, 35, "hello tracepoint",
998                          stream, -3.14, array_of_ints);
999               fclose(stream);
1000               app_struct.b = argc;
1001               app_struct.c = "[the string]";
1002               tracepoint(my_provider, event_instance1, 23, &app_struct);
1003               app_struct.b = argc * 5;
1004               app_struct.c = "[other string]";
1005               tracepoint(my_provider, event_instance2, 17, &app_struct);
1006               app_struct.b = 23;
1007               app_struct.c = "nothing";
1008               tracepoint(my_provider, event_instance3, -52, &app_struct);
1009
1010               return EXIT_SUCCESS;
1011           }
1012

ENVIRONMENT VARIABLES

1014       LTTNG_HOME
1015           Alternative user’s home directory. This variable is useful when the
1016           user running the instrumented application has a non-writable home
1017           directory.
1018
1019           Unix sockets used for the communication between liblttng-ust and
1020           the LTTng session and consumer daemons (part of the LTTng-tools
1021           project) are located in a specific directory under $LTTNG_HOME (or
1022           $HOME if $LTTNG_HOME is not set).
1023
1024       LTTNG_UST_CLOCK_PLUGIN
1025           Path to the shared object which acts as the clock override plugin.
1026           An example of such a plugin can be found in the LTTng-UST
1027           documentation under examples/clock-override
1028           <https://github.com/lttng/lttng-ust/tree/master/doc/examples/clock-
1029           override>.
1030
1031       LTTNG_UST_DEBUG
1032           Activates liblttng-ust's debug and error output if set to 1.
1033
1034       LTTNG_UST_GETCPU_PLUGIN
1035           Path to the shared object which acts as the getcpu() override
1036           plugin. An example of such a plugin can be found in the LTTng-UST
1037           documentation under examples/getcpu-override
1038           <https://github.com/lttng/lttng-
1039           ust/tree/master/doc/examples/getcpu-override>.
1040
1041       LTTNG_UST_REGISTER_TIMEOUT
1042           Waiting time for the registration done session daemon command
1043           before proceeding to execute the main program (milliseconds).
1044
1045           The value 0 means do not wait. The value -1 means wait forever.
1046           Setting this environment variable to 0 is recommended for
1047           applications with time constraints on the process startup time.
1048
1049           Default: 3000.
1050
1051       LTTNG_UST_WITHOUT_BADDR_STATEDUMP
1052           Prevents liblttng-ust from performing a base address state dump
1053           (see the LTTng-UST state dump section above) if set to 1.
1054

BUGS

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

RESOURCES

1060       ·   LTTng project website <http://lttng.org>
1061
1062       ·   LTTng documentation <http://lttng.org/docs>
1063
1064       ·   Git repositories <http://git.lttng.org>
1065
1066       ·   GitHub organization <http://github.com/lttng>
1067
1068       ·   Continuous integration <http://ci.lttng.org/>
1069
1070       ·   Mailing list <http://lists.lttng.org> for support and development:
1071           lttng-dev@lists.lttng.org
1072
1073       ·   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
1074

COPYRIGHTS

1076       This library is part of the LTTng-UST project.
1077
1078       This library is distributed under the GNU Lesser General Public
1079       License, version 2.1 <http://www.gnu.org/licenses/old-
1080       licenses/lgpl-2.1.en.html>. See the COPYING
1081       <https://github.com/lttng/lttng-ust/blob/master/COPYING> file for more
1082       details.
1083

THANKS

1085       Thanks to Ericsson for funding this work, providing real-life use
1086       cases, and testing.
1087
1088       Special thanks to Michel Dagenais and the DORSAL laboratory
1089       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
1090       the LTTng journey.
1091

AUTHORS

1093       LTTng-UST was originally written by Mathieu Desnoyers, with additional
1094       contributions from various other people. It is currently maintained by
1095       Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
1096

SEE ALSO

1098       tracef(3), tracelog(3), lttng-gen-tp(1), lttng-ust-dl(3), lttng-ust-
1099       cyg-profile(3), lttng(1), lttng-enable-event(1), lttng-list(1), lttng-
1100       add-context(1), babeltrace(1), dlopen(3), ld.so(8)
1101
1102
1103
1104LTTng 2.9.0-pre                   06/05/2016                      LTTNG-UST(3)
Impressum