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 LTTNG_UST_TP_ARGS(args...)
12       #define LTTNG_UST_TP_ENUM_VALUES(values...)
13       #define LTTNG_UST_TP_FIELDS(fields...)
14       #define LTTNG_UST_TRACEPOINT_ENUM(prov_name, enum_name, mappings)
15       #define LTTNG_UST_TRACEPOINT_EVENT(prov_name, t_name, args, fields)
16       #define LTTNG_UST_TRACEPOINT_EVENT_CLASS(cls_prov_name, cls_name,
17                                                args, fields)
18       #define LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(cls_prov_name, cls_name,
19                                                   inst_prov_name, t_name, args)
20       #define LTTNG_UST_TRACEPOINT_LOGLEVEL(prov_name, t_name, level)
21       #define lttng_ust_do_tracepoint(prov_name, t_name, ...)
22       #define lttng_ust_field_array(int_type, field_name, expr, count)
23       #define lttng_ust_field_array_nowrite(int_type, field_name, expr, count)
24       #define lttng_ust_field_array_hex(int_type, field_name, expr, count)
25       #define lttng_ust_field_array_nowrite_hex(int_type, field_name, expr,
26                                                 count)
27       #define lttng_ust_field_array_network(int_type, field_name, expr, count)
28       #define lttng_ust_field_array_network_nowrite(int_type, field_name,
29                                                     expr, count)
30       #define lttng_ust_field_array_network_hex(int_type, field_name, expr,
31                                                 count)
32       #define lttng_ust_field_array_network_nowrite_hex(int_type, field_name,
33                                                         expr, count)
34       #define lttng_ust_field_array_text(char, field_name, expr, count)
35       #define lttng_ust_field_array_text_nowrite(char, field_name, expr,
36                                                  count)
37       #define lttng_ust_field_enum(prov_name, enum_name, int_type, field_name,
38                                    expr)
39       #define lttng_ust_field_enum_nowrite(prov_name, enum_name, int_type,
40                                            field_name, expr)
41       #define lttng_ust_field_enum_value(label, value)
42       #define lttng_ust_field_enum_range(label, start, end)
43       #define lttng_ust_field_float(float_type, field_name, expr)
44       #define lttng_ust_field_float_nowrite(float_type, field_name, expr)
45       #define lttng_ust_field_integer(int_type, field_name, expr)
46       #define lttng_ust_field_integer_hex(int_type, field_name, expr)
47       #define lttng_ust_field_integer_network(int_type, field_name, expr)
48       #define lttng_ust_field_integer_network_hex(int_type, field_name, expr)
49       #define lttng_ust_field_integer_nowrite(int_type, field_name, expr)
50       #define lttng_ust_field_sequence(int_type, field_name, expr,
51                                        len_type, len_expr)
52       #define lttng_ust_field_sequence_nowrite(int_type, field_name, expr,
53                                                len_type, len_expr)
54       #define lttng_ust_field_sequence_hex(int_type, field_name, expr,
55                                            len_type, len_expr)
56       #define lttng_ust_field_sequence_nowrite_hex(int_type, field_name, expr,
57                                                    len_type, len_expr)
58       #define lttng_ust_field_sequence_network(int_type, field_name, expr,
59                                                len_type, len_expr)
60       #define lttng_ust_field_sequence_network_nowrite(int_type, field_name,
61                                                        expr, len_type,
62                                                        len_expr)
63       #define lttng_ust_field_sequence_network_hex(int_type, field_name, expr,
64                                                    len_type, len_expr)
65       #define lttng_ust_field_sequence_network_nowrite_hex(int_type,
66                                                            field_name,
67                                                            expr, len_type,
68                                                            len_expr)
69       #define lttng_ust_field_sequence_text(char, field_name, expr, len_type,
70                                             len_expr)
71       #define lttng_ust_field_sequence_text_nowrite(char, field_name, expr,
72                                                     len_type, len_expr)
73       #define lttng_ust_field_string(field_name, expr)
74       #define lttng_ust_field_string_nowrite(field_name, expr)
75       #define lttng_ust_tracepoint(prov_name, t_name, ...)
76       #define lttng_ust_tracepoint_enabled(prov_name, t_name)
77
78       Link with, following this manual page:
79
80-llttng-ust -ldl
81
82       •   If you define _LGPL_SOURCE before including <lttng/tracepoint.h>
83           (directly or indirectly): -llttng-ust-common
84

