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