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 | 690 | |
4ce89594 KS |
691 | Tracing in C/C++ constructors and destructors |
692 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
693 | ||
694 | As of LTTng-UST{nbsp}2.13, tracepoint definitions are implemented using | |
695 | compound literals. In the following cases, those compound literals are | |
696 | allocated on the heap: | |
697 | ||
698 | * g++{nbsp}<=={nbsp}4.8 is used as the compiler or, | |
699 | * `LTTNG_UST_ALLOCATE_COMPOUND_LITERAL_ON_HEAP` is defined in the C pre-processor flags | |
700 | and the application is compiled with a C++ compiler | |
701 | ||
702 | When the compound literals are heap-allocated, there are some cases in which | |
703 | both C-style and C++ constructors and destructors will not be traced. | |
704 | ||
705 | 1. C-style constructors and destructors in statically linked archives | |
706 | 2. C-style constructors and destructors in the application itself | |
707 | 3. Some C++-style constructors and destructors in the application and statically linked archives | |
708 | ||
709 | In the 3rd case above, which C++-style constructors and destructors will not be traced depends | |
710 | on the initialization order within each translation unit and across the entire program when | |
711 | all translation units are linked together. | |
4ddbd0b7 PP |
712 | |
713 | [[build-static]] | |
714 | Statically linking the tracepoint provider | |
715 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
716 | With the static linking method, compiled tracepoint providers are copied | |
717 | into the target application. | |
718 | ||
5b1163c6 PP |
719 | Define `LTTNG_UST_TRACEPOINT_DEFINE` definition below the |
720 | `LTTNG_UST_TRACEPOINT_CREATE_PROBES` definition in the tracepoint | |
721 | provider source: | |
4ddbd0b7 PP |
722 | |
723 | ------------------------------------------------------------------------ | |
5b1163c6 PP |
724 | #define LTTNG_UST_TRACEPOINT_CREATE_PROBES |
725 | #define LTTNG_UST_TRACEPOINT_DEFINE | |
4ddbd0b7 PP |
726 | |
727 | #include "tp.h" | |
728 | ------------------------------------------------------------------------ | |
729 | ||
730 | Create the tracepoint provider object file: | |
731 | ||
732 | [role="term"] | |
636cf2a0 PP |
733 | ---- |
734 | $ cc -c -I. tp.c | |
735 | ---- | |
4ddbd0b7 PP |
736 | |
737 | NOTE: Although an application instrumented with LTTng-UST tracepoints | |
5b1163c6 PP |
738 | can be compiled with a $$C++$$ compiler, tracepoint probes |
739 | should be compiled with a C compiler. | |
4ddbd0b7 PP |
740 | |
741 | At this point, you _can_ archive this tracepoint provider object file, | |
742 | possibly with other object files of your application or with other | |
743 | tracepoint provider object files, as a static library: | |
744 | ||
745 | [role="term"] | |
636cf2a0 PP |
746 | ---- |
747 | $ ar rc tp.a tp.o | |
748 | ---- | |
4ddbd0b7 PP |
749 | |
750 | Using a static library does have the advantage of centralising the | |
751 | tracepoint providers objects so they can be shared between multiple | |
752 | applications. This way, when the tracepoint provider is modified, the | |
753 | source code changes don't have to be patched into each application's | |
754 | source code tree. The applications need to be relinked after each | |
755 | change, but need not to be otherwise recompiled (unless the tracepoint | |
756 | provider's API changes). | |
757 | ||
758 | Then, link your application with this object file (or with the static | |
e9f549af PP |
759 | library containing it) and with `liblttng-ust` and `libdl` (`libc` on a |
760 | BSD system): | |
4ddbd0b7 PP |
761 | |
762 | [role="term"] | |
636cf2a0 | 763 | ---- |
e9f549af | 764 | $ cc -o app tp.o app.o -llttng-ust -ldl |
636cf2a0 | 765 | ---- |
4ddbd0b7 PP |
766 | |
767 | ||
768 | [[build-dynamic]] | |
769 | Dynamically loading the tracepoint provider | |
770 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
771 | The second approach to package the tracepoint provider is to use the | |
772 | dynamic loader: the library and its member functions are explicitly | |
773 | sought, loaded at run time. | |
774 | ||
775 | In this scenario, the tracepoint provider is compiled as a shared | |
776 | object. | |
777 | ||
778 | The process to create the tracepoint provider shared object is pretty | |
779 | much the same as the <<build-static,static linking method>>, except | |
780 | that: | |
781 | ||
782 | * Since the tracepoint provider is not part of the application, | |
5b1163c6 PP |
783 | `LTTNG_UST_TRACEPOINT_DEFINE` must be defined, for each tracepoint |
784 | provider, in exactly one source file of the _application_ | |
785 | * `LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next to | |
786 | `LTTNG_UST_TRACEPOINT_DEFINE` | |
4ddbd0b7 | 787 | |
5b1163c6 PP |
788 | Regarding `LTTNG_UST_TRACEPOINT_DEFINE` and |
789 | `LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE`, the recommended practice | |
790 | is to use a separate C source file in your application to define them, | |
791 | then include the tracepoint provider header files afterwards. For | |
792 | example, as `tp-define.c`: | |
4ddbd0b7 PP |
793 | |
794 | ------------------------------------------------------------------------ | |
5b1163c6 PP |
795 | #define LTTNG_UST_TRACEPOINT_DEFINE |
796 | #define LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE | |
4ddbd0b7 PP |
797 | |
798 | #include "tp.h" | |
799 | ------------------------------------------------------------------------ | |
800 | ||
801 | The tracepoint provider object file used to create the shared library is | |
802 | built like it is using the static linking method, but with the | |
803 | nloption:-fpic option: | |
804 | ||
805 | [role="term"] | |
636cf2a0 PP |
806 | ---- |
807 | $ cc -c -fpic -I. tp.c | |
808 | ---- | |
4ddbd0b7 PP |
809 | |
810 | It is then linked as a shared library like this: | |
811 | ||
812 | [role="term"] | |
636cf2a0 | 813 | ---- |
e9f549af | 814 | $ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust |
636cf2a0 | 815 | ---- |
4ddbd0b7 PP |
816 | |
817 | This tracepoint provider shared object isn't linked with the user | |
818 | application: it must be loaded manually. This is why the application is | |
819 | built with no mention of this tracepoint provider, but still needs | |
820 | libdl: | |
821 | ||
822 | [role="term"] | |
636cf2a0 PP |
823 | ---- |
824 | $ cc -o app app.o tp-define.o -ldl | |
825 | ---- | |
4ddbd0b7 PP |
826 | |
827 | There are two ways to dynamically load the tracepoint provider shared | |
828 | object: | |
829 | ||
830 | * Load it manually from the application using man:dlopen(3) | |
831 | * Make the dynamic loader load it with the `LD_PRELOAD` | |
832 | environment variable (see man:ld.so(8)) | |
833 | ||
834 | If the application does not dynamically load the tracepoint provider | |
835 | shared object using one of the methods above, tracing is disabled for | |
836 | this application, and the events are not listed in the output of | |
837 | man:lttng-list(1). | |
838 | ||
839 | Note that it is not safe to use man:dlclose(3) on a tracepoint provider | |
840 | shared object that is being actively used for tracing, due to a lack of | |
841 | reference counting from LTTng-UST to the shared object. | |
842 | ||
843 | For example, statically linking a tracepoint provider to a shared object | |
844 | which is to be dynamically loaded by an application (a plugin, for | |
845 | example) is not safe: the shared object, which contains the tracepoint | |
846 | provider, could be dynamically closed (man:dlclose(3)) at any time by | |
847 | the application. | |
848 | ||
849 | To instrument a shared object, either: | |
850 | ||
851 | * Statically link the tracepoint provider to the application, or | |
852 | * Build the tracepoint provider as a shared object (following the | |
853 | procedure shown in this section), and preload it when tracing is | |
854 | needed using the `LD_PRELOAD` environment variable. | |
855 | ||
856 | ||
857 | Using LTTng-UST with daemons | |
858 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
859 | Some extra care is needed when using `liblttng-ust` with daemon | |
860 | applications that call man:fork(2), man:clone(2), or BSD's man:rfork(2) | |
861 | without a following man:exec(3) family system call. The library | |
862 | `liblttng-ust-fork.so` needs to be preloaded before starting the | |
863 | application with the `LD_PRELOAD` environment variable (see | |
864 | man:ld.so(8)). | |
865 | ||
321d3c8d PP |
866 | To use `liblttng-ust` with a daemon application which closes file |
867 | descriptors that were not opened by it, preload the `liblttng-ust-fd.so` | |
868 | library before you start the application. Typical use cases include | |
869 | daemons closing all file descriptors after man:fork(2), and buggy | |
870 | applications doing ``double-closes''. | |
871 | ||
4ddbd0b7 PP |
872 | |
873 | Context information | |
874 | ~~~~~~~~~~~~~~~~~~~ | |
875 | Context information can be prepended by the LTTng-UST tracer before | |
876 | each event, or before specific events. | |
877 | ||
878 | Context fields can be added to specific channels using | |
879 | man:lttng-add-context(1). | |
880 | ||
881 | The following context fields are supported by LTTng-UST: | |
882 | ||
524a1173 PP |
883 | General context fields:: |
884 | + | |
885 | `cpu_id`::: | |
4ddbd0b7 PP |
886 | CPU ID. |
887 | + | |
888 | NOTE: This context field is always enabled, and it cannot be added | |
889 | with man:lttng-add-context(1). Its main purpose is to be used for | |
890 | dynamic event filtering. See man:lttng-enable-event(1) for more | |
891 | information about event filtering. | |
892 | ||
524a1173 | 893 | `ip`::: |
4ddbd0b7 PP |
894 | Instruction pointer: enables recording the exact address from which |
895 | an event was emitted. This context field can be used to | |
896 | reverse-lookup the source location that caused the event | |
897 | to be emitted. | |
898 | ||
524a1173 PP |
899 | `pthread_id`::: |
900 | POSIX thread identifier. | |
4ddbd0b7 | 901 | + |
524a1173 PP |
902 | Can be used on architectures where `pthread_t` maps nicely to an |
903 | `unsigned long` type. | |
4ddbd0b7 | 904 | |
524a1173 PP |
905 | Process context fields:: |
906 | + | |
907 | `procname`::: | |
4ddbd0b7 PP |
908 | Thread name, as set by man:exec(3) or man:prctl(2). It is |
909 | recommended that programs set their thread name with man:prctl(2) | |
910 | before hitting the first tracepoint for that thread. | |
911 | ||
524a1173 PP |
912 | `vpid`::: |
913 | Virtual process ID: process ID as seen from the point of view of the | |
914 | current process ID namespace (see man:pid_namespaces(7)). | |
4ddbd0b7 | 915 | |
524a1173 PP |
916 | `vtid`::: |
917 | Virtual thread ID: thread ID as seen from the point of view of the | |
918 | current process ID namespace (see man:pid_namespaces(7)). | |
735bef47 | 919 | |
524a1173 PP |
920 | perf context fields:: |
921 | + | |
922 | `perf:thread:COUNTER`::: | |
923 | perf counter named 'COUNTER'. Use `lttng add-context --list` to | |
924 | list the available perf counters. | |
925 | + | |
926 | Only available on IA-32 and x86-64 architectures. | |
735bef47 | 927 | |
524a1173 PP |
928 | `perf:thread:raw:rN:NAME`::: |
929 | perf counter with raw ID 'N' and custom name 'NAME'. See | |
930 | man:lttng-add-context(1) for more details. | |
735bef47 | 931 | |
524a1173 PP |
932 | Namespace context fields (see man:namespaces(7)):: |
933 | + | |
934 | `cgroup_ns`::: | |
935 | Inode number of the current control group namespace (see | |
936 | man:cgroup_namespaces(7)) in the proc file system. | |
735bef47 | 937 | |
524a1173 PP |
938 | `ipc_ns`::: |
939 | Inode number of the current IPC namespace (see | |
940 | man:ipc_namespaces(7)) in the proc file system. | |
735bef47 | 941 | |
524a1173 PP |
942 | `mnt_ns`::: |
943 | Inode number of the current mount point namespace (see | |
944 | man:mount_namespaces(7)) in the proc file system. | |
735bef47 | 945 | |
524a1173 PP |
946 | `net_ns`::: |
947 | Inode number of the current network namespace (see | |
948 | man:network_namespaces(7)) in the proc file system. | |
735bef47 | 949 | |
524a1173 PP |
950 | `pid_ns`::: |
951 | Inode number of the current process ID namespace (see | |
952 | man:pid_namespaces(7)) in the proc file system. | |
cefef7a7 | 953 | |
524a1173 PP |
954 | `time_ns`::: |
955 | Inode number of the current clock namespace (see | |
956 | man:time_namespaces(7)) in the proc file system. | |
735bef47 | 957 | |
524a1173 PP |
958 | `user_ns`::: |
959 | Inode number of the current user namespace (see | |
960 | man:user_namespaces(7)) in the proc file system. | |
4ddbd0b7 | 961 | |
524a1173 PP |
962 | `uts_ns`::: |
963 | Inode number of the current UTS namespace (see | |
964 | man:uts_namespaces(7)) in the proc file system. | |
fca2f191 | 965 | |
524a1173 PP |
966 | Credential context fields (see man:credentials(7)):: |
967 | + | |
968 | `vuid`::: | |
fca2f191 | 969 | Virtual real user ID: real user ID as seen from the point of view of |
524a1173 | 970 | the current user namespace (see man:user_namespaces(7)). |
fca2f191 | 971 | |
524a1173 PP |
972 | `vgid`::: |
973 | Virtual real group ID: real group ID as seen from the point of view | |
974 | of the current user namespace (see man:user_namespaces(7)). | |
fca2f191 | 975 | |
524a1173 PP |
976 | `veuid`::: |
977 | Virtual effective user ID: effective user ID as seen from the point | |
978 | of view of the current user namespace (see man:user_namespaces(7)). | |
fca2f191 | 979 | |
524a1173 PP |
980 | `vegid`::: |
981 | Virtual effective group ID: effective group ID as seen from the | |
982 | point of view of the current user namespace (see | |
983 | man:user_namespaces(7)). | |
fca2f191 | 984 | |
524a1173 PP |
985 | `vsuid`::: |
986 | Virtual saved set-user ID: saved set-user ID as seen from the point | |
987 | of view of the current user namespace (see man:user_namespaces(7)). | |
fca2f191 | 988 | |
524a1173 PP |
989 | `vsgid`::: |
990 | Virtual saved set-group ID: saved set-group ID as seen from the | |
991 | point of view of the current user namespace (see | |
992 | man:user_namespaces(7)). | |
fca2f191 | 993 | |
4ddbd0b7 | 994 | |
174434f5 | 995 | [[state-dump]] |
4ddbd0b7 PP |
996 | LTTng-UST state dump |
997 | ~~~~~~~~~~~~~~~~~~~~ | |
998 | If an application that uses `liblttng-ust` becomes part of a tracing | |
999 | session, information about its currently loaded shared objects, their | |
0c3c03e0 | 1000 | build IDs, and their debug link information are emitted as events |
4ddbd0b7 PP |
1001 | by the tracer. |
1002 | ||
1003 | The following LTTng-UST state dump events exist and must be enabled | |
d1194248 PP |
1004 | to record application state dumps. Note that, during the state dump |
1005 | phase, LTTng-UST can also emit _shared library load/unload_ events | |
1006 | (see <<ust-lib,Shared library load/unload tracking>> below). | |
4ddbd0b7 PP |
1007 | |
1008 | `lttng_ust_statedump:start`:: | |
1009 | Emitted when the state dump begins. | |
1010 | + | |
1011 | This event has no fields. | |
1012 | ||
1013 | `lttng_ust_statedump:end`:: | |
1014 | Emitted when the state dump ends. Once this event is emitted, it | |
1015 | is guaranteed that, for a given process, the state dump is | |
1016 | complete. | |
1017 | + | |
1018 | This event has no fields. | |
1019 | ||
6488ae4c | 1020 | `lttng_ust_statedump:bin_info`:: |
f5eb039d AB |
1021 | Emitted when information about a currently loaded executable or |
1022 | shared object is found. | |
4ddbd0b7 PP |
1023 | + |
1024 | Fields: | |
1025 | + | |
1026 | [options="header"] | |
8902dadc PP |
1027 | |=== |
1028 | |Field name |Description | |
1029 | ||
1030 | |`baddr` | |
d01f365a | 1031 | |Base address of loaded executable. |
8902dadc PP |
1032 | |
1033 | |`memsz` | |
d01f365a | 1034 | |Size of loaded executable in memory. |
8902dadc PP |
1035 | |
1036 | |`path` | |
d01f365a | 1037 | |Path to loaded executable file. |
8902dadc PP |
1038 | |
1039 | |`is_pic` | |
d1194248 PP |
1040 | |Whether or not the executable is position-independent code. |
1041 | ||
1042 | |`has_build_id` | |
1043 | |Whether or not the executable has a build ID. If this field is 1, you | |
1044 | can expect that an `lttng_ust_statedump:build_id` event record follows | |
1045 | this one (not necessarily immediately after). | |
1046 | ||
1047 | |`has_debug_link` | |
1048 | |Whether or not the executable has debug link information. If this field | |
1049 | is 1, you can expect that an `lttng_ust_statedump:debug_link` event | |
1050 | record follows this one (not necessarily immediately after). | |
8902dadc | 1051 | |=== |
4ddbd0b7 PP |
1052 | |
1053 | `lttng_ust_statedump:build_id`:: | |
1054 | Emitted when a build ID is found in a currently loaded shared | |
1055 | library. See | |
1056 | https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files] | |
1057 | for more information about build IDs. | |
1058 | + | |
1059 | Fields: | |
1060 | + | |
1061 | [options="header"] | |
8902dadc PP |
1062 | |=== |
1063 | |Field name |Description | |
1064 | ||
1065 | |`baddr` | |
d01f365a | 1066 | |Base address of loaded library. |
8902dadc PP |
1067 | |
1068 | |`build_id` | |
d01f365a | 1069 | |Build ID. |
8902dadc | 1070 | |=== |
4ddbd0b7 PP |
1071 | |
1072 | `lttng_ust_statedump:debug_link`:: | |
1073 | Emitted when debug link information is found in a currently loaded | |
1074 | shared library. See | |
1075 | https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files] | |
1076 | for more information about debug links. | |
1077 | + | |
1078 | Fields: | |
1079 | + | |
1080 | [options="header"] | |
8902dadc PP |
1081 | |=== |
1082 | |Field name |Description | |
1083 | ||
1084 | |`baddr` | |
d01f365a | 1085 | |Base address of loaded library. |
8902dadc PP |
1086 | |
1087 | |`crc` | |
d01f365a | 1088 | |Debug link file's CRC. |
8902dadc PP |
1089 | |
1090 | |`filename` | |
d01f365a | 1091 | |Debug link file name. |
d1194248 PP |
1092 | |=== |
1093 | ||
94be38e8 JR |
1094 | `lttng_ust_statedump:procname`:: |
1095 | The process procname at process start. | |
1096 | + | |
1097 | Fields: | |
1098 | + | |
1099 | [options="header"] | |
1100 | |=== | |
1101 | |Field name |Description | |
1102 | ||
1103 | |`procname` | |
1104 | |The process name. | |
1105 | ||
1106 | |=== | |
1107 | ||
d1194248 PP |
1108 | |
1109 | [[ust-lib]] | |
1110 | Shared library load/unload tracking | |
1111 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1112 | The <<state-dump,LTTng-UST state dump>> and the LTTng-UST helper library | |
1113 | to instrument the dynamic linker (see man:liblttng-ust-dl(3)) can emit | |
1114 | **shared library load/unload tracking** events. | |
1115 | ||
1116 | The following shared library load/unload tracking events exist and must | |
1117 | be enabled to track the loading and unloading of shared libraries: | |
1118 | ||
1119 | `lttng_ust_lib:load`:: | |
1120 | Emitted when a shared library (shared object) is loaded. | |
1121 | + | |
1122 | Fields: | |
1123 | + | |
1124 | [options="header"] | |
1125 | |=== | |
1126 | |Field name |Description | |
1127 | ||
1128 | |`baddr` | |
1129 | |Base address of loaded library. | |
1130 | ||
1131 | |`memsz` | |
1132 | |Size of loaded library in memory. | |
1133 | ||
1134 | |`path` | |
1135 | |Path to loaded library file. | |
1136 | ||
1137 | |`has_build_id` | |
1138 | |Whether or not the library has a build ID. If this field is 1, you | |
1139 | can expect that an `lttng_ust_lib:build_id` event record follows | |
1140 | this one (not necessarily immediately after). | |
1141 | ||
1142 | |`has_debug_link` | |
1143 | |Whether or not the library has debug link information. If this field | |
1144 | is 1, you can expect that an `lttng_ust_lib:debug_link` event | |
1145 | record follows this one (not necessarily immediately after). | |
1146 | |=== | |
1147 | ||
1148 | `lttng_ust_lib:unload`:: | |
1149 | Emitted when a shared library (shared object) is unloaded. | |
1150 | + | |
1151 | Fields: | |
1152 | + | |
1153 | [options="header"] | |
1154 | |=== | |
1155 | |Field name |Description | |
1156 | ||
1157 | |`baddr` | |
1158 | |Base address of unloaded library. | |
1159 | |=== | |
1160 | ||
1161 | `lttng_ust_lib:build_id`:: | |
1162 | Emitted when a build ID is found in a loaded shared library (shared | |
1163 | object). See | |
1164 | https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files] | |
1165 | for more information about build IDs. | |
1166 | + | |
1167 | Fields: | |
1168 | + | |
1169 | [options="header"] | |
1170 | |=== | |
1171 | |Field name |Description | |
1172 | ||
1173 | |`baddr` | |
1174 | |Base address of loaded library. | |
1175 | ||
1176 | |`build_id` | |
1177 | |Build ID. | |
1178 | |=== | |
1179 | ||
1180 | `lttng_ust_lib:debug_link`:: | |
1181 | Emitted when debug link information is found in a loaded | |
1182 | shared library (shared object). See | |
1183 | https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files] | |
1184 | for more information about debug links. | |
1185 | + | |
1186 | Fields: | |
1187 | + | |
1188 | [options="header"] | |
1189 | |=== | |
1190 | |Field name |Description | |
1191 | ||
1192 | |`baddr` | |
1193 | |Base address of loaded library. | |
1194 | ||
1195 | |`crc` | |
1196 | |Debug link file's CRC. | |
1197 | ||
1198 | |`filename` | |
1199 | |Debug link file name. | |
8902dadc | 1200 | |=== |
4ddbd0b7 PP |
1201 | |
1202 | ||
2c520d0e PP |
1203 | Detect if LTTng-UST is loaded |
1204 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1205 | To detect if `liblttng-ust` is loaded from an application: | |
1206 | ||
1207 | . Define the `lttng_ust_loaded` weak symbol globally: | |
1208 | + | |
1209 | ------------------------------------------------------------------------ | |
1210 | int lttng_ust_loaded __attribute__((weak)); | |
1211 | ------------------------------------------------------------------------ | |
1212 | + | |
1213 | This weak symbol is set by the constructor of `liblttng-ust`. | |
1214 | ||
1215 | . Test `lttng_ust_loaded` where needed: | |
1216 | + | |
1217 | ------------------------------------------------------------------------ | |
1218 | /* ... */ | |
1219 | ||
1220 | if (lttng_ust_loaded) { | |
1221 | /* LTTng-UST is loaded */ | |
1222 | } else { | |
1223 | /* LTTng-UST is NOT loaded */ | |
1224 | } | |
1225 | ||
1226 | /* ... */ | |
1227 | ------------------------------------------------------------------------ | |
1228 | ||
1229 | ||
4ddbd0b7 PP |
1230 | [[example]] |
1231 | EXAMPLE | |
1232 | ------- | |
1233 | NOTE: A few examples are available in the | |
f596de62 | 1234 | https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples[`doc/examples`] |
4ddbd0b7 PP |
1235 | directory of LTTng-UST's source tree. |
1236 | ||
1237 | This example shows all the features documented in the previous | |
1238 | sections. The <<build-static,static linking>> method is chosen here | |
1239 | to link the application with the tracepoint provider. | |
1240 | ||
885adac8 PP |
1241 | You can compile the source files and link them together statically |
1242 | like this: | |
1243 | ||
1244 | [role="term"] | |
636cf2a0 PP |
1245 | ---- |
1246 | $ cc -c -I. tp.c | |
1247 | $ cc -c app.c | |
e9f549af | 1248 | $ cc -o app tp.o app.o -llttng-ust -ldl |
636cf2a0 | 1249 | ---- |
885adac8 | 1250 | |
00665d8e PP |
1251 | Using the man:lttng(1) tool, create an LTTng tracing session, enable |
1252 | all the events of this tracepoint provider, and start tracing: | |
1253 | ||
1254 | [role="term"] | |
636cf2a0 PP |
1255 | ---- |
1256 | $ lttng create my-session | |
1257 | $ lttng enable-event --userspace 'my_provider:*' | |
1258 | $ lttng start | |
1259 | ---- | |
00665d8e PP |
1260 | |
1261 | You may also enable specific events: | |
1262 | ||
1263 | [role="term"] | |
636cf2a0 PP |
1264 | ---- |
1265 | $ lttng enable-event --userspace my_provider:big_event | |
1266 | $ lttng enable-event --userspace my_provider:event_instance2 | |
1267 | ---- | |
00665d8e PP |
1268 | |
1269 | Run the application: | |
1270 | ||
1271 | [role="term"] | |
636cf2a0 PP |
1272 | ---- |
1273 | $ ./app some arguments | |
1274 | ---- | |
00665d8e PP |
1275 | |
1276 | Stop the current tracing session and inspect the recorded events: | |
1277 | ||
1278 | [role="term"] | |
636cf2a0 PP |
1279 | ---- |
1280 | $ lttng stop | |
1281 | $ lttng view | |
1282 | ---- | |
00665d8e | 1283 | |
885adac8 PP |
1284 | |
1285 | Tracepoint provider header file | |
1286 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1287 | `tp.h`: | |
4ddbd0b7 PP |
1288 | |
1289 | ------------------------------------------------------------------------ | |
5b1163c6 PP |
1290 | #undef LTTNG_UST_TRACEPOINT_PROVIDER |
1291 | #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider | |
4ddbd0b7 | 1292 | |
5b1163c6 PP |
1293 | #undef LTTNG_USTTRACEPOINT_INCLUDE |
1294 | #define LTTNG_USTTRACEPOINT_INCLUDE "./tp.h" | |
4ddbd0b7 | 1295 | |
5b1163c6 PP |
1296 | #if !defined(_TP_H) || \ |
1297 | defined(LTTNG_UST_TRACEPOINT_HEADER_MULTI_READ) | |
4ddbd0b7 PP |
1298 | #define _TP_H |
1299 | ||
1300 | #include <lttng/tracepoint.h> | |
1301 | #include <stdio.h> | |
1302 | ||
1303 | #include "app.h" | |
1304 | ||
5b1163c6 | 1305 | LTTNG_UST_TRACEPOINT_EVENT( |
4ddbd0b7 PP |
1306 | my_provider, |
1307 | simple_event, | |
5b1163c6 | 1308 | LTTNG_UST_TP_ARGS( |
4ddbd0b7 PP |
1309 | int, my_integer_arg, |
1310 | const char *, my_string_arg | |
1311 | ), | |
5b1163c6 PP |
1312 | LTTNG_UST_TP_FIELDS( |
1313 | lttng_ust_field_string(argc, my_string_arg) | |
1314 | lttng_ust_field_integer(int, argv, my_integer_arg) | |
4ddbd0b7 PP |
1315 | ) |
1316 | ) | |
1317 | ||
5b1163c6 | 1318 | LTTNG_UST_TRACEPOINT_ENUM( |
4ddbd0b7 PP |
1319 | my_provider, |
1320 | my_enum, | |
5b1163c6 PP |
1321 | LTTNG_UST_TP_ENUM_VALUES( |
1322 | lttng_ust_field_enum_value("ZERO", 0) | |
1323 | lttng_ust_field_enum_value("ONE", 1) | |
1324 | lttng_ust_field_enum_value("TWO", 2) | |
1325 | lttng_ust_field_enum_range("A RANGE", 52, 125) | |
1326 | lttng_ust_field_enum_value("ONE THOUSAND", 1000) | |
4ddbd0b7 PP |
1327 | ) |
1328 | ) | |
1329 | ||
5b1163c6 | 1330 | LTTNG_UST_TRACEPOINT_EVENT( |
4ddbd0b7 PP |
1331 | my_provider, |
1332 | big_event, | |
5b1163c6 | 1333 | LTTNG_UST_TP_ARGS( |
4ddbd0b7 PP |
1334 | int, my_integer_arg, |
1335 | const char *, my_string_arg, | |
1336 | FILE *, stream, | |
1337 | double, flt_arg, | |
1338 | int *, array_arg | |
1339 | ), | |
5b1163c6 PP |
1340 | LTTNG_UST_TP_FIELDS( |
1341 | lttng_ust_field_integer(int, int_field1, my_integer_arg * 2) | |
1342 | lttng_ust_field_integer_hex(long int, stream_pos, | |
1343 | ftell(stream)) | |
1344 | lttng_ust_field_float(double, float_field, flt_arg) | |
1345 | lttng_ust_field_string(string_field, my_string_arg) | |
1346 | lttng_ust_field_array(int, array_field, array_arg, 7) | |
1347 | lttng_ust_field_array_text(char, array_text_field, | |
1348 | array_arg, 5) | |
7aa0de34 | 1349 | lttng_ust_field_sequence(int, seq_field, array_arg, unsigned int, |
5b1163c6 PP |
1350 | my_integer_arg / 10) |
1351 | lttng_ust_field_sequence_text(char, seq_text_field, | |
7aa0de34 | 1352 | array_arg, unsigned int, |
5b1163c6 PP |
1353 | my_integer_arg / 5) |
1354 | lttng_ust_field_enum(my_provider, my_enum, int, | |
1355 | enum_field, array_arg[1]) | |
4ddbd0b7 PP |
1356 | ) |
1357 | ) | |
1358 | ||
5b1163c6 PP |
1359 | LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, big_event, |
1360 | LTTNG_UST_TRACEPOINT_LOGLEVEL_WARNING) | |
4ddbd0b7 | 1361 | |
5b1163c6 | 1362 | LTTNG_UST_TRACEPOINT_EVENT_CLASS( |
4ddbd0b7 PP |
1363 | my_provider, |
1364 | my_tracepoint_class, | |
5b1163c6 | 1365 | LTTNG_UST_TP_ARGS( |
4ddbd0b7 PP |
1366 | int, my_integer_arg, |
1367 | struct app_struct *, app_struct_arg | |
1368 | ), | |
5b1163c6 PP |
1369 | LTTNG_UST_TP_FIELDS( |
1370 | lttng_ust_field_integer(int, a, my_integer_arg) | |
1371 | lttng_ust_field_integer(unsigned long, b, app_struct_arg->b) | |
1372 | lttng_ust_field_string(c, app_struct_arg->c) | |
4ddbd0b7 PP |
1373 | ) |
1374 | ) | |
1375 | ||
5b1163c6 | 1376 | LTTNG_UST_TRACEPOINT_EVENT_INSTANCE( |
4ddbd0b7 PP |
1377 | my_provider, |
1378 | my_tracepoint_class, | |
5b1163c6 | 1379 | my_provider, |
4ddbd0b7 | 1380 | event_instance1, |
5b1163c6 | 1381 | LTTNG_UST_TP_ARGS( |
4ddbd0b7 PP |
1382 | int, my_integer_arg, |
1383 | struct app_struct *, app_struct_arg | |
1384 | ) | |
1385 | ) | |
1386 | ||
5b1163c6 | 1387 | LTTNG_UST_TRACEPOINT_EVENT_INSTANCE( |
4ddbd0b7 PP |
1388 | my_provider, |
1389 | my_tracepoint_class, | |
5b1163c6 | 1390 | my_provider, |
4ddbd0b7 | 1391 | event_instance2, |
5b1163c6 | 1392 | LTTNG_UST_TP_ARGS( |
4ddbd0b7 PP |
1393 | int, my_integer_arg, |
1394 | struct app_struct *, app_struct_arg | |
1395 | ) | |
1396 | ) | |
1397 | ||
5b1163c6 PP |
1398 | LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, event_instance2, |
1399 | LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO) | |
4ddbd0b7 | 1400 | |
5b1163c6 | 1401 | LTTNG_UST_TRACEPOINT_EVENT_INSTANCE( |
4ddbd0b7 PP |
1402 | my_provider, |
1403 | my_tracepoint_class, | |
5b1163c6 | 1404 | my_provider, |
4ddbd0b7 | 1405 | event_instance3, |
5b1163c6 | 1406 | LTTNG_UST_TP_ARGS( |
4ddbd0b7 PP |
1407 | int, my_integer_arg, |
1408 | struct app_struct *, app_struct_arg | |
1409 | ) | |
1410 | ) | |
1411 | ||
1412 | #endif /* _TP_H */ | |
1413 | ||
1414 | #include <lttng/tracepoint-event.h> | |
1415 | ------------------------------------------------------------------------ | |
1416 | ||
885adac8 PP |
1417 | |
1418 | Tracepoint provider source file | |
1419 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1420 | `tp.c`: | |
4ddbd0b7 PP |
1421 | |
1422 | ------------------------------------------------------------------------ | |
5b1163c6 PP |
1423 | #define LTTNG_UST_TRACEPOINT_CREATE_PROBES |
1424 | #define LTTNG_UST_TRACEPOINT_DEFINE | |
4ddbd0b7 PP |
1425 | |
1426 | #include "tp.h" | |
1427 | ------------------------------------------------------------------------ | |
1428 | ||
885adac8 PP |
1429 | |
1430 | Application header file | |
1431 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1432 | `app.h`: | |
4ddbd0b7 PP |
1433 | |
1434 | ------------------------------------------------------------------------ | |
1435 | #ifndef _APP_H | |
1436 | #define _APP_H | |
1437 | ||
1438 | struct app_struct { | |
1439 | unsigned long b; | |
1440 | const char *c; | |
1441 | double d; | |
1442 | }; | |
1443 | ||
1444 | #endif /* _APP_H */ | |
1445 | ------------------------------------------------------------------------ | |
1446 | ||
885adac8 PP |
1447 | |
1448 | Application source file | |
1449 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1450 | `app.c`: | |
4ddbd0b7 PP |
1451 | |
1452 | ------------------------------------------------------------------------ | |
1453 | #include <stdlib.h> | |
1454 | #include <stdio.h> | |
1455 | ||
1456 | #include "tp.h" | |
1457 | #include "app.h" | |
1458 | ||
1459 | static int array_of_ints[] = { | |
1460 | 100, -35, 1, 23, 14, -6, 28, 1001, -3000, | |
1461 | }; | |
1462 | ||
1463 | int main(int argc, char* argv[]) | |
1464 | { | |
1465 | FILE *stream; | |
1466 | struct app_struct app_struct; | |
1467 | ||
5b1163c6 | 1468 | lttng_ust_tracepoint(my_provider, simple_event, argc, argv[0]); |
4ddbd0b7 PP |
1469 | stream = fopen("/tmp/app.txt", "w"); |
1470 | ||
1471 | if (!stream) { | |
1472 | fprintf(stderr, | |
1473 | "Error: Cannot open /tmp/app.txt for writing\n"); | |
1474 | return EXIT_FAILURE; | |
1475 | } | |
1476 | ||
1477 | if (fprintf(stream, "0123456789") != 10) { | |
1478 | fclose(stream); | |
1479 | fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n"); | |
1480 | return EXIT_FAILURE; | |
1481 | } | |
1482 | ||
5b1163c6 PP |
1483 | lttng_ust_tracepoint(my_provider, big_event, 35, |
1484 | "hello tracepoint", stream, -3.14, | |
1485 | array_of_ints); | |
4ddbd0b7 PP |
1486 | fclose(stream); |
1487 | app_struct.b = argc; | |
1488 | app_struct.c = "[the string]"; | |
5b1163c6 PP |
1489 | lttng_ust_tracepoint(my_provider, event_instance1, 23, |
1490 | &app_struct); | |
4ddbd0b7 PP |
1491 | app_struct.b = argc * 5; |
1492 | app_struct.c = "[other string]"; | |
5b1163c6 PP |
1493 | lttng_ust_tracepoint(my_provider, event_instance2, 17, |
1494 | &app_struct); | |
4ddbd0b7 PP |
1495 | app_struct.b = 23; |
1496 | app_struct.c = "nothing"; | |
5b1163c6 PP |
1497 | lttng_ust_tracepoint(my_provider, event_instance3, -52, |
1498 | &app_struct); | |
4ddbd0b7 PP |
1499 | return EXIT_SUCCESS; |
1500 | } | |
1501 | ------------------------------------------------------------------------ | |
1502 | ||
4ddbd0b7 | 1503 | |
174434f5 PP |
1504 | ENVIRONMENT VARIABLES |
1505 | --------------------- | |
c0f6fb05 MD |
1506 | `LTTNG_UST_APP_PATH`:: |
1507 | Path under which unix sockets used for the communication between | |
1508 | the application (tracee) instrumented with `liblttng-ust` and the | |
1509 | LTTng session and consumer daemons (part of the LTTng-tools project) | |
1510 | are located. When `$LTTNG_UST_APP_PATH` is specified, only this path | |
1511 | is considered for connecting to a session daemon. The | |
1512 | `$LTTNG_UST_APP_PATH` target directory must exist and be accessible | |
1513 | by the user before the application is executed for tracing to work. | |
1514 | Setting this environment variable disables connection to root and | |
1515 | per-user session daemons. | |
1516 | ||
8bc1125e | 1517 | `LTTNG_HOME`:: |
14dd1c6f PP |
1518 | Alternative user's home directory. This variable is useful when the |
1519 | user running the instrumented application has a non-writable home | |
c0f6fb05 MD |
1520 | directory. This path is where unix sockets for communication with |
1521 | the per-user session daemon are located. | |
0ce82328 | 1522 | |
b2c5f61a | 1523 | `LTTNG_UST_ALLOW_BLOCKING`:: |
d742d2aa | 1524 | If set, allow the application to retry event tracing when there's |
b2c5f61a MD |
1525 | no space left for the event record in the sub-buffer, therefore |
1526 | effectively blocking the application until space is made available | |
d742d2aa PP |
1527 | or the configured timeout is reached. |
1528 | + | |
1529 | To allow an application to block during tracing, you also need to | |
1530 | specify a blocking timeout when you create a channel with the | |
1531 | nloption:--blocking-timeout option of the man:lttng-enable-channel(1) | |
1532 | command. | |
c7667bfe | 1533 | + |
6f97f9c2 MD |
1534 | This option can be useful in workloads generating very large trace data |
1535 | throughput, where blocking the application is an acceptable trade-off to | |
1536 | prevent discarding event records. | |
1537 | + | |
b2c5f61a MD |
1538 | WARNING: Setting this environment variable may significantly |
1539 | affect application timings. | |
6f97f9c2 | 1540 | |
d7df80f6 MJ |
1541 | `LTTNG_UST_ABORT_ON_CRITICAL`:: |
1542 | If set, abort the instrumented application on a critical error message. | |
1543 | ||
62c2f155 PP |
1544 | `LTTNG_UST_CLOCK_PLUGIN`:: |
1545 | Path to the shared object which acts as the clock override plugin. | |
1546 | An example of such a plugin can be found in the LTTng-UST | |
1547 | documentation under | |
f596de62 | 1548 | https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/clock-override[`examples/clock-override`]. |
62c2f155 | 1549 | |
174434f5 | 1550 | `LTTNG_UST_DEBUG`:: |
702d1b7d | 1551 | If set, enable `liblttng-ust`'s debug and error output. |
174434f5 | 1552 | |
62c2f155 PP |
1553 | `LTTNG_UST_GETCPU_PLUGIN`:: |
1554 | Path to the shared object which acts as the `getcpu()` override | |
1555 | plugin. An example of such a plugin can be found in the LTTng-UST | |
1556 | documentation under | |
f596de62 | 1557 | https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/getcpu-override[`examples/getcpu-override`]. |
62c2f155 | 1558 | |
174434f5 | 1559 | `LTTNG_UST_REGISTER_TIMEOUT`:: |
14dd1c6f PP |
1560 | Waiting time for the _registration done_ session daemon command |
1561 | before proceeding to execute the main program (milliseconds). | |
174434f5 | 1562 | + |
14dd1c6f PP |
1563 | The value `0` means _do not wait_. The value `-1` means _wait forever_. |
1564 | Setting this environment variable to `0` is recommended for applications | |
174434f5 PP |
1565 | with time constraints on the process startup time. |
1566 | + | |
156b0cf7 | 1567 | Default: 3000. |
174434f5 PP |
1568 | |
1569 | `LTTNG_UST_WITHOUT_BADDR_STATEDUMP`:: | |
702d1b7d PP |
1570 | If set, prevents `liblttng-ust` from performing a base address state |
1571 | dump (see the <<state-dump,LTTng-UST state dump>> section above). | |
174434f5 | 1572 | |
94be38e8 JR |
1573 | `LTTNG_UST_WITHOUT_PROCNAME_STATEDUMP`:: |
1574 | If set, prevents `liblttng-ust` from performing a procname state | |
1575 | dump (see the <<state-dump,LTTng-UST state dump>> section above). | |
1576 | ||
174434f5 | 1577 | |
4ddbd0b7 PP |
1578 | include::common-footer.txt[] |
1579 | ||
1580 | include::common-copyrights.txt[] | |
1581 | ||
1582 | include::common-authors.txt[] | |
1583 | ||
1584 | ||
1585 | SEE ALSO | |
1586 | -------- | |
5b1163c6 PP |
1587 | man:lttng_ust_tracef(3), |
1588 | man:lttng_ust_tracelog(3), | |
4ddbd0b7 PP |
1589 | man:lttng-gen-tp(1), |
1590 | man:lttng-ust-dl(3), | |
1591 | man:lttng-ust-cyg-profile(3), | |
1592 | man:lttng(1), | |
1593 | man:lttng-enable-event(1), | |
1594 | man:lttng-list(1), | |
1595 | man:lttng-add-context(1), | |
1596 | man:babeltrace(1), | |
1597 | man:dlopen(3), | |
1598 | man:ld.so(8) |