DESCRIPTION

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

EXAMPLE

1153           Note
1154           A few examples are available in the directory of LTTng-UST’s source
1155           tree.
1156
1157       This example shows all the features documented in the previous
1158       sections. The static linking method is chosen here to link the
1159       application with the tracepoint provider.
1160
1161       You can compile the source files and link them together statically like
1162       this:
1163
1164           $ cc -c -I. tp.c
1165           $ cc -c app.c
1166           $ cc -o app tp.o app.o -llttng-ust -ldl
1167
1168       Using the lttng(1) tool, create an LTTng tracing session, enable all
1169       the events of this tracepoint provider, and start tracing:
1170
1171           $ lttng create my-session
1172           $ lttng enable-event --userspace 'my_provider:*'
1173           $ lttng start
1174
1175       You may also enable specific events:
1176
1177           $ lttng enable-event --userspace my_provider:big_event
1178           $ lttng enable-event --userspace my_provider:event_instance2
1179
1180       Run the application:
1181
1182           $ ./app some arguments
1183
1184       Stop the current tracing session and inspect the recorded events:
1185
1186           $ lttng stop
1187           $ lttng view
1188
1189   Tracepoint provider header file
1190       tp.h:
1191
1192           #undef LTTNG_UST_TRACEPOINT_PROVIDER
1193           #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
1194
1195           #undef LTTNG_USTTRACEPOINT_INCLUDE
1196           #define LTTNG_USTTRACEPOINT_INCLUDE "./tp.h"
1197
1198           #if !defined(_TP_H) || \
1199               defined(LTTNG_UST_TRACEPOINT_HEADER_MULTI_READ)
1200           #define _TP_H
1201
1202           #include <lttng/tracepoint.h>
1203           #include <stdio.h>
1204
1205           #include "app.h"
1206
1207           LTTNG_UST_TRACEPOINT_EVENT(
1208               my_provider,
1209               simple_event,
1210               LTTNG_UST_TP_ARGS(
1211                   int, my_integer_arg,
1212                   const char *, my_string_arg
1213               ),
1214               LTTNG_UST_TP_FIELDS(
1215                   lttng_ust_field_string(argc, my_string_arg)
1216                   lttng_ust_field_integer(int, argv, my_integer_arg)
1217               )
1218           )
1219
1220           LTTNG_UST_TRACEPOINT_ENUM(
1221               my_provider,
1222               my_enum,
1223               LTTNG_UST_TP_ENUM_VALUES(
1224                   lttng_ust_field_enum_value("ZERO", 0)
1225                   lttng_ust_field_enum_value("ONE", 1)
1226                   lttng_ust_field_enum_value("TWO", 2)
1227                   lttng_ust_field_enum_range("A RANGE", 52, 125)
1228                   lttng_ust_field_enum_value("ONE THOUSAND", 1000)
1229               )
1230           )
1231
1232           LTTNG_UST_TRACEPOINT_EVENT(
1233               my_provider,
1234               big_event,
1235               LTTNG_UST_TP_ARGS(
1236                   int, my_integer_arg,
1237                   const char *, my_string_arg,
1238                   FILE *, stream,
1239                   double, flt_arg,
1240                   int *, array_arg
1241               ),
1242               LTTNG_UST_TP_FIELDS(
1243                   lttng_ust_field_integer(int, int_field1, my_integer_arg * 2)
1244                   lttng_ust_field_integer_hex(long int, stream_pos,
1245                                               ftell(stream))
1246                   lttng_ust_field_float(double, float_field, flt_arg)
1247                   lttng_ust_field_string(string_field, my_string_arg)
1248                   lttng_ust_field_array(int, array_field, array_arg, 7)
1249                   lttng_ust_field_array_text(char, array_text_field,
1250                                              array_arg, 5)
1251                   lttng_ust_field_sequence(int, seq_field, array_arg, int,
1252                                            my_integer_arg / 10)
1253                   lttng_ust_field_sequence_text(char, seq_text_field,
1254                                                 array_arg, int,
1255                                                 my_integer_arg / 5)
1256                   lttng_ust_field_enum(my_provider, my_enum, int,
1257                                        enum_field, array_arg[1])
1258               )
1259           )
1260
1261           LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, big_event,
1262                                         LTTNG_UST_TRACEPOINT_LOGLEVEL_WARNING)
1263
1264           LTTNG_UST_TRACEPOINT_EVENT_CLASS(
1265               my_provider,
1266               my_tracepoint_class,
1267               LTTNG_UST_TP_ARGS(
1268                   int, my_integer_arg,
1269                   struct app_struct *, app_struct_arg
1270               ),
1271               LTTNG_UST_TP_FIELDS(
1272                   lttng_ust_field_integer(int, a, my_integer_arg)
1273                   lttng_ust_field_integer(unsigned long, b, app_struct_arg->b)
1274                   lttng_ust_field_string(c, app_struct_arg->c)
1275               )
1276           )
1277
1278           LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
1279               my_provider,
1280               my_tracepoint_class,
1281               my_provider,
1282               event_instance1,
1283               LTTNG_UST_TP_ARGS(
1284                   int, my_integer_arg,
1285                   struct app_struct *, app_struct_arg
1286               )
1287           )
1288
1289           LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
1290               my_provider,
1291               my_tracepoint_class,
1292               my_provider,
1293               event_instance2,
1294               LTTNG_UST_TP_ARGS(
1295                   int, my_integer_arg,
1296                   struct app_struct *, app_struct_arg
1297               )
1298           )
1299
1300           LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, event_instance2,
1301                                         LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO)
1302
1303           LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
1304               my_provider,
1305               my_tracepoint_class,
1306               my_provider,
1307               event_instance3,
1308               LTTNG_UST_TP_ARGS(
1309                   int, my_integer_arg,
1310                   struct app_struct *, app_struct_arg
1311               )
1312           )
1313
1314           #endif /* _TP_H */
1315
1316           #include <lttng/tracepoint-event.h>
1317
1318   Tracepoint provider source file
1319       tp.c:
1320
1321           #define LTTNG_UST_TRACEPOINT_CREATE_PROBES
1322           #define LTTNG_UST_TRACEPOINT_DEFINE
1323
1324           #include "tp.h"
1325
1326   Application header file
1327       app.h:
1328
1329           #ifndef _APP_H
1330           #define _APP_H
1331
1332           struct app_struct {
1333               unsigned long b;
1334               const char *c;
1335               double d;
1336           };
1337
1338           #endif /* _APP_H */
1339
1340   Application source file
1341       app.c:
1342
1343           #include <stdlib.h>
1344           #include <stdio.h>
1345
1346           #include "tp.h"
1347           #include "app.h"
1348
1349           static int array_of_ints[] = {
1350               100, -35, 1, 23, 14, -6, 28, 1001, -3000,
1351           };
1352
1353           int main(int argc, char* argv[])
1354           {
1355               FILE *stream;
1356               struct app_struct app_struct;
1357
1358               lttng_ust_tracepoint(my_provider, simple_event, argc, argv[0]);
1359               stream = fopen("/tmp/app.txt", "w");
1360
1361               if (!stream) {
1362                   fprintf(stderr,
1363                           "Error: Cannot open /tmp/app.txt for writing\n");
1364                   return EXIT_FAILURE;
1365               }
1366
1367               if (fprintf(stream, "0123456789") != 10) {
1368                   fclose(stream);
1369                   fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
1370                   return EXIT_FAILURE;
1371               }
1372
1373               lttng_ust_tracepoint(my_provider, big_event, 35,
1374                                    "hello tracepoint", stream, -3.14,
1375                                    array_of_ints);
1376               fclose(stream);
1377               app_struct.b = argc;
1378               app_struct.c = "[the string]";
1379               lttng_ust_tracepoint(my_provider, event_instance1, 23,
1380                                    &app_struct);
1381               app_struct.b = argc * 5;
1382               app_struct.c = "[other string]";
1383               lttng_ust_tracepoint(my_provider, event_instance2, 17,
1384                                    &app_struct);
1385               app_struct.b = 23;
1386               app_struct.c = "nothing";
1387               lttng_ust_tracepoint(my_provider, event_instance3, -52,
1388                                    &app_struct);
1389               return EXIT_SUCCESS;
1390           }
1391

