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