1LTTNG-UST(3) LTTng Manual LTTNG-UST(3)
2
3
4
6 lttng-ust - LTTng user space tracing
7
9 #include <lttng/tracepoint.h>
10
11 #define TRACEPOINT_ENUM(prov_name, enum_name, mappings)
12 #define TRACEPOINT_EVENT(prov_name, t_name, args, fields)
13 #define TRACEPOINT_EVENT_CLASS(prov_name, class_name, args, fields)
14 #define TRACEPOINT_EVENT_INSTANCE(prov_name, class_name, t_name, args)
15 #define TRACEPOINT_LOGLEVEL(prov_name, t_name, level)
16 #define ctf_array(int_type, field_name, expr, count)
17 #define ctf_array_nowrite(int_type, field_name, expr, count)
18 #define ctf_array_hex(int_type, field_name, expr, count)
19 #define ctf_array_nowrite_hex(int_type, field_name, expr, count)
20 #define ctf_array_network(int_type, field_name, expr, count)
21 #define ctf_array_network_nowrite(int_type, field_name, expr, count)
22 #define ctf_array_network_hex(int_type, field_name, expr, count)
23 #define ctf_array_network_nowrite_hex(int_type, field_name, expr, count)
24 #define ctf_array_text(char, field_name, expr, count)
25 #define ctf_array_text_nowrite(char, field_name, expr, count)
26 #define ctf_enum(prov_name, enum_name, int_type, field_name, expr)
27 #define ctf_enum_nowrite(prov_name, enum_name, int_type, field_name,
28 expr)
29 #define ctf_enum_value(label, value)
30 #define ctf_enum_range(label, start, end)
31 #define ctf_float(float_type, field_name, expr)
32 #define ctf_float_nowrite(float_type, field_name, expr)
33 #define ctf_integer(int_type, field_name, expr)
34 #define ctf_integer_hex(int_type, field_name, expr)
35 #define ctf_integer_network(int_type, field_name, expr)
36 #define ctf_integer_network_hex(int_type, field_name, expr)
37 #define ctf_integer_nowrite(int_type, field_name, expr)
38 #define ctf_sequence(int_type, field_name, expr, len_type, len_expr)
39 #define ctf_sequence_nowrite(int_type, field_name, expr, len_type,
40 len_expr)
41 #define ctf_sequence_hex(int_type, field_name, expr, len_type,
42 len_expr)
43 #define ctf_sequence_nowrite_hex(int_type, field_name, expr, len_type,
44 len_expr)
45 #define ctf_sequence_network(int_type, field_name, expr, len_type,
46 len_expr)
47 #define ctf_sequence_network_nowrite(int_type, field_name, expr,
48 len_type, len_expr)
49 #define ctf_sequence_network_hex(int_type, field_name, expr, len_type,
50 len_expr)
51 #define ctf_sequence_network_nowrite_hex(int_type, field_name, expr,
52 len_type, len_expr)
53 #define ctf_sequence_text(char, field_name, expr, len_type, len_expr)
54 #define ctf_sequence_text_nowrite(char, field_name, expr, len_type,
55 len_expr)
56 #define ctf_string(field_name, expr)
57 #define ctf_string_nowrite(field_name, expr)
58 #define do_tracepoint(prov_name, t_name, ...)
59 #define tracepoint(prov_name, t_name, ...)
60 #define tracepoint_enabled(prov_name, t_name)
61
62 Link with -llttng-ust -ldl, following this man page.
63
65 The Linux Trace Toolkit: next generation <http://lttng.org/> is an open
66 source software package used for correlated tracing of the Linux
67 kernel, user applications, and user libraries.
68
69 LTTng-UST is the user space tracing component of the LTTng project. It
70 is a port to user space of the low-overhead tracing capabilities of the
71 LTTng Linux kernel tracer. The liblttng-ust library is used to trace
72 user applications and libraries.
73
74 Note
75 This man page is about the liblttng-ust library. The LTTng-UST
76 project also provides Java and Python packages to trace
77 applications written in those languages. How to instrument and
78 trace Java and Python applications is documented in the online
79 LTTng documentation <http://lttng.org/docs/>.
80
81 There are three ways to use liblttng-ust:
82
83 · Using the tracef(3) API, which is similar to printf(3).
84
85 · Using the tracelog(3) API, which is tracef(3) with a log level
86 parameter.
87
88 · Defining your own tracepoints. See the Creating a tracepoint
89 provider section below.
90
91 Creating a tracepoint provider
92 Creating a tracepoint provider is the first step of using liblttng-ust.
93 The next steps are:
94
95 · Instrumenting your application with tracepoint() calls
96
97 · Building your application with LTTng-UST support, either statically
98 or dynamically.
99
100 A tracepoint provider is a compiled object containing the event probes
101 corresponding to your custom tracepoint definitions. A tracepoint
102 provider contains the code to get the size of an event and to serialize
103 it, amongst other things.
104
105 To create a tracepoint provider, start with the following tracepoint
106 provider header template:
107
108 #undef TRACEPOINT_PROVIDER
109 #define TRACEPOINT_PROVIDER my_provider
110
111 #undef TRACEPOINT_INCLUDE
112 #define TRACEPOINT_INCLUDE "./tp.h"
113
114 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
115 #define _TP_H
116
117 #include <lttng/tracepoint.h>
118
119 /*
120 * TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
121 * TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(),
122 * and `TRACEPOINT_ENUM()` are used here.
123 */
124
125 #endif /* _TP_H */
126
127 #include <lttng/tracepoint-event.h>
128
129 In this template, the tracepoint provider is named my_provider
130 (TRACEPOINT_PROVIDER definition). The file needs to bear the name of
131 the TRACEPOINT_INCLUDE definition (tp.h in this case). Between #include
132 <lttng/tracepoint.h> and #endif go the invocations of the
133 TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
134 TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(), and
135 TRACEPOINT_ENUM() macros.
136
137 Note
138 You can avoid writing the prologue and epilogue boilerplate in the
139 template file above by using the lttng-gen-tp(1) tool shipped with
140 LTTng-UST.
141
142 The tracepoint provider header file needs to be included in a source
143 file which looks like this:
144
145 #define TRACEPOINT_CREATE_PROBES
146
147 #include "tp.h"
148
149 Together, those two files (let’s call them tp.h and tp.c) form the
150 tracepoint provider sources, ready to be compiled.
151
152 You can create multiple tracepoint providers to be used in a single
153 application, but each one must have its own header file.
154
155 The TRACEPOINT_EVENT() usage section below shows how to use the
156 TRACEPOINT_EVENT() macro to define the actual tracepoints in the
157 tracepoint provider header file.
158
159 See the EXAMPLE section below for a complete example.
160
161 TRACEPOINT_EVENT() usage
162 The TRACEPOINT_EVENT() macro is used in a template provider header file
163 (see the Creating a tracepoint provider section above) to define
164 LTTng-UST tracepoints.
165
166 The TRACEPOINT_EVENT() usage template is as follows:
167
168 TRACEPOINT_EVENT(
169 /* Tracepoint provider name */
170 my_provider,
171
172 /* Tracepoint/event name */
173 my_tracepoint,
174
175 /* List of tracepoint arguments (input) */
176 TP_ARGS(
177 ...
178 ),
179
180 /* List of fields of eventual event (output) */
181 TP_FIELDS(
182 ...
183 )
184 )
185
186 The TP_ARGS() macro contains the input arguments of the tracepoint.
187 Those arguments can be used in the argument expressions of the output
188 fields defined in TP_FIELDS().
189
190 The format of the TP_ARGS() parameters is: C type, then argument name;
191 repeat as needed, up to ten times. For example:
192
193 TP_ARGS(
194 int, my_int,
195 const char *, my_string,
196 FILE *, my_file,
197 double, my_float,
198 struct my_data *, my_data
199 )
200
201 The TP_FIELDS() macro contains the output fields of the tracepoint,
202 that is, the actual data that can be recorded in the payload of an
203 event emitted by this tracepoint.
204
205 The TP_FIELDS() macro contains a list of ctf_*() macros NOT separated
206 by commas. The available macros are documented in the Available ctf_*()
207 field type macros section below.
208
209 Available ctf_*() field type macros
210 This section documents the available ctf_*() macros that can be
211 inserted in the TP_FIELDS() macro of the TRACEPOINT_EVENT() macro.
212
213 Standard integer, displayed in base 10:
214
215 ctf_integer(int_type, field_name, expr)
216 ctf_integer_nowrite(int_type, field_name, expr)
217
218 Standard integer, displayed in base 16:
219
220 ctf_integer_hex(int_type, field_name, expr)
221
222 Integer in network byte order (big endian), displayed in base 10:
223
224 ctf_integer_network(int_type, field_name, expr)
225
226 Integer in network byte order, displayed in base 16:
227
228 ctf_integer_network_hex(int_type, field_name, expr)
229
230 Floating point number:
231
232 ctf_float(float_type, field_name, expr)
233 ctf_float_nowrite(float_type, field_name, expr)
234
235 Null-terminated string:
236
237 ctf_string(field_name, expr)
238 ctf_string_nowrite(field_name, expr)
239
240 Statically-sized array of integers (_hex versions displayed in
241 hexadecimal, _network versions in network byte order):
242
243 ctf_array(int_type, field_name, expr, count)
244 ctf_array_nowrite(int_type, field_name, expr, count)
245 ctf_array_hex(int_type, field_name, expr, count)
246 ctf_array_nowrite_hex(int_type, field_name, expr, count)
247 ctf_array_network(int_type, field_name, expr, count)
248 ctf_array_network_nowrite(int_type, field_name, expr, count)
249 ctf_array_network_hex(int_type, field_name, expr, count)
250 ctf_array_network_nowrite_hex(int_type, field_name, expr, count)
251
252 Statically-sized array, printed as text; no need to be null-terminated:
253
254 ctf_array_text(char, field_name, expr, count)
255 ctf_array_text_nowrite(char, field_name, expr, count)
256
257 Dynamically-sized array of integers (_hex versions displayed in
258 hexadecimal, _network versions in network byte order):
259
260 ctf_sequence(int_type, field_name, expr, len_type, len_expr)
261 ctf_sequence_nowrite(int_type, field_name, expr, len_type, len_expr)
262 ctf_sequence_hex(int_type, field_name, expr, len_type, len_expr)
263 ctf_sequence_nowrite_hex(int_type, field_name, expr, len_type,
264 len_expr)
265 ctf_sequence_network(int_type, field_name, expr, len_type, len_expr)
266 ctf_sequence_network_nowrite(int_type, field_name, expr, len_type,
267 len_expr)
268 ctf_sequence_network_hex(int_type, field_name, expr, len_type,
269 len_expr)
270 ctf_sequence_network_nowrite_hex(int_type, field_name, expr,
271 len_type, len_expr)
272
273 Dynamically-sized array, displayed as text; no need to be
274 null-terminated:
275
276 ctf_sequence_text(char, field_name, expr, len_type, len_expr)
277 ctf_sequence_text_nowrite(char, field_name, expr, len_type, len_expr)
278
279 Enumeration. The enumeration field must be defined before using this
280 macro with the TRACEPOINT_ENUM() macro. See the TRACEPOINT_ENUM() usage
281 section for more information.
282
283 ctf_enum(prov_name, enum_name, int_type, field_name, expr)
284 ctf_enum_nowrite(prov_name, enum_name, int_type, field_name, expr)
285
286 The parameters are:
287
288 count
289 Number of elements in array/sequence. This must be known at compile
290 time.
291
292 enum_name
293 Name of an enumeration field previously defined with the
294 TRACEPOINT_ENUM() macro. See the TRACEPOINT_ENUM() usage section
295 for more information.
296
297 expr
298 C expression resulting in the field’s value. This expression can
299 use one or more arguments passed to the tracepoint. The arguments
300 of a given tracepoint are defined in the TP_ARGS() macro (see the
301 Creating a tracepoint provider section above).
302
303 field_name
304 Event field name (C identifier syntax, NOT a literal string).
305
306 float_type
307 Float C type (float or double). The size of this type determines
308 the size of the floating point number field.
309
310 int_type
311 Integer C type. The size of this type determines the size of the
312 integer/enumeration field.
313
314 len_expr
315 C expression resulting in the sequence’s length. This expression
316 can use one or more arguments passed to the tracepoint.
317
318 len_type
319 Unsigned integer C type of sequence’s length.
320
321 prov_name
322 Tracepoint provider name. This must be the same as the tracepoint
323 provider name used in a previous field definition.
324
325 The _nowrite versions omit themselves from the recorded trace, but are
326 otherwise identical. Their primary purpose is to make some of the event
327 context available to the event filters without having to commit the
328 data to sub-buffers. See lttng-enable-event(1) to learn more about
329 dynamic event filtering.
330
331 See the EXAMPLE section below for a complete example.
332
333 TRACEPOINT_ENUM() usage
334 An enumeration field is a list of mappings between an integers, or a
335 range of integers, and strings (sometimes called labels or
336 enumerators). Enumeration fields can be used to have a more compact
337 trace when the possible values for a field are limited.
338
339 An enumeration field is defined with the TRACEPOINT_ENUM() macro:
340
341 TRACEPOINT_ENUM(
342 /* Tracepoint provider name */
343 my_provider,
344
345 /* Enumeration name (unique in the whole tracepoint provider) */
346 my_enum,
347
348 /* Enumeration mappings */
349 TP_ENUM_VALUES(
350 ...
351 )
352 )
353
354 TP_ENUM_VALUES() contains a list of enumeration mappings, NOT separated
355 by commas. Two macros can be used in the TP_ENUM_VALUES():
356 ctf_enum_value() and ctf_enum_range().
357
358 ctf_enum_value() is a single value mapping:
359
360 ctf_enum_value(label, value)
361
362 This macro maps the given label string to the value value.
363
364 ctf_enum_range() is a range mapping:
365
366 ctf_enum_range(label, start, end)
367
368 This macro maps the given label string to the range of integers from
369 start to end, inclusively. Range mappings may overlap, but the
370 behaviour is implementation-defined: each trace reader handles
371 overlapping ranges as it wishes.
372
373 See the EXAMPLE section below for a complete example.
374
375 TRACEPOINT_EVENT_CLASS() usage
376 A tracepoint class is a class of tracepoints sharing the same field
377 types and names. A tracepoint instance is one instance of such a
378 declared tracepoint class, with its own event name.
379
380 LTTng-UST creates one event serialization function per tracepoint
381 class. Using TRACEPOINT_EVENT() creates one tracepoint class per
382 tracepoint definition, whereas using TRACEPOINT_EVENT_CLASS() and
383 TRACEPOINT_EVENT_INSTANCE() creates one tracepoint class, and one or
384 more tracepoint instances of this class. In other words, many
385 tracepoints can reuse the same serialization code. Reusing the same
386 code, when possible, can reduce cache pollution, thus improve
387 performance.
388
389 The TRACEPOINT_EVENT_CLASS() macro accepts the same parameters as the
390 TRACEPOINT_EVENT() macro, except that instead of an event name, its
391 second parameter is the tracepoint class name:
392
393 TRACEPOINT_EVENT_CLASS(
394 /* Tracepoint provider name */
395 my_provider,
396
397 /* Tracepoint class name */
398 my_tracepoint_class,
399
400 /* List of tracepoint arguments (input) */
401 TP_ARGS(
402 ...
403 ),
404
405 /* List of fields of eventual event (output) */
406 TP_FIELDS(
407 ...
408 )
409 )
410
411 Once the tracepoint class is defined, you can create as many tracepoint
412 instances as needed:
413
414 TRACEPOINT_EVENT_INSTANCE(
415 /* Tracepoint provider name */
416 my_provider,
417
418 /* Tracepoint class name */
419 my_tracepoint_class,
420
421 /* Tracepoint/event name */
422 my_tracepoint,
423
424 /* List of tracepoint arguments (input) */
425 TP_ARGS(
426 ...
427 )
428 )
429
430 As you can see, the TRACEPOINT_EVENT_INSTANCE() does not contain the
431 TP_FIELDS() macro, because they are defined at the
432 TRACEPOINT_EVENT_CLASS() level.
433
434 See the EXAMPLE section below for a complete example.
435
436 TRACEPOINT_LOGLEVEL() usage
437 Optionally, a log level can be assigned to a defined tracepoint.
438 Assigning different levels of severity to tracepoints can be useful:
439 when controlling tracing sessions, you can choose to only enable events
440 falling into a specific log level range using the --loglevel and
441 --loglevel-only options of the lttng-enable-event(1) command.
442
443 Log levels are assigned to tracepoints that are already defined using
444 the TRACEPOINT_LOGLEVEL() macro. The latter must be used after having
445 used TRACEPOINT_EVENT() or TRACEPOINT_EVENT_INSTANCE() for a given
446 tracepoint. The TRACEPOINT_LOGLEVEL() macro is used as follows:
447
448 TRACEPOINT_LOGLEVEL(
449 /* Tracepoint provider name */
450 my_provider,
451
452 /* Tracepoint/event name */
453 my_tracepoint,
454
455 /* Log level */
456 TRACE_INFO
457 )
458
459 The available log level definitions are:
460
461 TRACE_EMERG
462 System is unusable.
463
464 TRACE_ALERT
465 Action must be taken immediately.
466
467 TRACE_CRIT
468 Critical conditions.
469
470 TRACE_ERR
471 Error conditions.
472
473 TRACE_WARNING
474 Warning conditions.
475
476 TRACE_NOTICE
477 Normal, but significant, condition.
478
479 TRACE_INFO
480 Informational message.
481
482 TRACE_DEBUG_SYSTEM
483 Debug information with system-level scope (set of programs).
484
485 TRACE_DEBUG_PROGRAM
486 Debug information with program-level scope (set of processes).
487
488 TRACE_DEBUG_PROCESS
489 Debug information with process-level scope (set of modules).
490
491 TRACE_DEBUG_MODULE
492 Debug information with module (executable/library) scope (set of
493 units).
494
495 TRACE_DEBUG_UNIT
496 Debug information with compilation unit scope (set of functions).
497
498 TRACE_DEBUG_FUNCTION
499 Debug information with function-level scope.
500
501 TRACE_DEBUG_LINE
502 Debug information with line-level scope (default log level).
503
504 TRACE_DEBUG
505 Debug-level message.
506
507 See the EXAMPLE section below for a complete example.
508
509 Instrumenting your application
510 Once the tracepoint provider is created (see the Creating a tracepoint
511 provider section above), you can instrument your application with the
512 defined tracepoints thanks to the tracepoint() macro:
513
514 #define tracepoint(prov_name, t_name, ...)
515
516 With:
517
518 prov_name
519 Tracepoint provider name.
520
521 t_name
522 Tracepoint/event name.
523
524 ...
525 Tracepoint arguments, if any.
526
527 Make sure to include the tracepoint provider header file anywhere you
528 use tracepoint() for this provider.
529
530 Note
531 Even though LTTng-UST supports tracepoint() call site duplicates
532 having the same provider and tracepoint names, it is recommended to
533 use a provider/tracepoint name pair only once within the
534 application source code to help map events back to their call sites
535 when analyzing the trace.
536
537 Sometimes, arguments to the tracepoint are expensive to compute (take
538 call stack, for example). To avoid the computation when the tracepoint
539 is disabled, you can use the tracepoint_enabled() and do_tracepoint()
540 macros:
541
542 #define tracepoint_enabled(prov_name, t_name)
543 #define do_tracepoint(prov_name, t_name, ...)
544
545 tracepoint_enabled() returns a non-zero value if the tracepoint named
546 t_name from the provider named prov_name is enabled at run time.
547
548 do_tracepoint() is like tracepoint(), except that it doesn’t check if
549 the tracepoint is enabled. Using tracepoint() with tracepoint_enabled()
550 is dangerous since tracepoint() also contains the tracepoint_enabled()
551 check, thus a race condition is possible in this situation:
552
553 if (tracepoint_enabled(my_provider, my_tracepoint)) {
554 stuff = prepare_stuff();
555 }
556
557 tracepoint(my_provider, my_tracepoint, stuff);
558
559 If the tracepoint is enabled after the condition, then stuff is not
560 prepared: the emitted event will either contain wrong data, or the
561 whole application could crash (segmentation fault, for example).
562
563 Note
564 Neither tracepoint_enabled() nor do_tracepoint() have a
565 STAP_PROBEV() call, so if you need it, you should emit this call
566 yourself.
567
568 Statically linking the tracepoint provider
569 With the static linking method, compiled tracepoint providers are
570 copied into the target application.
571
572 Define TRACEPOINT_DEFINE definition below the TRACEPOINT_CREATE_PROBES
573 definition in the tracepoint provider source:
574
575 #define TRACEPOINT_CREATE_PROBES
576 #define TRACEPOINT_DEFINE
577
578 #include "tp.h"
579
580 Create the tracepoint provider object file:
581
582 $ cc -c -I. tp.c
583
584
585 Note
586 Although an application instrumented with LTTng-UST tracepoints can
587 be compiled with a C++ compiler, tracepoint probes should be
588 compiled with a C compiler.
589
590 At this point, you can archive this tracepoint provider object file,
591 possibly with other object files of your application or with other
592 tracepoint provider object files, as a static library:
593
594 $ ar rc tp.a tp.o
595
596 Using a static library does have the advantage of centralising the
597 tracepoint providers objects so they can be shared between multiple
598 applications. This way, when the tracepoint provider is modified, the
599 source code changes don’t have to be patched into each application’s
600 source code tree. The applications need to be relinked after each
601 change, but need not to be otherwise recompiled (unless the tracepoint
602 provider’s API changes).
603
604 Then, link your application with this object file (or with the static
605 library containing it) and with liblttng-ust and libdl (libc on a BSD
606 system):
607
608 $ cc -o app tp.o app.o -llttng-ust -ldl
609
610 Dynamically loading the tracepoint provider
611 The second approach to package the tracepoint provider is to use the
612 dynamic loader: the library and its member functions are explicitly
613 sought, loaded at run time.
614
615 In this scenario, the tracepoint provider is compiled as a shared
616 object.
617
618 The process to create the tracepoint provider shared object is pretty
619 much the same as the static linking method, except that:
620
621 · Since the tracepoint provider is not part of the application,
622 TRACEPOINT_DEFINE must be defined, for each tracepoint provider, in
623 exactly one source file of the application
624
625 · TRACEPOINT_PROBE_DYNAMIC_LINKAGE must be defined next to
626 TRACEPOINT_DEFINE
627
628 Regarding TRACEPOINT_DEFINE and TRACEPOINT_PROBE_DYNAMIC_LINKAGE, the
629 recommended practice is to use a separate C source file in your
630 application to define them, then include the tracepoint provider header
631 files afterwards. For example, as tp-define.c:
632
633 #define TRACEPOINT_DEFINE
634 #define TRACEPOINT_PROBE_DYNAMIC_LINKAGE
635
636 #include "tp.h"
637
638 The tracepoint provider object file used to create the shared library
639 is built like it is using the static linking method, but with the -fpic
640 option:
641
642 $ cc -c -fpic -I. tp.c
643
644 It is then linked as a shared library like this:
645
646 $ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
647
648 This tracepoint provider shared object isn’t linked with the user
649 application: it must be loaded manually. This is why the application is
650 built with no mention of this tracepoint provider, but still needs
651 libdl:
652
653 $ cc -o app app.o tp-define.o -ldl
654
655 There are two ways to dynamically load the tracepoint provider shared
656 object:
657
658 · Load it manually from the application using dlopen(3)
659
660 · Make the dynamic loader load it with the LD_PRELOAD environment
661 variable (see ld.so(8))
662
663 If the application does not dynamically load the tracepoint provider
664 shared object using one of the methods above, tracing is disabled for
665 this application, and the events are not listed in the output of lttng-
666 list(1).
667
668 Note that it is not safe to use dlclose(3) on a tracepoint provider
669 shared object that is being actively used for tracing, due to a lack of
670 reference counting from LTTng-UST to the shared object.
671
672 For example, statically linking a tracepoint provider to a shared
673 object which is to be dynamically loaded by an application (a plugin,
674 for example) is not safe: the shared object, which contains the
675 tracepoint provider, could be dynamically closed (dlclose(3)) at any
676 time by the application.
677
678 To instrument a shared object, either:
679
680 · Statically link the tracepoint provider to the application, or
681
682 · Build the tracepoint provider as a shared object (following the
683 procedure shown in this section), and preload it when tracing is
684 needed using the LD_PRELOAD environment variable.
685
686 Using LTTng-UST with daemons
687 Some extra care is needed when using liblttng-ust with daemon
688 applications that call fork(2), clone(2), or BSD’s rfork(2) without a
689 following exec(3) family system call. The library liblttng-ust-fork.so
690 needs to be preloaded before starting the application with the
691 LD_PRELOAD environment variable (see ld.so(8)).
692
693 To use liblttng-ust with a daemon application which closes file
694 descriptors that were not opened by it, preload the liblttng-ust-fd.so
695 library before you start the application. Typical use cases include
696 daemons closing all file descriptors after fork(2), and buggy
697 applications doing “double-closes”.
698
699 Context information
700 Context information can be prepended by the LTTng-UST tracer before
701 each event, or before specific events.
702
703 Context fields can be added to specific channels using lttng-add-
704 context(1).
705
706 The following context fields are supported by LTTng-UST:
707
708 cpu_id
709 CPU ID.
710
711 Note
712 This context field is always enabled, and it cannot be added
713 with lttng-add-context(1). Its main purpose is to be used for
714 dynamic event filtering. See lttng-enable-event(1) for more
715 information about event filtering.
716
717 ip
718 Instruction pointer: enables recording the exact address from which
719 an event was emitted. This context field can be used to
720 reverse-lookup the source location that caused the event to be
721 emitted.
722
723 perf:thread:COUNTER
724 perf counter named COUNTER. Use lttng add-context --list to list
725 the available perf counters.
726
727 Only available on IA-32 and x86-64 architectures.
728
729 perf:thread:raw:rN:NAME
730 perf counter with raw ID N and custom name NAME. See lttng-add-
731 context(1) for more details.
732
733 pthread_id
734 POSIX thread identifier. Can be used on architectures where
735 pthread_t maps nicely to an unsigned long type.
736
737 procname
738 Thread name, as set by exec(3) or prctl(2). It is recommended that
739 programs set their thread name with prctl(2) before hitting the
740 first tracepoint for that thread.
741
742 vpid
743 Virtual process ID: process ID as seen from the point of view of
744 the process namespace.
745
746 vtid
747 Virtual thread ID: thread ID as seen from the point of view of the
748 process namespace.
749
750 LTTng-UST state dump
751 If an application that uses liblttng-ust becomes part of a tracing
752 session, information about its currently loaded shared objects, their
753 build IDs, and their debug link information are emitted as events by
754 the tracer.
755
756 The following LTTng-UST state dump events exist and must be enabled to
757 record application state dumps. Note that, during the state dump phase,
758 LTTng-UST can also emit shared library load/unload events (see Shared
759 library load/unload tracking below).
760
761 lttng_ust_statedump:start
762 Emitted when the state dump begins.
763
764 This event has no fields.
765
766 lttng_ust_statedump:end
767 Emitted when the state dump ends. Once this event is emitted, it is
768 guaranteed that, for a given process, the state dump is complete.
769
770 This event has no fields.
771
772 lttng_ust_statedump:bin_info
773 Emitted when information about a currently loaded executable or
774 shared object is found.
775
776 Fields:
777
778 ┌───────────────┬────────────────────────────────┐
779 │Field name │ Description │
780 ├───────────────┼────────────────────────────────┤
781 │baddr │ Base address of loaded │
782 │ │ executable. │
783 ├───────────────┼────────────────────────────────┤
784 │memsz │ Size of loaded executable │
785 │ │ in memory. │
786 ├───────────────┼────────────────────────────────┤
787 │path │ Path to loaded executable │
788 │ │ file. │
789 ├───────────────┼────────────────────────────────┤
790 │is_pic │ Whether or not the │
791 │ │ executable is │
792 │ │ position-independent code. │
793 ├───────────────┼────────────────────────────────┤
794 │has_build_id │ Whether or not the │
795 │ │ executable has a build ID. │
796 │ │ If this field is 1, you │
797 │ │ can expect that an │
798 │ │ lttng_ust_statedump:build_id │
799 │ │ event record follows this │
800 │ │ one (not necessarily │
801 │ │ immediately after). │
802 ├───────────────┼────────────────────────────────┤
803 │has_debug_link │ Whether or not the │
804 │ │ executable has debug link │
805 │ │ information. If this field │
806 │ │ is 1, you can expect that an │
807 │ │ lttng_ust_statedump:debug_link │
808 │ │ event record follows this │
809 │ │ one (not necessarily │
810 │ │ immediately after). │
811 └───────────────┴────────────────────────────────┘
812
813 lttng_ust_statedump:build_id
814 Emitted when a build ID is found in a currently loaded shared
815 library. See Debugging Information in Separate Files
816 <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
817 Files.html> for more information about build IDs.
818
819 Fields:
820
821 ┌───────────┬────────────────────────┐
822 │Field name │ Description │
823 ├───────────┼────────────────────────┤
824 │baddr │ Base address of loaded │
825 │ │ library. │
826 ├───────────┼────────────────────────┤
827 │build_id │ Build ID. │
828 └───────────┴────────────────────────┘
829
830 lttng_ust_statedump:debug_link
831 Emitted when debug link information is found in a currently loaded
832 shared library. See Debugging Information in Separate Files
833 <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
834 Files.html> for more information about debug links.
835
836 Fields:
837
838 ┌───────────┬────────────────────────┐
839 │Field name │ Description │
840 ├───────────┼────────────────────────┤
841 │baddr │ Base address of loaded │
842 │ │ library. │
843 ├───────────┼────────────────────────┤
844 │crc │ Debug link file’s CRC. │
845 ├───────────┼────────────────────────┤
846 │filename │ Debug link file name. │
847 └───────────┴────────────────────────┘
848
849 Shared library load/unload tracking
850 The LTTng-UST state dump and the LTTng-UST helper library to instrument
851 the dynamic linker (see liblttng-ust-dl(3)) can emit shared library
852 load/unload tracking events.
853
854 The following shared library load/unload tracking events exist and must
855 be enabled to track the loading and unloading of shared libraries:
856
857 lttng_ust_lib:load
858 Emitted when a shared library (shared object) is loaded.
859
860 Fields:
861
862 ┌───────────────┬────────────────────────────┐
863 │Field name │ Description │
864 ├───────────────┼────────────────────────────┤
865 │baddr │ Base address of loaded │
866 │ │ library. │
867 ├───────────────┼────────────────────────────┤
868 │memsz │ Size of loaded library in │
869 │ │ memory. │
870 ├───────────────┼────────────────────────────┤
871 │path │ Path to loaded library │
872 │ │ file. │
873 ├───────────────┼────────────────────────────┤
874 │has_build_id │ Whether or not the library │
875 │ │ has a build ID. If this │
876 │ │ field is 1, you can expect │
877 │ │ that an │
878 │ │ lttng_ust_lib:build_id │
879 │ │ event record follows this │
880 │ │ one (not necessarily │
881 │ │ immediately after). │
882 ├───────────────┼────────────────────────────┤
883 │has_debug_link │ Whether or not the library │
884 │ │ has debug link │
885 │ │ information. If this field │
886 │ │ is 1, you can expect that │
887 │ │ an │
888 │ │ lttng_ust_lib:debug_link │
889 │ │ event record follows this │
890 │ │ one (not necessarily │
891 │ │ immediately after). │
892 └───────────────┴────────────────────────────┘
893
894 lttng_ust_lib:unload
895 Emitted when a shared library (shared object) is unloaded.
896
897 Fields:
898
899 ┌───────────┬──────────────────────────┐
900 │Field name │ Description │
901 ├───────────┼──────────────────────────┤
902 │baddr │ Base address of unloaded │
903 │ │ library. │
904 └───────────┴──────────────────────────┘
905
906 lttng_ust_lib:build_id
907 Emitted when a build ID is found in a loaded shared library (shared
908 object). See Debugging Information in Separate Files
909 <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
910 Files.html> for more information about build IDs.
911
912 Fields:
913
914 ┌───────────┬────────────────────────┐
915 │Field name │ Description │
916 ├───────────┼────────────────────────┤
917 │baddr │ Base address of loaded │
918 │ │ library. │
919 ├───────────┼────────────────────────┤
920 │build_id │ Build ID. │
921 └───────────┴────────────────────────┘
922
923 lttng_ust_lib:debug_link
924 Emitted when debug link information is found in a loaded shared
925 library (shared object). See Debugging Information in Separate
926 Files <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
927 Files.html> for more information about debug links.
928
929 Fields:
930
931 ┌───────────┬────────────────────────┐
932 │Field name │ Description │
933 ├───────────┼────────────────────────┤
934 │baddr │ Base address of loaded │
935 │ │ library. │
936 ├───────────┼────────────────────────┤
937 │crc │ Debug link file’s CRC. │
938 ├───────────┼────────────────────────┤
939 │filename │ Debug link file name. │
940 └───────────┴────────────────────────┘
941
942 Detect if LTTng-UST is loaded
943 To detect if liblttng-ust is loaded from an application:
944
945 1. Define the lttng_ust_loaded weak symbol globally:
946
947 int lttng_ust_loaded __attribute__((weak));
948
949 This weak symbol is set by the constructor of liblttng-ust.
950
951 2. Test lttng_ust_loaded where needed:
952
953 /* ... */
954
955 if (lttng_ust_loaded) {
956 /* LTTng-UST is loaded */
957 } else {
958 /* LTTng-UST is NOT loaded */
959 }
960
961 /* ... */
962
964 Note
965 A few examples are available in the doc/examples
966 <https://github.com/lttng/lttng-ust/tree/v2.10.6/doc/examples>
967 directory of LTTng-UST’s source tree.
968
969 This example shows all the features documented in the previous
970 sections. The static linking method is chosen here to link the
971 application with the tracepoint provider.
972
973 You can compile the source files and link them together statically like
974 this:
975
976 $ cc -c -I. tp.c
977 $ cc -c app.c
978 $ cc -o app tp.o app.o -llttng-ust -ldl
979
980 Using the lttng(1) tool, create an LTTng tracing session, enable all
981 the events of this tracepoint provider, and start tracing:
982
983 $ lttng create my-session
984 $ lttng enable-event --userspace 'my_provider:*'
985 $ lttng start
986
987 You may also enable specific events:
988
989 $ lttng enable-event --userspace my_provider:big_event
990 $ lttng enable-event --userspace my_provider:event_instance2
991
992 Run the application:
993
994 $ ./app some arguments
995
996 Stop the current tracing session and inspect the recorded events:
997
998 $ lttng stop
999 $ lttng view
1000
1001 Tracepoint provider header file
1002 tp.h:
1003
1004 #undef TRACEPOINT_PROVIDER
1005 #define TRACEPOINT_PROVIDER my_provider
1006
1007 #undef TRACEPOINT_INCLUDE
1008 #define TRACEPOINT_INCLUDE "./tp.h"
1009
1010 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
1011 #define _TP_H
1012
1013 #include <lttng/tracepoint.h>
1014 #include <stdio.h>
1015
1016 #include "app.h"
1017
1018 TRACEPOINT_EVENT(
1019 my_provider,
1020 simple_event,
1021 TP_ARGS(
1022 int, my_integer_arg,
1023 const char *, my_string_arg
1024 ),
1025 TP_FIELDS(
1026 ctf_string(argc, my_string_arg)
1027 ctf_integer(int, argv, my_integer_arg)
1028 )
1029 )
1030
1031 TRACEPOINT_ENUM(
1032 my_provider,
1033 my_enum,
1034 TP_ENUM_VALUES(
1035 ctf_enum_value("ZERO", 0)
1036 ctf_enum_value("ONE", 1)
1037 ctf_enum_value("TWO", 2)
1038 ctf_enum_range("A RANGE", 52, 125)
1039 ctf_enum_value("ONE THOUSAND", 1000)
1040 )
1041 )
1042
1043 TRACEPOINT_EVENT(
1044 my_provider,
1045 big_event,
1046 TP_ARGS(
1047 int, my_integer_arg,
1048 const char *, my_string_arg,
1049 FILE *, stream,
1050 double, flt_arg,
1051 int *, array_arg
1052 ),
1053 TP_FIELDS(
1054 ctf_integer(int, int_field1, my_integer_arg * 2)
1055 ctf_integer_hex(long int, stream_pos, ftell(stream))
1056 ctf_float(double, float_field, flt_arg)
1057 ctf_string(string_field, my_string_arg)
1058 ctf_array(int, array_field, array_arg, 7)
1059 ctf_array_text(char, array_text_field, array_arg, 5)
1060 ctf_sequence(int, seq_field, array_arg, int,
1061 my_integer_arg / 10)
1062 ctf_sequence_text(char, seq_text_field, array_arg,
1063 int, my_integer_arg / 5)
1064 ctf_enum(my_provider, my_enum, int,
1065 enum_field, array_arg[1])
1066 )
1067 )
1068
1069 TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING)
1070
1071 TRACEPOINT_EVENT_CLASS(
1072 my_provider,
1073 my_tracepoint_class,
1074 TP_ARGS(
1075 int, my_integer_arg,
1076 struct app_struct *, app_struct_arg
1077 ),
1078 TP_FIELDS(
1079 ctf_integer(int, a, my_integer_arg)
1080 ctf_integer(unsigned long, b, app_struct_arg->b)
1081 ctf_string(c, app_struct_arg->c)
1082 )
1083 )
1084
1085 TRACEPOINT_EVENT_INSTANCE(
1086 my_provider,
1087 my_tracepoint_class,
1088 event_instance1,
1089 TP_ARGS(
1090 int, my_integer_arg,
1091 struct app_struct *, app_struct_arg
1092 )
1093 )
1094
1095 TRACEPOINT_EVENT_INSTANCE(
1096 my_provider,
1097 my_tracepoint_class,
1098 event_instance2,
1099 TP_ARGS(
1100 int, my_integer_arg,
1101 struct app_struct *, app_struct_arg
1102 )
1103 )
1104
1105 TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO)
1106
1107 TRACEPOINT_EVENT_INSTANCE(
1108 my_provider,
1109 my_tracepoint_class,
1110 event_instance3,
1111 TP_ARGS(
1112 int, my_integer_arg,
1113 struct app_struct *, app_struct_arg
1114 )
1115 )
1116
1117 #endif /* _TP_H */
1118
1119 #include <lttng/tracepoint-event.h>
1120
1121 Tracepoint provider source file
1122 tp.c:
1123
1124 #define TRACEPOINT_CREATE_PROBES
1125 #define TRACEPOINT_DEFINE
1126
1127 #include "tp.h"
1128
1129 Application header file
1130 app.h:
1131
1132 #ifndef _APP_H
1133 #define _APP_H
1134
1135 struct app_struct {
1136 unsigned long b;
1137 const char *c;
1138 double d;
1139 };
1140
1141 #endif /* _APP_H */
1142
1143 Application source file
1144 app.c:
1145
1146 #include <stdlib.h>
1147 #include <stdio.h>
1148
1149 #include "tp.h"
1150 #include "app.h"
1151
1152 static int array_of_ints[] = {
1153 100, -35, 1, 23, 14, -6, 28, 1001, -3000,
1154 };
1155
1156 int main(int argc, char* argv[])
1157 {
1158 FILE *stream;
1159 struct app_struct app_struct;
1160
1161 tracepoint(my_provider, simple_event, argc, argv[0]);
1162 stream = fopen("/tmp/app.txt", "w");
1163
1164 if (!stream) {
1165 fprintf(stderr,
1166 "Error: Cannot open /tmp/app.txt for writing\n");
1167 return EXIT_FAILURE;
1168 }
1169
1170 if (fprintf(stream, "0123456789") != 10) {
1171 fclose(stream);
1172 fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
1173 return EXIT_FAILURE;
1174 }
1175
1176 tracepoint(my_provider, big_event, 35, "hello tracepoint",
1177 stream, -3.14, array_of_ints);
1178 fclose(stream);
1179 app_struct.b = argc;
1180 app_struct.c = "[the string]";
1181 tracepoint(my_provider, event_instance1, 23, &app_struct);
1182 app_struct.b = argc * 5;
1183 app_struct.c = "[other string]";
1184 tracepoint(my_provider, event_instance2, 17, &app_struct);
1185 app_struct.b = 23;
1186 app_struct.c = "nothing";
1187 tracepoint(my_provider, event_instance3, -52, &app_struct);
1188
1189 return EXIT_SUCCESS;
1190 }
1191
1193 LTTNG_HOME
1194 Alternative user’s home directory. This variable is useful when the
1195 user running the instrumented application has a non-writable home
1196 directory.
1197
1198 Unix sockets used for the communication between liblttng-ust and
1199 the LTTng session and consumer daemons (part of the LTTng-tools
1200 project) are located in a specific directory under $LTTNG_HOME (or
1201 $HOME if $LTTNG_HOME is not set).
1202
1203 LTTNG_UST_ALLOW_BLOCKING
1204 If set, allow the application to retry event tracing when there’s
1205 no space left for the event record in the sub-buffer, therefore
1206 effectively blocking the application until space is made available
1207 or the configured timeout is reached.
1208
1209 To allow an application to block during tracing, you also need to
1210 specify a blocking timeout when you create a channel with the
1211 --blocking-timeout option of the lttng-enable-channel(1) command.
1212
1213 This option can be useful in workloads generating very large trace
1214 data throughput, where blocking the application is an acceptable
1215 trade-off to prevent discarding event records.
1216
1217 Warning
1218 Setting this environment variable may significantly affect
1219 application timings.
1220
1221 LTTNG_UST_CLOCK_PLUGIN
1222 Path to the shared object which acts as the clock override plugin.
1223 An example of such a plugin can be found in the LTTng-UST
1224 documentation under examples/clock-override
1225 <https://github.com/lttng/lttng-
1226 ust/tree/v2.10.6/doc/examples/clock-override>.
1227
1228 LTTNG_UST_DEBUG
1229 If set, enable liblttng-ust's debug and error output.
1230
1231 LTTNG_UST_GETCPU_PLUGIN
1232 Path to the shared object which acts as the getcpu() override
1233 plugin. An example of such a plugin can be found in the LTTng-UST
1234 documentation under examples/getcpu-override
1235 <https://github.com/lttng/lttng-
1236 ust/tree/v2.10.6/doc/examples/getcpu-override>.
1237
1238 LTTNG_UST_REGISTER_TIMEOUT
1239 Waiting time for the registration done session daemon command
1240 before proceeding to execute the main program (milliseconds).
1241
1242 The value 0 means do not wait. The value -1 means wait forever.
1243 Setting this environment variable to 0 is recommended for
1244 applications with time constraints on the process startup time.
1245
1246 Default: 3000.
1247
1248 LTTNG_UST_WITHOUT_BADDR_STATEDUMP
1249 If set, prevents liblttng-ust from performing a base address state
1250 dump (see the LTTng-UST state dump section above).
1251
1253 If you encounter any issue or usability problem, please report it on
1254 the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>.
1255
1257 · LTTng project website <http://lttng.org>
1258
1259 · LTTng documentation <http://lttng.org/docs>
1260
1261 · Git repositories <http://git.lttng.org>
1262
1263 · GitHub organization <http://github.com/lttng>
1264
1265 · Continuous integration <http://ci.lttng.org/>
1266
1267 · Mailing list <http://lists.lttng.org> for support and development:
1268 lttng-dev@lists.lttng.org
1269
1270 · IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
1271
1273 This library is part of the LTTng-UST project.
1274
1275 This library is distributed under the GNU Lesser General Public
1276 License, version 2.1 <http://www.gnu.org/licenses/old-
1277 licenses/lgpl-2.1.en.html>. See the COPYING
1278 <https://github.com/lttng/lttng-ust/blob/v2.10.6/COPYING> file for more
1279 details.
1280
1282 Thanks to Ericsson for funding this work, providing real-life use
1283 cases, and testing.
1284
1285 Special thanks to Michel Dagenais and the DORSAL laboratory
1286 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
1287 the LTTng journey.
1288
1290 LTTng-UST was originally written by Mathieu Desnoyers, with additional
1291 contributions from various other people. It is currently maintained by
1292 Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
1293
1295 tracef(3), tracelog(3), lttng-gen-tp(1), lttng-ust-dl(3), lttng-ust-
1296 cyg-profile(3), lttng(1), lttng-enable-event(1), lttng-list(1), lttng-
1297 add-context(1), babeltrace(1), dlopen(3), ld.so(8)
1298
1299
1300
1301LTTng 2.10.6 10/17/2019 LTTNG-UST(3)