ENVIRONMENT VARIABLES

1393       LTTNG_HOME
1394           Alternative user’s home directory. This variable is useful when the
1395           user running the instrumented application has a non-writable home
1396           directory.
1397
1398           Unix sockets used for the communication between liblttng-ust and
1399           the LTTng session and consumer daemons (part of the LTTng-tools
1400           project) are located in a specific directory under $LTTNG_HOME (or
1401           $HOME if $LTTNG_HOME is not set).
1402
1403       LTTNG_UST_ALLOW_BLOCKING
1404           If set, allow the application to retry event tracing when there’s
1405           no space left for the event record in the sub-buffer, therefore
1406           effectively blocking the application until space is made available
1407           or the configured timeout is reached.
1408
1409           To allow an application to block during tracing, you also need to
1410           specify a blocking timeout when you create a channel with the
1411           --blocking-timeout option of the lttng-enable-channel(1) command.
1412
1413           This option can be useful in workloads generating very large trace
1414           data throughput, where blocking the application is an acceptable
1415           trade-off to prevent discarding event records.
1416
1417               Warning
1418               Setting this environment variable may significantly affect
1419               application timings.
1420
1421       LTTNG_UST_ABORT_ON_CRITICAL
1422           If set, abort the instrumented application on a critical error
1423           message.
1424
1425       LTTNG_UST_CLOCK_PLUGIN
1426           Path to the shared object which acts as the clock override plugin.
1427           An example of such a plugin can be found in the LTTng-UST
1428           documentation under
1429
1430       LTTNG_UST_DEBUG
1431           If set, enable liblttng-ust's debug and error output.
1432
1433       LTTNG_UST_GETCPU_PLUGIN
1434           Path to the shared object which acts as the getcpu() override
1435           plugin. An example of such a plugin can be found in the LTTng-UST
1436           documentation under
1437
1438       LTTNG_UST_REGISTER_TIMEOUT
1439           Waiting time for the registration done session daemon command
1440           before proceeding to execute the main program (milliseconds).
1441
1442           The value 0 means do not wait. The value -1 means wait forever.
1443           Setting this environment variable to 0 is recommended for
1444           applications with time constraints on the process startup time.
1445
1446           Default: 3000.
1447
1448       LTTNG_UST_WITHOUT_BADDR_STATEDUMP
1449           If set, prevents liblttng-ust from performing a base address state
1450           dump (see the LTTng-UST state dump section above).
1451
1452       LTTNG_UST_WITHOUT_PROCNAME_STATEDUMP
1453           If set, prevents liblttng-ust from performing a procname state dump
1454           (see the LTTng-UST state dump section above).
1455

