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