1LTTNG-UST(3) LTTng Manual LTTNG-UST(3)
2
6 lttng-ust - LTTng user space tracing
7
9 #include <lttng/tracepoint.h>
10 #define TRACEPOINT_ENUM(prov_name, enum_name, mappings)
12 #define TRACEPOINT_EVENT(prov_name, t_name, args, fields)
13 #define TRACEPOINT_EVENT_CLASS(prov_name, class_name,
14 args, fields)
15 #define TRACEPOINT_EVENT_INSTANCE(prov_name, class_name,
16 t_name, args)
17 #define TRACEPOINT_LOGLEVEL(prov_name, t_name, level)
18 #define ctf_array(int_type, field_name, expr, count)
19 #define ctf_array_nowrite(int_type, field_name, expr, count)
20 #define ctf_array_text(char, field_name, expr, count)
21 #define ctf_array_text_nowrite(char, field_name, expr, count)
22 #define ctf_enum(prov_name, enum_name, int_type, field_name, expr)
23 #define ctf_enum_nowrite(prov_name, enum_name, int_type,
24 field_name, expr)
25 #define ctf_enum_value(label, value)
26 #define ctf_enum_range(label, start, end)
27 #define ctf_float(float_type, field_name, expr)
28 #define ctf_float_nowrite(float_type, field_name, expr)
29 #define ctf_integer(int_type, field_name, expr)
30 #define ctf_integer_hex(int_type, field_name, expr)
31 #define ctf_integer_network(int_type, field_name, expr)
32 #define ctf_integer_network_hex(int_type, field_name, expr)
33 #define ctf_integer_nowrite(int_type, field_name, expr)
34 #define ctf_sequence(int_type, field_name, expr, len_type, len_expr)
35 #define ctf_sequence_nowrite(int_type, field_name, expr,
36 len_type, len_expr)
37 #define ctf_sequence_text(char, field_name, expr, len_type, len_expr)
38 #define ctf_sequence_text_nowrite(char, field_name, expr,
39 len_type, len_expr)
40 #define ctf_string(field_name, expr)
41 #define ctf_string_nowrite(field_name, expr)
42 #define do_tracepoint(prov_name, t_name, ...)
43 #define tracepoint(prov_name, t_name, ...)
44 #define tracepoint_enabled(prov_name, t_name)
45 Link with -llttng-ust -ldl, following this man page.
47
49 The Linux Trace Toolkit: next generation <http://lttng.org/> is an open
50 source software package used for correlated tracing of the Linux
51 kernel, user applications, and user libraries.
52 LTTng-UST is the user space tracing component of the LTTng project. It
54 is a port to user space of the low-overhead tracing capabilities of the
55 LTTng Linux kernel tracer. The liblttng-ust library is used to trace
56 user applications and libraries.
57 Note
59 This man page is about the liblttng-ust library. The LTTng-UST
60 project also provides Java and Python packages to trace
61 applications written in those languages. How to instrument and
62 trace Java and Python applications is documented in the online
63 LTTng documentation <http://lttng.org/docs/>.
64 There are three ways to use liblttng-ust:
66 · Using the tracef(3) API, which is similar to printf(3).
68 · Using the tracelog(3) API, which is tracef(3) with a log level
70 parameter.
71 · Defining your own tracepoints. See the Creating a tracepoint
73 provider section below.
74 Creating a tracepoint provider
76 Creating a tracepoint provider is the first step of using liblttng-ust.
77 The next steps are:
78 · Instrumenting your application with tracepoint() calls
80 · Building your application with LTTng-UST support, either statically
82 or dynamically.
83 A tracepoint provider is a compiled object containing the event probes
85 corresponding to your custom tracepoint definitions. A tracepoint
86 provider contains the code to get the size of an event and to serialize
87 it, amongst other things.
88 To create a tracepoint provider, start with the following tracepoint
90 provider header template:
91 #undef TRACEPOINT_PROVIDER
93 #define TRACEPOINT_PROVIDER my_provider
94 #undef TRACEPOINT_INCLUDE
96 #define TRACEPOINT_INCLUDE "./tp.h"
97 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
99 #define _TP_H
100 #include <lttng/tracepoint.h>
102 /*
104 * TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
105 * TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(),
106 * and `TRACEPOINT_ENUM()` are used here.
107 */
108 #endif /* _TP_H */
110 #include <lttng/tracepoint-event.h>
112 In this template, the tracepoint provider is named my_provider
114 (TRACEPOINT_PROVIDER definition). The file needs to bear the name of
115 the TRACEPOINT_INCLUDE definition (tp.h in this case). Between #include
116 <lttng/tracepoint.h> and #endif go the invocations of the
117 TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
118 TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(), and
119 TRACEPOINT_ENUM() macros.
120 Note
122 You can avoid writing the prologue and epilogue boilerplate in the
123 template file above by using the lttng-gen-tp(1) tool shipped with
124 LTTng-UST.
125 The tracepoint provider header file needs to be included in a source
127 file which looks like this:
128 #define TRACEPOINT_CREATE_PROBES
130 #include "tp.h"
132 Together, those two files (let’s call them tp.h and tp.c) form the
134 tracepoint provider sources, ready to be compiled.
135 You can create multiple tracepoint providers to be used in a single
137 application, but each one must have its own header file.
138 The TRACEPOINT_EVENT() usage section below shows how to use the
140 TRACEPOINT_EVENT() macro to define the actual tracepoints in the
141 tracepoint provider header file.
142 See the EXAMPLE section below for a complete example.
144 TRACEPOINT_EVENT() usage
146 The TRACEPOINT_EVENT() macro is used in a template provider header file
147 (see the Creating a tracepoint provider section above) to define
148 LTTng-UST tracepoints.
149 The TRACEPOINT_EVENT() usage template is as follows:
151 TRACEPOINT_EVENT(
153 /* Tracepoint provider name */
154 my_provider,
155 /* Tracepoint/event name */
157 my_tracepoint,
158 /* List of tracepoint arguments (input) */
160 TP_ARGS(
161 ...
162 ),
163 /* List of fields of eventual event (output) */
165 TP_FIELDS(
166 ...
167 )
168 )
169 The TP_ARGS() macro contains the input arguments of the tracepoint.
171 Those arguments can be used in the argument expressions of the output
172 fields defined in TP_FIELDS().
173 The format of the TP_ARGS() parameters is: C type, then argument name;
175 repeat as needed, up to ten times. For example:
176 TP_ARGS(
178 int, my_int,
179 const char *, my_string,
180 FILE *, my_file,
181 double, my_float,
182 struct my_data *, my_data
183 )
184 The TP_FIELDS() macro contains the output fields of the tracepoint,
186 that is, the actual data that can be recorded in the payload of an
187 event emitted by this tracepoint.
188 The TP_FIELDS() macro contains a list of ctf_*() macros NOT separated
190 by commas. The available macros are documented in the Available ctf_*()
191 field type macros section below.
192 Available ctf_*() field type macros
194 This section documents the available ctf_*() macros that can be
195 inserted in the TP_FIELDS() macro of the TRACEPOINT_EVENT() macro.
196 Standard integer, displayed in base 10:
198 ctf_integer(int_type, field_name, expr)
200 ctf_integer_nowrite(int_type, field_name, expr)
201 Standard integer, displayed in base 16:
203 ctf_integer_hex(int_type, field_name, expr)
205 Integer in network byte order (big endian), displayed in base 10:
207 ctf_integer_network(int_type, field_name, expr)
209 Integer in network byte order, displayed in base 16:
211 ctf_integer_network_hex(int_type, field_name, expr)
213 Floating point number:
215 ctf_float(float_type, field_name, expr)
217 ctf_float_nowrite(float_type, field_name, expr)
218 Null-terminated string:
220 ctf_string(field_name, expr)
222 ctf_string_nowrite(field_name, expr)
223 Statically-sized array of integers:
225 ctf_array(int_type, field_name, expr, count)
227 ctf_array_nowrite(int_type, field_name, expr, count)
228 Statically-sized array, printed as text; no need to be null-terminated:
230 ctf_array_text(char, field_name, expr, count)
232 ctf_array_text_nowrite(char, field_name, expr, count)
233 Dynamically-sized array of integers:
235 ctf_sequence(int_type, field_name, expr, len_type, len_expr)
237 ctf_sequence_nowrite(int_type, field_name, expr, len_type, len_expr)
238 Dynamically-sized array, displayed as text; no need to be
240 null-terminated:
241 ctf_sequence_text(char, field_name, expr, len_type, len_expr)
243 ctf_sequence_text_nowrite(char, field_name, expr, len_type, len_expr)
244 Enumeration. The enumeration field must be defined before using this
246 macro with the TRACEPOINT_ENUM() macro. See the TRACEPOINT_ENUM() usage
247 section for more information.
248 ctf_enum(prov_name, enum_name, int_type, field_name, expr)
250 ctf_enum_nowrite(prov_name, enum_name, int_type, field_name, expr)
251 The parameters are:
253 int_type
255 Integer C type. The size of this type determines the size of the
256 integer/enumeration field.
257 float_type
259 Float C type (float or double). The size of this type determines
260 the size of the floating point number field.
261 field_name
263 Event field name (C identifier syntax, NOT a literal string).
264 expr
266 C expression resulting in the field’s value. This expression can
267 use one or more arguments passed to the tracepoint. The arguments
268 of a given tracepoint are defined in the TP_ARGS() macro (see the
269 Creating a tracepoint provider section above).
270 count
272 Number of elements in array/sequence. This must be known at compile
273 time.
274 len_type
276 Unsigned integer C type of sequence’s length.
277 len_expr
279 C expression resulting in the sequence’s length. This expression
280 can use one or more arguments passed to the tracepoint.
281 prov_name
283 Tracepoint provider name. This must be the same as the tracepoint
284 provider name used in a previous field definition.
285 enum_name
287 Name of an enumeration field previously defined with the
288 TRACEPOINT_ENUM() macro. See the TRACEPOINT_ENUM() usage section
289 for more information.
290 The _nowrite versions omit themselves from the recorded trace, but are
292 otherwise identical. Their primary purpose is to make some of the event
293 context available to the event filters without having to commit the
294 data to sub-buffers. See lttng-enable-event(1) to learn more about
295 dynamic event filtering.
296 See the EXAMPLE section below for a complete example.
298 TRACEPOINT_ENUM() usage
300 An enumeration field is a list of mappings between an integers, or a
301 range of integers, and strings (sometimes called labels or
302 enumerators). Enumeration fields can be used to have a more compact
303 trace when the possible values for a field are limited.
304 An enumeration field is defined with the TRACEPOINT_ENUM() macro:
306 TRACEPOINT_ENUM(
308 /* Tracepoint provider name */
309 my_provider,
310 /* Enumeration name (unique in the whole tracepoint provider) */
312 my_enum,
313 /* Enumeration mappings */
315 TP_ENUM_VALUES(
316 ...
317 )
318 )
319 TP_ENUM_VALUES() contains a list of enumeration mappings, NOT separated
321 by commas. Two macros can be used in the TP_ENUM_VALUES():
322 ctf_enum_value() and ctf_enum_range().
323 ctf_enum_value() is a single value mapping:
325 ctf_enum_value(label, value)
327 This macro maps the given label string to the value value.
329 ctf_enum_range() is a range mapping:
331 ctf_enum_range(label, start, end)
333 This macro maps the given label string to the range of integers from
335 start to end, inclusively. Range mappings may overlap, but the
336 behaviour is implementation-defined: each trace reader handles
337 overlapping ranges as it wishes.
338 See the EXAMPLE section below for a complete example.
340 TRACEPOINT_EVENT_CLASS() usage
342 A tracepoint class is a class of tracepoints sharing the same field
343 types and names. A tracepoint instance is one instance of such a
344 declared tracepoint class, with its own event name.
345 LTTng-UST creates one event serialization function per tracepoint
347 class. Using TRACEPOINT_EVENT() creates one tracepoint class per
348 tracepoint definition, whereas using TRACEPOINT_EVENT_CLASS() and
349 TRACEPOINT_EVENT_INSTANCE() creates one tracepoint class, and one or
350 more tracepoint instances of this class. In other words, many
351 tracepoints can reuse the same serialization code. Reusing the same
352 code, when possible, can reduce cache pollution, thus improve
353 performance.
354 The TRACEPOINT_EVENT_CLASS() macro accepts the same parameters as the
356 TRACEPOINT_EVENT() macro, except that instead of an event name, its
357 second parameter is the tracepoint class name:
358 TRACEPOINT_EVENT_CLASS(
360 /* Tracepoint provider name */
361 my_provider,
362 /* Tracepoint class name */
364 my_tracepoint_class,
365 /* List of tracepoint arguments (input) */
367 TP_ARGS(
368 ...
369 ),
370 /* List of fields of eventual event (output) */
372 TP_FIELDS(
373 ...
374 )
375 )
376 Once the tracepoint class is defined, you can create as many tracepoint
378 instances as needed:
379 TRACEPOINT_EVENT_INSTANCE(
381 /* Tracepoint provider name */
382 my_provider,
383 /* Tracepoint class name */
385 my_tracepoint_class,
386 /* Tracepoint/event name */
388 my_tracepoint,
389 /* List of tracepoint arguments (input) */
391 TP_ARGS(
392 ...
393 )
394 )
395 As you can see, the TRACEPOINT_EVENT_INSTANCE() does not contain the
397 TP_FIELDS() macro, because they are defined at the
398 TRACEPOINT_EVENT_CLASS() level.
399 See the EXAMPLE section below for a complete example.
401 TRACEPOINT_LOGLEVEL() usage
403 Optionally, a log level can be assigned to a defined tracepoint.
404 Assigning different levels of severity to tracepoints can be useful:
405 when controlling tracing sessions, you can choose to only enable events
406 falling into a specific log level range using the --loglevel and
407 --loglevel-only options of the lttng-enable-event(1) command.
408 Log levels are assigned to tracepoints that are already defined using
410 the TRACEPOINT_LOGLEVEL() macro. The latter must be used after having
411 used TRACEPOINT_EVENT() or TRACEPOINT_EVENT_INSTANCE() for a given
412 tracepoint. The TRACEPOINT_LOGLEVEL() macro is used as follows:
413 TRACEPOINT_LOGLEVEL(
415 /* Tracepoint provider name */
416 my_provider,
417 /* Tracepoint/event name */
419 my_tracepoint,
420 /* Log level */
422 TRACE_INFO
423 )
424 The available log level definitions are:
426 TRACE_EMERG
428 System is unusable.
429 TRACE_ALERT
431 Action must be taken immediately.
432 TRACE_CRIT
434 Critical conditions.
435 TRACE_ERR
437 Error conditions.
438 TRACE_WARNING
440 Warning conditions.
441 TRACE_NOTICE
443 Normal, but significant, condition.
444 TRACE_INFO
446 Informational message.
447 TRACE_DEBUG_SYSTEM
449 Debug information with system-level scope (set of programs).
450 TRACE_DEBUG_PROGRAM
452 Debug information with program-level scope (set of processes).
453 TRACE_DEBUG_PROCESS
455 Debug information with process-level scope (set of modules).
456 TRACE_DEBUG_MODULE
458 Debug information with module (executable/library) scope (set of
459 units).
460 TRACE_DEBUG_UNIT
462 Debug information with compilation unit scope (set of functions).
463 TRACE_DEBUG_FUNCTION
465 Debug information with function-level scope.
466 TRACE_DEBUG_LINE
468 Debug information with line-level scope (default log level).
469 TRACE_DEBUG
471 Debug-level message.
472 See the EXAMPLE section below for a complete example.
474 Instrumenting your application
476 Once the tracepoint provider is created (see the Creating a tracepoint
477 provider section above), you can instrument your application with the
478 defined tracepoints thanks to the tracepoint() macro:
479 #define tracepoint(prov_name, t_name, ...)
481 With:
483 prov_name
485 Tracepoint provider name.
486 t_name
488 Tracepoint/event name.
489 ...
491 Tracepoint arguments, if any.
492 Make sure to include the tracepoint provider header file anywhere you
494 use tracepoint() for this provider.
495 Note
497 Even though LTTng-UST supports tracepoint() call site duplicates
498 having the same provider and tracepoint names, it is recommended to
499 use a provider/tracepoint name pair only once within the
500 application source code to help map events back to their call sites
501 when analyzing the trace.
502 Sometimes, arguments to the tracepoint are expensive to compute (take
504 call stack, for example). To avoid the computation when the tracepoint
505 is disabled, you can use the tracepoint_enabled() and do_tracepoint()
506 macros:
507 #define tracepoint_enabled(prov_name, t_name)
509 #define do_tracepoint(prov_name, t_name, ...)
510 tracepoint_enabled() returns a non-zero value if the tracepoint named
512 t_name from the provider named prov_name is enabled at run time.
513 do_tracepoint() is like tracepoint(), except that it doesn’t check if
515 the tracepoint is enabled. Using tracepoint() with tracepoint_enabled()
516 is dangerous since tracepoint() also contains the tracepoint_enabled()
517 check, thus a race condition is possible in this situation:
518 if (tracepoint_enabled(my_provider, my_tracepoint)) {
520 stuff = prepare_stuff();
521 }
522 tracepoint(my_provider, my_tracepoint, stuff);
524 If the tracepoint is enabled after the condition, then stuff is not
526 prepared: the emitted event will either contain wrong data, or the
527 whole application could crash (segmentation fault, for example).
528 Note
530 Neither tracepoint_enabled() nor do_tracepoint() have a
531 STAP_PROBEV() call, so if you need it, you should emit this call
532 yourself.
533 Statically linking the tracepoint provider
535 With the static linking method, compiled tracepoint providers are
536 copied into the target application.
537 Define TRACEPOINT_DEFINE definition below the TRACEPOINT_CREATE_PROBES
539 definition in the tracepoint provider source:
540 #define TRACEPOINT_CREATE_PROBES
542 #define TRACEPOINT_DEFINE
543 #include "tp.h"
545 Create the tracepoint provider object file:
547 cc -c -I. tp.c
549 Note
552 Although an application instrumented with LTTng-UST tracepoints can
553 be compiled with a C++ compiler, tracepoint probes should be
554 compiled with a C compiler.
555 At this point, you can archive this tracepoint provider object file,
557 possibly with other object files of your application or with other
558 tracepoint provider object files, as a static library:
559 ar rc tp.a tp.o
561 Using a static library does have the advantage of centralising the
563 tracepoint providers objects so they can be shared between multiple
564 applications. This way, when the tracepoint provider is modified, the
565 source code changes don’t have to be patched into each application’s
566 source code tree. The applications need to be relinked after each
567 change, but need not to be otherwise recompiled (unless the tracepoint
568 provider’s API changes).
569 Then, link your application with this object file (or with the static
571 library containing it) and with liblttng-ust and libdl (libc on a BSD
572 system):
573 cc -o app tp.o app.o -llttng-ust -ldl
575 Dynamically loading the tracepoint provider
577 The second approach to package the tracepoint provider is to use the
578 dynamic loader: the library and its member functions are explicitly
579 sought, loaded at run time.
580 In this scenario, the tracepoint provider is compiled as a shared
582 object.
583 The process to create the tracepoint provider shared object is pretty
585 much the same as the static linking method, except that:
586 · Since the tracepoint provider is not part of the application,
588 TRACEPOINT_DEFINE must be defined, for each tracepoint provider, in
589 exactly one source file of the application
590 · TRACEPOINT_PROBE_DYNAMIC_LINKAGE must be defined next to
592 TRACEPOINT_DEFINE
593 Regarding TRACEPOINT_DEFINE and TRACEPOINT_PROBE_DYNAMIC_LINKAGE, the
595 recommended practice is to use a separate C source file in your
596 application to define them, then include the tracepoint provider header
597 files afterwards. For example, as tp-define.c:
598 #define TRACEPOINT_DEFINE
600 #define TRACEPOINT_PROBE_DYNAMIC_LINKAGE
601 #include "tp.h"
603 The tracepoint provider object file used to create the shared library
605 is built like it is using the static linking method, but with the -fpic
606 option:
607 cc -c -fpic -I. tp.c
609 It is then linked as a shared library like this:
611 cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
613 This tracepoint provider shared object isn’t linked with the user
615 application: it must be loaded manually. This is why the application is
616 built with no mention of this tracepoint provider, but still needs
617 libdl:
618 cc -o app app.o tp-define.o -ldl
620 There are two ways to dynamically load the tracepoint provider shared
622 object:
623 · Load it manually from the application using dlopen(3)
625 · Make the dynamic loader load it with the LD_PRELOAD environment
627 variable (see ld.so(8))
628 If the application does not dynamically load the tracepoint provider
630 shared object using one of the methods above, tracing is disabled for
631 this application, and the events are not listed in the output of lttng-
632 list(1).
633 Note that it is not safe to use dlclose(3) on a tracepoint provider
635 shared object that is being actively used for tracing, due to a lack of
636 reference counting from LTTng-UST to the shared object.
637 For example, statically linking a tracepoint provider to a shared
639 object which is to be dynamically loaded by an application (a plugin,
640 for example) is not safe: the shared object, which contains the
641 tracepoint provider, could be dynamically closed (dlclose(3)) at any
642 time by the application.
643 To instrument a shared object, either:
645 · Statically link the tracepoint provider to the application, or
647 · Build the tracepoint provider as a shared object (following the
649 procedure shown in this section), and preload it when tracing is
650 needed using the LD_PRELOAD environment variable.
651 Using LTTng-UST with daemons
653 Some extra care is needed when using liblttng-ust with daemon
654 applications that call fork(2), clone(2), or BSD’s rfork(2) without a
655 following exec(3) family system call. The library liblttng-ust-fork.so
656 needs to be preloaded before starting the application with the
657 LD_PRELOAD environment variable (see ld.so(8)).
658 Context information
660 Context information can be prepended by the LTTng-UST tracer before
661 each event, or before specific events.
662 Context fields can be added to specific channels using lttng-add-
664 context(1).
665 The following context fields are supported by LTTng-UST:
667 cpu_id
669 CPU ID.
670 Note
672 This context field is always enabled, and it cannot be added
673 with lttng-add-context(1). Its main purpose is to be used for
674 dynamic event filtering. See lttng-enable-event(1) for more
675 information about event filtering.
676 ip
678 Instruction pointer: enables recording the exact address from which
679 an event was emitted. This context field can be used to
680 reverse-lookup the source location that caused the event to be
681 emitted.
682 perf:thread:COUNTER
684 perf counter named COUNTER. Use lttng add-context --list to list
685 the available perf counters.
686 Only available on IA-32 and x86-64 architectures.
688 pthread_id
690 POSIX thread identifier. Can be used on architectures where
691 pthread_t maps nicely to an unsigned long type.
692 procname
694 Thread name, as set by exec(3) or prctl(2). It is recommended that
695 programs set their thread name with prctl(2) before hitting the
696 first tracepoint for that thread.
697 vpid
699 Virtual process ID: process ID as seen from the point of view of
700 the process namespace.
701 vtid
703 Virtual thread ID: thread ID as seen from the point of view of the
704 process namespace.
705 LTTng-UST state dump
707 If an application that uses liblttng-ust becomes part of a tracing
708 session, information about its currently loaded shared objects, their
709 build IDs, and their debug link informations are emitted as events by
710 the tracer.
711 The following LTTng-UST state dump events exist and must be enabled to
713 record application state dumps.
714 lttng_ust_statedump:start
716 Emitted when the state dump begins.
717 This event has no fields.
719 lttng_ust_statedump:end
721 Emitted when the state dump ends. Once this event is emitted, it is
722 guaranteed that, for a given process, the state dump is complete.
723 This event has no fields.
725 lttng_ust_statedump:bin_info
727 Emitted when information about a currently loaded executable or
728 shared object is found.
729 Fields:
731 ┌───────────┬───────────────────────────┐
733 │Field name │ Description │
734 ├───────────┼───────────────────────────┤
735 │baddr │ Base address of loaded │
736 │ │ executable │
737 ├───────────┼───────────────────────────┤
738 │memsz │ Size of loaded executable │
739 │ │ in memory │
740 ├───────────┼───────────────────────────┤
741 │path │ Path to loaded executable │
742 │ │ file │
743 ├───────────┼───────────────────────────┤
744 │is_pic │ Whether the executable is │
745 │ │ position-independent code │
746 └───────────┴───────────────────────────┘
747 lttng_ust_statedump:build_id
749 Emitted when a build ID is found in a currently loaded shared
750 library. See Debugging Information in Separate Files
751 <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
752 Files.html> for more information about build IDs.
753 Fields:
755 ┌───────────┬────────────────────────┐
757 │Field name │ Description │
758 ├───────────┼────────────────────────┤
759 │baddr │ Base address of loaded │
760 │ │ library │
761 ├───────────┼────────────────────────┤
762 │build_id │ Build ID │
763 └───────────┴────────────────────────┘
764 lttng_ust_statedump:debug_link
766 Emitted when debug link information is found in a currently loaded
767 shared library. See Debugging Information in Separate Files
768 <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
769 Files.html> for more information about debug links.
770 Fields:
772 ┌───────────┬────────────────────────┐
774 │Field name │ Description │
775 ├───────────┼────────────────────────┤
776 │baddr │ Base address of loaded │
777 │ │ library │
778 ├───────────┼────────────────────────┤
779 │crc │ Debug link file’s CRC │
780 ├───────────┼────────────────────────┤
781 │filename │ Debug link file name │
782 └───────────┴────────────────────────┘
783
785 Note
786 A few examples are available in the doc/examples
787 <https://github.com/lttng/lttng-ust/tree/master/doc/examples>
788 directory of LTTng-UST’s source tree.
789 This example shows all the features documented in the previous
791 sections. The static linking method is chosen here to link the
792 application with the tracepoint provider.
793 You can compile the source files and link them together statically like
795 this:
796 cc -c -I. tp.c
798 cc -c app.c
799 cc -o app tp.o app.o -llttng-ust -ldl
800 Using the lttng(1) tool, create an LTTng tracing session, enable all
802 the events of this tracepoint provider, and start tracing:
803 lttng create my-session
805 lttng enable-event --userspace 'my_provider:*'
806 lttng start
807 You may also enable specific events:
809 lttng enable-event --userspace my_provider:big_event
811 lttng enable-event --userspace my_provider:event_instance2
812 Run the application:
814 ./app some arguments
816 Stop the current tracing session and inspect the recorded events:
818 lttng stop
820 lttng view
821 Tracepoint provider header file
823 tp.h:
824 #undef TRACEPOINT_PROVIDER
826 #define TRACEPOINT_PROVIDER my_provider
827 #undef TRACEPOINT_INCLUDE
829 #define TRACEPOINT_INCLUDE "./tp.h"
830 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
832 #define _TP_H
833 #include <lttng/tracepoint.h>
835 #include <stdio.h>
836 #include "app.h"
838 TRACEPOINT_EVENT(
840 my_provider,
841 simple_event,
842 TP_ARGS(
843 int, my_integer_arg,
844 const char *, my_string_arg
845 ),
846 TP_FIELDS(
847 ctf_string(argc, my_string_arg)
848 ctf_integer(int, argv, my_integer_arg)
849 )
850 )
851 TRACEPOINT_ENUM(
853 my_provider,
854 my_enum,
855 TP_ENUM_VALUES(
856 ctf_enum_value("ZERO", 0)
857 ctf_enum_value("ONE", 1)
858 ctf_enum_value("TWO", 2)
859 ctf_enum_range("A RANGE", 52, 125)
860 ctf_enum_value("ONE THOUSAND", 1000)
861 )
862 )
863 TRACEPOINT_EVENT(
865 my_provider,
866 big_event,
867 TP_ARGS(
868 int, my_integer_arg,
869 const char *, my_string_arg,
870 FILE *, stream,
871 double, flt_arg,
872 int *, array_arg
873 ),
874 TP_FIELDS(
875 ctf_integer(int, int_field1, my_integer_arg * 2)
876 ctf_integer_hex(long int, stream_pos, ftell(stream))
877 ctf_float(double, float_field, flt_arg)
878 ctf_string(string_field, my_string_arg)
879 ctf_array(int, array_field, array_arg, 7)
880 ctf_array_text(char, array_text_field, array_arg, 5)
881 ctf_sequence(int, seq_field, array_arg, int,
882 my_integer_arg / 10)
883 ctf_sequence_text(char, seq_text_field, array_arg,
884 int, my_integer_arg / 5)
885 ctf_enum(my_provider, my_enum, int,
886 enum_field, array_arg[1])
887 )
888 )
889 TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING)
891 TRACEPOINT_EVENT_CLASS(
893 my_provider,
894 my_tracepoint_class,
895 TP_ARGS(
896 int, my_integer_arg,
897 struct app_struct *, app_struct_arg
898 ),
899 TP_FIELDS(
900 ctf_integer(int, a, my_integer_arg)
901 ctf_integer(unsigned long, b, app_struct_arg->b)
902 ctf_string(c, app_struct_arg->c)
903 )
904 )
905 TRACEPOINT_EVENT_INSTANCE(
907 my_provider,
908 my_tracepoint_class,
909 event_instance1,
910 TP_ARGS(
911 int, my_integer_arg,
912 struct app_struct *, app_struct_arg
913 )
914 )
915 TRACEPOINT_EVENT_INSTANCE(
917 my_provider,
918 my_tracepoint_class,
919 event_instance2,
920 TP_ARGS(
921 int, my_integer_arg,
922 struct app_struct *, app_struct_arg
923 )
924 )
925 TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO)
927 TRACEPOINT_EVENT_INSTANCE(
929 my_provider,
930 my_tracepoint_class,
931 event_instance3,
932 TP_ARGS(
933 int, my_integer_arg,
934 struct app_struct *, app_struct_arg
935 )
936 )
937 #endif /* _TP_H */
939 #include <lttng/tracepoint-event.h>
941 Tracepoint provider source file
943 tp.c:
944 #define TRACEPOINT_CREATE_PROBES
946 #define TRACEPOINT_DEFINE
947 #include "tp.h"
949 Application header file
951 app.h:
952 #ifndef _APP_H
954 #define _APP_H
955 struct app_struct {
957 unsigned long b;
958 const char *c;
959 double d;
960 };
961 #endif /* _APP_H */
963 Application source file
965 app.c:
966 #include <stdlib.h>
968 #include <stdio.h>
969 #include "tp.h"
971 #include "app.h"
972 static int array_of_ints[] = {
974 100, -35, 1, 23, 14, -6, 28, 1001, -3000,
975 };
976 int main(int argc, char* argv[])
978 {
979 FILE *stream;
980 struct app_struct app_struct;
981 tracepoint(my_provider, simple_event, argc, argv[0]);
983 stream = fopen("/tmp/app.txt", "w");
984 if (!stream) {
986 fprintf(stderr,
987 "Error: Cannot open /tmp/app.txt for writing\n");
988 return EXIT_FAILURE;
989 }
990 if (fprintf(stream, "0123456789") != 10) {
992 fclose(stream);
993 fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
994 return EXIT_FAILURE;
995 }
996 tracepoint(my_provider, big_event, 35, "hello tracepoint",
998 stream, -3.14, array_of_ints);
999 fclose(stream);
1000 app_struct.b = argc;
1001 app_struct.c = "[the string]";
1002 tracepoint(my_provider, event_instance1, 23, &app_struct);
1003 app_struct.b = argc * 5;
1004 app_struct.c = "[other string]";
1005 tracepoint(my_provider, event_instance2, 17, &app_struct);
1006 app_struct.b = 23;
1007 app_struct.c = "nothing";
1008 tracepoint(my_provider, event_instance3, -52, &app_struct);
1009 return EXIT_SUCCESS;
1011 }
1012
1014 LTTNG_HOME
1015 Alternative user’s home directory. This variable is useful when the
1016 user running the instrumented application has a non-writable home
1017 directory.
1018 Unix sockets used for the communication between liblttng-ust and
1020 the LTTng session and consumer daemons (part of the LTTng-tools
1021 project) are located in a specific directory under $LTTNG_HOME (or
1022 $HOME if $LTTNG_HOME is not set).
1023 LTTNG_UST_CLOCK_PLUGIN
1025 Path to the shared object which acts as the clock override plugin.
1026 An example of such a plugin can be found in the LTTng-UST
1027 documentation under examples/clock-override
1028 <https://github.com/lttng/lttng-ust/tree/master/doc/examples/clock-
1029 override>.
1030 LTTNG_UST_DEBUG
1032 Activates liblttng-ust's debug and error output if set to 1.
1033 LTTNG_UST_GETCPU_PLUGIN
1035 Path to the shared object which acts as the getcpu() override
1036 plugin. An example of such a plugin can be found in the LTTng-UST
1037 documentation under examples/getcpu-override
1038 <https://github.com/lttng/lttng-
1039 ust/tree/master/doc/examples/getcpu-override>.
1040 LTTNG_UST_REGISTER_TIMEOUT
1042 Waiting time for the registration done session daemon command
1043 before proceeding to execute the main program (milliseconds).
1044 The value 0 means do not wait. The value -1 means wait forever.
1046 Setting this environment variable to 0 is recommended for
1047 applications with time constraints on the process startup time.
1048 Default: 3000.
1050 LTTNG_UST_WITHOUT_BADDR_STATEDUMP
1052 Prevents liblttng-ust from performing a base address state dump
1053 (see the LTTng-UST state dump section above) if set to 1.
1054
1056 If you encounter any issue or usability problem, please report it on
1057 the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>.
1058
1060 · LTTng project website <http://lttng.org>
1061 · LTTng documentation <http://lttng.org/docs>
1063 · Git repositories <http://git.lttng.org>
1065 · GitHub organization <http://github.com/lttng>
1067 · Continuous integration <http://ci.lttng.org/>
1069 · Mailing list <http://lists.lttng.org> for support and development:
1071 lttng-dev@lists.lttng.org
1072 · IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
1074
1076 This library is part of the LTTng-UST project.
1077 This library is distributed under the GNU Lesser General Public
1079 License, version 2.1 <http://www.gnu.org/licenses/old-
1080 licenses/lgpl-2.1.en.html>. See the COPYING
1081 <https://github.com/lttng/lttng-ust/blob/master/COPYING> file for more
1082 details.
1083
1085 Thanks to Ericsson for funding this work, providing real-life use
1086 cases, and testing.
1087 Special thanks to Michel Dagenais and the DORSAL laboratory
1089 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
1090 the LTTng journey.
1091
1093 LTTng-UST was originally written by Mathieu Desnoyers, with additional
1094 contributions from various other people. It is currently maintained by
1095 Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
1096
1098 tracef(3), tracelog(3), lttng-gen-tp(1), lttng-ust-dl(3), lttng-ust-
1099 cyg-profile(3), lttng(1), lttng-enable-event(1), lttng-list(1), lttng-
1100 add-context(1), babeltrace(1), dlopen(3), ld.so(8)
1101LTTng 2.9.0-pre 06/05/2016 LTTNG-UST(3)