BUGS

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

RESOURCES

1461       •   LTTng project website <http://lttng.org>
1462
1463       •   LTTng documentation <http://lttng.org/docs>
1464
1465       •   Git repositories <http://git.lttng.org>
1466
1467       •   GitHub organization <http://github.com/lttng>
1468
1469       •   Continuous integration <http://ci.lttng.org/>
1470
1471       •   Mailing list <http://lists.lttng.org> for support and development:
1472           lttng-dev@lists.lttng.org
1473
1474       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
1475

COPYRIGHTS

1477       This library is part of the LTTng-UST project.
1478
1479       This library is distributed under the GNU Lesser General Public
1480       License, version 2.1 <http://www.gnu.org/licenses/old-
1481       licenses/lgpl-2.1.en.html>. See the for more details.
1482

THANKS

1484       Thanks to Ericsson for funding this work, providing real-life use
1485       cases, and testing.
1486
1487       Special thanks to Michel Dagenais and the DORSAL laboratory
1488       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
1489       the LTTng journey.
1490

AUTHORS

1492       LTTng-UST was originally written by Mathieu Desnoyers, with additional
1493       contributions from various other people. It is currently maintained by
1494       Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
1495

SEE ALSO

1497       lttng_ust_tracef(3), lttng_ust_tracelog(3), lttng-gen-tp(1), lttng-ust-
1498       dl(3), lttng-ust-cyg-profile(3), lttng(1), lttng-enable-event(1),
1499       lttng-list(1), lttng-add-context(1), babeltrace(1), dlopen(3), ld.so(8)
1500
1501
1502
1503LTTng 2.13.6                      06/07/2023                      LTTNG-UST(3)
Impressum