1LTTNG-UST(3) LTTng Manual LTTNG-UST(3)
2
6 lttng-ust - LTTng user space tracing
7
9 #include <lttng/tracepoint.h>
10 #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 Link with, following this manual page:
79 • -llttng-ust -ldl
81 • If you define _LGPL_SOURCE before including <lttng/tracepoint.h>
83 (directly or indirectly): -llttng-ust-common
84
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 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 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 There are three ways to use liblttng-ust:
103 • Using the lttng_ust_tracef(3) API, which is similar to printf(3).
105 • Using the lttng_ust_tracelog(3) API, which is lttng_ust_tracef(3)
107 with a log level parameter.
108 • Defining your own tracepoints. See the Creating a tracepoint
110 provider section below.
111 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 Undefined
117 All APIs are available.
118 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 The following table shows the mapping from LTTng-UST versions (up to
124 LTTng-UST 2.13.1) to available API versions:
125 ┌──────────────────┬────────────────────────┐
127 │LTTng-UST version │ Available API versions │
128 ├──────────────────┼────────────────────────┤
129 │ │ │
130 │2.0 to 2.12 │ 0 │
131 ├──────────────────┼────────────────────────┤
132 │ │ │
133 │2.13 │ 0 and 1 │
134 └──────────────────┴────────────────────────┘
135 This manual page only documents version 1 of the API.
137 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 Creating a tracepoint provider
144 Creating a tracepoint provider is the first step of using liblttng-ust.
145 The next steps are:
146 • Instrumenting your application with lttng_ust_tracepoint() calls
148 • Building your application with LTTng-UST support, either statically
150 or dynamically.
151 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 To create a tracepoint provider, start with the following tracepoint
158 provider header template:
159 #undef LTTNG_UST_TRACEPOINT_PROVIDER
161 #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
162 #undef LTTNG_UST_TRACEPOINT_INCLUDE
164 #define LTTNG_UST_TRACEPOINT_INCLUDE "./tp.h"
165 #if !defined(_TP_H) || \
167 defined(LTTNG_UST_TRACEPOINT_HEADER_MULTI_READ)
168 #define _TP_H
169 #include <lttng/tracepoint.h>
171 /*
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 #endif /* _TP_H */
180 #include <lttng/tracepoint-event.h>
182 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 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 The tracepoint provider header file needs to be included in a source
198 file which looks like this:
199 #define LTTNG_UST_TRACEPOINT_CREATE_PROBES
201 #include "tp.h"
203 Together, those two files (let’s call them tp.h and tp.c) form the
205 tracepoint provider sources, ready to be compiled.
206 You can create multiple tracepoint providers to be used in a single
208 application, but each one must have its own header file.
209 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 See the EXAMPLE section below for a complete example.
215 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 The LTTNG_UST_TRACEPOINT_EVENT() usage template is as follows:
222 LTTNG_UST_TRACEPOINT_EVENT(
224 /* Tracepoint provider name */
225 my_provider,
226 /* Tracepoint/event name */
228 my_tracepoint,
229 /* List of tracepoint arguments (input) */
231 LTTNG_UST_TP_ARGS(
232 ...
233 ),
234 /* List of fields of eventual event (output) */
236 LTTNG_UST_TP_FIELDS(
237 ...
238 )
239 )
240 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 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 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 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 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 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 Standard integer, displayed in base 10:
270 lttng_ust_field_integer(int_type, field_name, expr)
272 lttng_ust_field_integer_nowrite(int_type, field_name, expr)
273 Standard integer, displayed in base 16:
275 lttng_ust_field_integer_hex(int_type, field_name, expr)
277 Integer in network byte order (big endian), displayed in base 10:
279 lttng_ust_field_integer_network(int_type, field_name, expr)
281 Integer in network byte order, displayed in base 16:
283 lttng_ust_field_integer_network_hex(int_type, field_name, expr)
285 Floating point number:
287 lttng_ust_field_float(float_type, field_name, expr)
289 lttng_ust_field_float_nowrite(float_type, field_name, expr)
290 Null-terminated string:
292 lttng_ust_field_string(field_name, expr)
294 lttng_ust_field_string_nowrite(field_name, expr)
295 Statically-sized array of integers (_hex versions displayed in
297 hexadecimal, _network versions in network byte order):
298 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 Statically-sized array, printed as text; no need to be null-terminated:
311 lttng_ust_field_array_text(char, field_name, expr, count)
313 lttng_ust_field_array_text_nowrite(char, field_name, expr, count)
314 Dynamically-sized array of integers (_hex versions displayed in
316 hexadecimal, _network versions in network byte order):
317 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 Dynamically-sized array, displayed as text; no need to be
337 null-terminated:
338 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 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 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 The parameters are:
354 count
356 Number of elements in array/sequence. This must be known at compile
357 time.
358 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 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 field_name
371 Event field name (C identifier syntax, NOT a literal string).
372 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 int_type
378 Integer C type. The size of this type determines the size of the
379 integer/enumeration field.
380 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 len_type
386 Unsigned integer C type of sequence’s length.
387 prov_name
389 Tracepoint provider name. This must be the same as the tracepoint
390 provider name used in a previous field definition.
391 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 See the EXAMPLE section below for a complete example.
399 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 An enumeration field is defined with the LTTNG_UST_TRACEPOINT_ENUM()
407 macro:
408 LTTNG_UST_TRACEPOINT_ENUM(
410 /* Tracepoint provider name */
411 my_provider,
412 /* Enumeration name (unique in the whole tracepoint provider) */
414 my_enum,
415 /* Enumeration mappings */
417 LTTNG_UST_TP_ENUM_VALUES(
418 ...
419 )
420 )
421 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 lttng_ust_field_enum_value() is a single value mapping:
428 lttng_ust_field_enum_value(label, value)
430 This macro maps the given label string to the value value.
432 lttng_ust_field_enum_range() is a range mapping:
434 lttng_ust_field_enum_range(label, start, end)
436 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 See the EXAMPLE section below for a complete example.
443 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 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 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 #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
465 /* ... */
467 LTTNG_UST_TRACEPOINT_EVENT_CLASS(
469 /* Tracepoint class provider name */
470 my_provider,
471 /* Tracepoint class name */
473 my_tracepoint_class,
474 /* List of tracepoint arguments (input) */
476 LTTNG_UST_TP_ARGS(
477 ...
478 ),
479 /* List of fields of eventual event (output) */
481 LTTNG_UST_TP_FIELDS(
482 ...
483 )
484 )
485 Once the tracepoint class is defined, you can create as many tracepoint
487 instances as needed:
488 #define LTTNG_UST_TRACEPOINT_PROVIDER natality
490 /* ... */
492 LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
494 /* Name of the tracepoint class provider */
495 my_provider,
496 /* Tracepoint class name */
498 my_tracepoint_class,
499 /* Name of the local (instance) tracepoint provider */
501 natality,
502 /* Tracepoint/event name */
504 my_tracepoint,
505 /* List of tracepoint arguments (input) */
507 LTTNG_UST_TP_ARGS(
508 ...
509 )
510 )
511 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 Note that the LTTNG_UST_TRACEPOINT_EVENT_INSTANCE() macro requires two
517 provider names:
518 • The name of the tracepoint class provider (my_provider in the
520 example above).
521 This is the same as the first argument of the
523 LTTNG_UST_TRACEPOINT_EVENT_CLASS() expansion to refer to.
524 • The name of the local, or instance, provider (natality in the
526 example above).
527 This is the provider name which becomes the prefix part of the name
529 of the events which such a tracepoint creates.
530 The two provider names may be different if the tracepoint class and the
532 tracepoint instance macros are in two different translation units.
533 See the EXAMPLE section below for a complete example.
535 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 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 LTTNG_UST_TRACEPOINT_LOGLEVEL(
550 /* Tracepoint provider name */
551 my_provider,
552 /* Tracepoint/event name */
554 my_tracepoint,
555 /* Log level */
557 LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO
558 )
559 The available log level definitions are:
561 LTTNG_UST_TRACEPOINT_LOGLEVEL_EMERG
563 System is unusable.
564 LTTNG_UST_TRACEPOINT_LOGLEVEL_ALERT
566 Action must be taken immediately.
567 LTTNG_UST_TRACEPOINT_LOGLEVEL_CRIT
569 Critical conditions.
570 LTTNG_UST_TRACEPOINT_LOGLEVEL_ERR
572 Error conditions.
573 LTTNG_UST_TRACEPOINT_LOGLEVEL_WARNING
575 Warning conditions.
576 LTTNG_UST_TRACEPOINT_LOGLEVEL_NOTICE
578 Normal, but significant, condition.
579 LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO
581 Informational message.
582 LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_SYSTEM
584 Debug information with system-level scope (set of programs).
585 LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_PROGRAM
587 Debug information with program-level scope (set of processes).
588 LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_PROCESS
590 Debug information with process-level scope (set of modules).
591 LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_MODULE
593 Debug information with module (executable/library) scope (set of
594 units).
595 LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_UNIT
597 Debug information with compilation unit scope (set of functions).
598 LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION
600 Debug information with function-level scope.
601 LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_LINE
603 Debug information with line-level scope (default log level).
604 LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG
606 Debug-level message.
607 See the EXAMPLE section below for a complete example.
609 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 #define lttng_ust_tracepoint(prov_name, t_name, ...)
616 With:
618 prov_name
620 Tracepoint provider name.
621 t_name
623 Tracepoint/event name.
624 ...
626 Tracepoint arguments, if any.
627 Make sure to include the tracepoint provider header file anywhere you
629 use lttng_ust_tracepoint() for this provider.
630 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 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 #define lttng_ust_tracepoint_enabled(prov_name, t_name)
644 #define lttng_ust_do_tracepoint(prov_name, t_name, ...)
645 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 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 if (lttng_ust_tracepoint_enabled(my_provider, my_tracepoint)) {
658 stuff = prepare_stuff();
659 }
660 lttng_ust_tracepoint(my_provider, my_tracepoint, stuff);
662 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 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 Statically linking the tracepoint provider
673 With the static linking method, compiled tracepoint providers are
674 copied into the target application.
675 Define LTTNG_UST_TRACEPOINT_DEFINE definition below the
677 LTTNG_UST_TRACEPOINT_CREATE_PROBES definition in the tracepoint
678 provider source:
679 #define LTTNG_UST_TRACEPOINT_CREATE_PROBES
681 #define LTTNG_UST_TRACEPOINT_DEFINE
682 #include "tp.h"
684 Create the tracepoint provider object file:
686 $ cc -c -I. tp.c
688 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 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 $ ar rc tp.a tp.o
700 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 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 $ cc -o app tp.o app.o -llttng-ust -ldl
714 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 In this scenario, the tracepoint provider is compiled as a shared
721 object.
722 The process to create the tracepoint provider shared object is pretty
724 much the same as the static linking method, except that:
725 • 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 • LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE must be defined next to
731 LTTNG_UST_TRACEPOINT_DEFINE
732 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 #define LTTNG_UST_TRACEPOINT_DEFINE
740 #define LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE
741 #include "tp.h"
743 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 $ cc -c -fpic -I. tp.c
749 It is then linked as a shared library like this:
751 $ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
753 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 $ cc -o app app.o tp-define.o -ldl
760 There are two ways to dynamically load the tracepoint provider shared
762 object:
763 • Load it manually from the application using dlopen(3)
765 • Make the dynamic loader load it with the LD_PRELOAD environment
767 variable (see ld.so(8))
768 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 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 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 To instrument a shared object, either:
785 • Statically link the tracepoint provider to the application, or
787 • 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 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 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 Context information
806 Context information can be prepended by the LTTng-UST tracer before
807 each event, or before specific events.
808 Context fields can be added to specific channels using lttng-add-
810 context(1).
811 The following context fields are supported by LTTng-UST:
813 General context fields
815 cpu_id
817 CPU ID.
818 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 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 pthread_id
832 POSIX thread identifier.
833 Can be used on architectures where pthread_t maps nicely to an
835 unsigned long type.
836 Process context fields
838 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 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 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 perf context fields
853 perf:thread:COUNTER
855 perf counter named COUNTER. Use lttng add-context --list to
856 list the available perf counters.
857 Only available on IA-32 and x86-64 architectures.
859 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 Namespace context fields (see namespaces(7))
865 cgroup_ns
867 Inode number of the current control group namespace (see
868 cgroup_namespaces(7)) in the proc file system.
869 ipc_ns
871 Inode number of the current IPC namespace (see
872 ipc_namespaces(7)) in the proc file system.
873 mnt_ns
875 Inode number of the current mount point namespace (see
876 mount_namespaces(7)) in the proc file system.
877 net_ns
879 Inode number of the current network namespace (see
880 network_namespaces(7)) in the proc file system.
881 pid_ns
883 Inode number of the current process ID namespace (see
884 pid_namespaces(7)) in the proc file system.
885 time_ns
887 Inode number of the current clock namespace (see
888 time_namespaces(7)) in the proc file system.
889 user_ns
891 Inode number of the current user namespace (see
892 user_namespaces(7)) in the proc file system.
893 uts_ns
895 Inode number of the current UTS namespace (see
896 uts_namespaces(7)) in the proc file system.
897 Credential context fields (see credentials(7))
899 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 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 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 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 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 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 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 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 lttng_ust_statedump:start
940 Emitted when the state dump begins.
941 This event has no fields.
943 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 This event has no fields.
949 lttng_ust_statedump:bin_info
951 Emitted when information about a currently loaded executable or
952 shared object is found.
953 Fields:
955 ┌───────────────┬────────────────────────────────┐
957 │Field name │ Description │
958 ├───────────────┼────────────────────────────────┤
959 │baddr │ Base address of loaded │
960 │ │ executable. │
961 ├───────────────┼────────────────────────────────┤
962 │memsz │ Size of loaded executable │
963 │ │ in memory. │
964 ├───────────────┼────────────────────────────────┤
965 │path │ Path to loaded executable │
966 │ │ file. │
967 ├───────────────┼────────────────────────────────┤
968 │is_pic │ Whether or not the │
969 │ │ executable is │
970 │ │ position-independent code. │
971 ├───────────────┼────────────────────────────────┤
972 │has_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 ├───────────────┼────────────────────────────────┤
981 │has_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 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 Fields:
998 ┌───────────┬────────────────────────┐
1000 │Field name │ Description │
1001 ├───────────┼────────────────────────┤
1002 │baddr │ Base address of loaded │
1003 │ │ library. │
1004 ├───────────┼────────────────────────┤
1005 │build_id │ Build ID. │
1006 └───────────┴────────────────────────┘
1007 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 Fields:
1015 ┌───────────┬────────────────────────┐
1017 │Field name │ Description │
1018 ├───────────┼────────────────────────┤
1019 │baddr │ Base address of loaded │
1020 │ │ library. │
1021 ├───────────┼────────────────────────┤
1022 │crc │ Debug link file’s CRC. │
1023 ├───────────┼────────────────────────┤
1024 │filename │ Debug link file name. │
1025 └───────────┴────────────────────────┘
1026 lttng_ust_statedump:procname
1028 The process procname at process start.
1029 Fields:
1031 ┌───────────┬───────────────────┐
1033 │Field name │ Description │
1034 ├───────────┼───────────────────┤
1035 │procname │ The process name. │
1036 └───────────┴───────────────────┘
1037 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 The following shared library load/unload tracking events exist and must
1044 be enabled to track the loading and unloading of shared libraries:
1045 lttng_ust_lib:load
1047 Emitted when a shared library (shared object) is loaded.
1048 Fields:
1050 ┌───────────────┬────────────────────────────┐
1052 │Field name │ Description │
1053 ├───────────────┼────────────────────────────┤
1054 │baddr │ Base address of loaded │
1055 │ │ library. │
1056 ├───────────────┼────────────────────────────┤
1057 │memsz │ Size of loaded library in │
1058 │ │ memory. │
1059 ├───────────────┼────────────────────────────┤
1060 │path │ Path to loaded library │
1061 │ │ file. │
1062 ├───────────────┼────────────────────────────┤
1063 │has_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 ├───────────────┼────────────────────────────┤
1072 │has_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 lttng_ust_lib:unload
1084 Emitted when a shared library (shared object) is unloaded.
1085 Fields:
1087 ┌───────────┬──────────────────────────┐
1089 │Field name │ Description │
1090 ├───────────┼──────────────────────────┤
1091 │baddr │ Base address of unloaded │
1092 │ │ library. │
1093 └───────────┴──────────────────────────┘
1094 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 Fields:
1102 ┌───────────┬────────────────────────┐
1104 │Field name │ Description │
1105 ├───────────┼────────────────────────┤
1106 │baddr │ Base address of loaded │
1107 │ │ library. │
1108 ├───────────┼────────────────────────┤
1109 │build_id │ Build ID. │
1110 └───────────┴────────────────────────┘
1111 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 Fields:
1119 ┌───────────┬────────────────────────┐
1121 │Field name │ Description │
1122 ├───────────┼────────────────────────┤
1123 │baddr │ Base address of loaded │
1124 │ │ library. │
1125 ├───────────┼────────────────────────┤
1126 │crc │ Debug link file’s CRC. │
1127 ├───────────┼────────────────────────┤
1128 │filename │ Debug link file name. │
1129 └───────────┴────────────────────────┘
1130 Detect if LTTng-UST is loaded
1132 To detect if liblttng-ust is loaded from an application:
1133 1. Define the lttng_ust_loaded weak symbol globally:
1135 int lttng_ust_loaded __attribute__((weak));
1137 This weak symbol is set by the constructor of liblttng-ust.
1139 2. Test lttng_ust_loaded where needed:
1141 /* ... */
1143 if (lttng_ust_loaded) {
1145 /* LTTng-UST is loaded */
1146 } else {
1147 /* LTTng-UST is NOT loaded */
1148 }
1149 /* ... */
1151
1153 Note
1154 A few examples are available in the directory of LTTng-UST’s source
1155 tree.
1156 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 You can compile the source files and link them together statically like
1162 this:
1163 $ cc -c -I. tp.c
1165 $ cc -c app.c
1166 $ cc -o app tp.o app.o -llttng-ust -ldl
1167 Using the lttng(1) tool, create an LTTng tracing session, enable all
1169 the events of this tracepoint provider, and start tracing:
1170 $ lttng create my-session
1172 $ lttng enable-event --userspace 'my_provider:*'
1173 $ lttng start
1174 You may also enable specific events:
1176 $ lttng enable-event --userspace my_provider:big_event
1178 $ lttng enable-event --userspace my_provider:event_instance2
1179 Run the application:
1181 $ ./app some arguments
1183 Stop the current tracing session and inspect the recorded events:
1185 $ lttng stop
1187 $ lttng view
1188 Tracepoint provider header file
1190 tp.h:
1191 #undef LTTNG_UST_TRACEPOINT_PROVIDER
1193 #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
1194 #undef LTTNG_USTTRACEPOINT_INCLUDE
1196 #define LTTNG_USTTRACEPOINT_INCLUDE "./tp.h"
1197 #if !defined(_TP_H) || \
1199 defined(LTTNG_UST_TRACEPOINT_HEADER_MULTI_READ)
1200 #define _TP_H
1201 #include <lttng/tracepoint.h>
1203 #include <stdio.h>
1204 #include "app.h"
1206 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 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 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 LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, big_event,
1262 LTTNG_UST_TRACEPOINT_LOGLEVEL_WARNING)
1263 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 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 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 LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, event_instance2,
1301 LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO)
1302 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 #endif /* _TP_H */
1315 #include <lttng/tracepoint-event.h>
1317 Tracepoint provider source file
1319 tp.c:
1320 #define LTTNG_UST_TRACEPOINT_CREATE_PROBES
1322 #define LTTNG_UST_TRACEPOINT_DEFINE
1323 #include "tp.h"
1325 Application header file
1327 app.h:
1328 #ifndef _APP_H
1330 #define _APP_H
1331 struct app_struct {
1333 unsigned long b;
1334 const char *c;
1335 double d;
1336 };
1337 #endif /* _APP_H */
1339 Application source file
1341 app.c:
1342 #include <stdlib.h>
1344 #include <stdio.h>
1345 #include "tp.h"
1347 #include "app.h"
1348 static int array_of_ints[] = {
1350 100, -35, 1, 23, 14, -6, 28, 1001, -3000,
1351 };
1352 int main(int argc, char* argv[])
1354 {
1355 FILE *stream;
1356 struct app_struct app_struct;
1357 lttng_ust_tracepoint(my_provider, simple_event, argc, argv[0]);
1359 stream = fopen("/tmp/app.txt", "w");
1360 if (!stream) {
1362 fprintf(stderr,
1363 "Error: Cannot open /tmp/app.txt for writing\n");
1364 return EXIT_FAILURE;
1365 }
1366 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 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
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 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 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 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 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 Warning
1418 Setting this environment variable may significantly affect
1419 application timings.
1420 LTTNG_UST_ABORT_ON_CRITICAL
1422 If set, abort the instrumented application on a critical error
1423 message.
1424 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 LTTNG_UST_DEBUG
1431 If set, enable liblttng-ust's debug and error output.
1432 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 LTTNG_UST_REGISTER_TIMEOUT
1439 Waiting time for the registration done session daemon command
1440 before proceeding to execute the main program (milliseconds).
1441 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 Default: 3000.
1447 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 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
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
1461 • LTTng project website <http://lttng.org>
1462 • LTTng documentation <http://lttng.org/docs>
1464 • Git repositories <http://git.lttng.org>
1466 • GitHub organization <http://github.com/lttng>
1468 • Continuous integration <http://ci.lttng.org/>
1470 • Mailing list <http://lists.lttng.org> for support and development:
1472 lttng-dev@lists.lttng.org
1473 • IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
1475
1477 This library is part of the LTTng-UST project.
1478 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
1484 Thanks to Ericsson for funding this work, providing real-life use
1485 cases, and testing.
1486 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
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
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)
1500LTTng 2.13.1 12/10/2021 LTTNG-UST(3)