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