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