| 1 | // SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com> |
| 2 | // SPDX-License-Identifier: CC-BY-4.0 |
| 3 | // |
| 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] |
| 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', |
| 64 | 'len_type', 'len_expr') |
| 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', |
| 68 | 'len_type', 'len_expr') |
| 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') |
| 86 | |
| 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` |
| 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 | |
| 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. |
| 117 | * Defining your own tracepoints. See the |
| 118 | <<creating-tp,Creating a tracepoint provider>> section below. |
| 119 | |
| 120 | |
| 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 | |
| 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 | |
| 157 | * <<tracepoint,Instrumenting your application with |
| 158 | `lttng_ust_tracepoint()` calls>> |
| 159 | * Building your application with LTTng-UST support, either |
| 160 | <<build-static,statically>> or <<build-dynamic,dynamically>>. |
| 161 | |
| 162 | A *tracepoint provider* is a compiled object containing the event probes |
| 163 | corresponding to your custom tracepoint definitions. A tracepoint |
| 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 | ------------------------------------------------------------------------ |
| 171 | #undef LTTNG_UST_TRACEPOINT_PROVIDER |
| 172 | #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider |
| 173 | |
| 174 | #undef LTTNG_UST_TRACEPOINT_INCLUDE |
| 175 | #define LTTNG_UST_TRACEPOINT_INCLUDE "./tp.h" |
| 176 | |
| 177 | #if !defined(_TP_H) || \ |
| 178 | defined(LTTNG_UST_TRACEPOINT_HEADER_MULTI_READ) |
| 179 | #define _TP_H |
| 180 | |
| 181 | #include <lttng/tracepoint.h> |
| 182 | |
| 183 | /* |
| 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. |
| 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` |
| 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). |
| 198 | Between `#include <lttng/tracepoint.h>` and `#endif` go |
| 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. |
| 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 | ------------------------------------------------------------------------ |
| 213 | #define LTTNG_UST_TRACEPOINT_CREATE_PROBES |
| 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 | |
| 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 |
| 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]] |
| 232 | `LTTNG_UST_TRACEPOINT_EVENT()` usage |
| 233 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 234 | The `LTTNG_UST_TRACEPOINT_EVENT()` macro is used in a template provider |
| 235 | header file (see the <<creating-tp,Creating a tracepoint provider>> |
| 236 | section above) to define LTTng-UST tracepoints. |
| 237 | |
| 238 | The `LTTNG_UST_TRACEPOINT_EVENT()` usage template is as follows: |
| 239 | |
| 240 | ------------------------------------------------------------------------ |
| 241 | LTTNG_UST_TRACEPOINT_EVENT( |
| 242 | /* Tracepoint provider name */ |
| 243 | my_provider, |
| 244 | |
| 245 | /* Tracepoint/event name */ |
| 246 | my_tracepoint, |
| 247 | |
| 248 | /* List of tracepoint arguments (input) */ |
| 249 | LTTNG_UST_TP_ARGS( |
| 250 | ... |
| 251 | ), |
| 252 | |
| 253 | /* List of fields of eventual event (output) */ |
| 254 | LTTNG_UST_TP_FIELDS( |
| 255 | ... |
| 256 | ) |
| 257 | ) |
| 258 | ------------------------------------------------------------------------ |
| 259 | |
| 260 | The `LTTNG_UST_TP_ARGS()` macro contains the input arguments of the tracepoint. |
| 261 | Those arguments can be used in the argument expressions of the output |
| 262 | fields defined in `LTTNG_UST_TP_FIELDS()`. |
| 263 | |
| 264 | The format of the `LTTNG_UST_TP_ARGS()` parameters is: C type, then argument name; |
| 265 | repeat as needed, up to ten times. For example: |
| 266 | |
| 267 | ------------------------------------------------------------------------ |
| 268 | LTTNG_UST_TP_ARGS( |
| 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 | |
| 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. |
| 280 | |
| 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. |
| 286 | |
| 287 | |
| 288 | [[ctf-macros]] |
| 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>>. |
| 294 | |
| 295 | Standard integer, displayed in base 10: |
| 296 | |
| 297 | [verse] |
| 298 | *lttng_ust_field_integer*('int_type', 'field_name', 'expr') |
| 299 | *lttng_ust_field_integer_nowrite*('int_type', 'field_name', 'expr') |
| 300 | |
| 301 | Standard integer, displayed in base 16: |
| 302 | |
| 303 | [verse] |
| 304 | *lttng_ust_field_integer_hex*('int_type', 'field_name', 'expr') |
| 305 | |
| 306 | Integer in network byte order (big endian), displayed in base 10: |
| 307 | |
| 308 | [verse] |
| 309 | *lttng_ust_field_integer_network*('int_type', 'field_name', 'expr') |
| 310 | |
| 311 | Integer in network byte order, displayed in base 16: |
| 312 | |
| 313 | [verse] |
| 314 | *lttng_ust_field_integer_network_hex*('int_type', 'field_name', 'expr') |
| 315 | |
| 316 | Floating point number: |
| 317 | |
| 318 | [verse] |
| 319 | *lttng_ust_field_float*('float_type', 'field_name', 'expr') |
| 320 | *lttng_ust_field_float_nowrite*('float_type', 'field_name', 'expr') |
| 321 | |
| 322 | Null-terminated string: |
| 323 | |
| 324 | [verse] |
| 325 | *lttng_ust_field_string*('field_name', 'expr') |
| 326 | *lttng_ust_field_string_nowrite*('field_name', 'expr') |
| 327 | |
| 328 | Statically-sized array of integers (`_hex` versions displayed in |
| 329 | hexadecimal, `_network` versions in network byte order): |
| 330 | |
| 331 | [verse] |
| 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') |
| 342 | |
| 343 | Statically-sized array, printed as text; no need to be null-terminated: |
| 344 | |
| 345 | [verse] |
| 346 | *lttng_ust_field_array_text*(char, 'field_name', 'expr', 'count') |
| 347 | *lttng_ust_field_array_text_nowrite*(char, 'field_name', 'expr', 'count') |
| 348 | |
| 349 | Dynamically-sized array of integers (`_hex` versions displayed in |
| 350 | hexadecimal, `_network` versions in network byte order): |
| 351 | |
| 352 | [verse] |
| 353 | *lttng_ust_field_sequence*('int_type', 'field_name', 'expr', 'len_type', |
| 354 | 'len_expr') |
| 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', |
| 358 | 'len_expr') |
| 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', |
| 362 | 'len_type', 'len_expr') |
| 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') |
| 370 | |
| 371 | Dynamically-sized array, displayed as text; no need to be null-terminated: |
| 372 | |
| 373 | [verse] |
| 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') |
| 378 | |
| 379 | Enumeration. The enumeration field must be defined before using this |
| 380 | macro with the `LTTNG_UST_TRACEPOINT_ENUM()` macro. See the |
| 381 | <<tracepoint-enum,`LTTNG_UST_TRACEPOINT_ENUM()` usage>> section for more |
| 382 | information. |
| 383 | |
| 384 | [verse] |
| 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') |
| 389 | |
| 390 | The parameters are: |
| 391 | |
| 392 | 'count':: |
| 393 | Number of elements in array/sequence. This must be known at |
| 394 | compile time. |
| 395 | |
| 396 | 'enum_name':: |
| 397 | Name of an enumeration field previously defined with the |
| 398 | `LTTNG_UST_TRACEPOINT_ENUM()` macro. See the |
| 399 | <<tracepoint-enum,`LTTNG_UST_TRACEPOINT_ENUM()` usage>> section for more |
| 400 | information. |
| 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 |
| 405 | of a given tracepoint are defined in the `LTTNG_UST_TP_ARGS()` macro (see |
| 406 | the <<creating-tp,Creating a tracepoint provider>> section above). |
| 407 | |
| 408 | 'field_name':: |
| 409 | Event field name (C identifier syntax, :not: a literal string). |
| 410 | |
| 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. |
| 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 | |
| 423 | 'len_type':: |
| 424 | Unsigned integer C type of sequence's length. |
| 425 | |
| 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 | |
| 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]] |
| 440 | `LTTNG_UST_TRACEPOINT_ENUM()` usage |
| 441 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 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 | |
| 447 | An enumeration field is defined with the `LTTNG_UST_TRACEPOINT_ENUM()` |
| 448 | macro: |
| 449 | |
| 450 | ------------------------------------------------------------------------ |
| 451 | LTTNG_UST_TRACEPOINT_ENUM( |
| 452 | /* Tracepoint provider name */ |
| 453 | my_provider, |
| 454 | |
| 455 | /* Enumeration name (unique in the whole tracepoint provider) */ |
| 456 | my_enum, |
| 457 | |
| 458 | /* Enumeration mappings */ |
| 459 | LTTNG_UST_TP_ENUM_VALUES( |
| 460 | ... |
| 461 | ) |
| 462 | ) |
| 463 | ------------------------------------------------------------------------ |
| 464 | |
| 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()`. |
| 469 | |
| 470 | `lttng_ust_field_enum_value()` is a single value mapping: |
| 471 | |
| 472 | [verse] |
| 473 | *lttng_ust_field_enum_value*('label', 'value') |
| 474 | |
| 475 | This macro maps the given 'label' string to the value 'value'. |
| 476 | |
| 477 | `lttng_ust_field_enum_range()` is a range mapping: |
| 478 | |
| 479 | [verse] |
| 480 | *lttng_ust_field_enum_range*('label', 'start', 'end') |
| 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]] |
| 491 | `LTTNG_UST_TRACEPOINT_EVENT_CLASS()` usage |
| 492 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 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 | |
| 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 |
| 503 | tracepoints can reuse the same serialization code. Reusing the same |
| 504 | code, when possible, can reduce cache pollution, thus improve |
| 505 | performance. |
| 506 | |
| 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_: |
| 511 | |
| 512 | ------------------------------------------------------------------------ |
| 513 | #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider |
| 514 | |
| 515 | /* ... */ |
| 516 | |
| 517 | LTTNG_UST_TRACEPOINT_EVENT_CLASS( |
| 518 | /* Tracepoint class provider name */ |
| 519 | my_provider, |
| 520 | |
| 521 | /* Tracepoint class name */ |
| 522 | my_tracepoint_class, |
| 523 | |
| 524 | /* List of tracepoint arguments (input) */ |
| 525 | LTTNG_UST_TP_ARGS( |
| 526 | ... |
| 527 | ), |
| 528 | |
| 529 | /* List of fields of eventual event (output) */ |
| 530 | LTTNG_UST_TP_FIELDS( |
| 531 | ... |
| 532 | ) |
| 533 | ) |
| 534 | ------------------------------------------------------------------------ |
| 535 | |
| 536 | Once the tracepoint class is defined, you can create as many tracepoint |
| 537 | instances as needed: |
| 538 | |
| 539 | ------------------------------------------------------------------------- |
| 540 | #define LTTNG_UST_TRACEPOINT_PROVIDER natality |
| 541 | |
| 542 | /* ... */ |
| 543 | |
| 544 | LTTNG_UST_TRACEPOINT_EVENT_INSTANCE( |
| 545 | /* Name of the tracepoint class provider */ |
| 546 | my_provider, |
| 547 | |
| 548 | /* Tracepoint class name */ |
| 549 | my_tracepoint_class, |
| 550 | |
| 551 | /* Name of the local (instance) tracepoint provider */ |
| 552 | natality, |
| 553 | |
| 554 | /* Tracepoint/event name */ |
| 555 | my_tracepoint, |
| 556 | |
| 557 | /* List of tracepoint arguments (input) */ |
| 558 | LTTNG_UST_TP_ARGS( |
| 559 | ... |
| 560 | ) |
| 561 | ) |
| 562 | ------------------------------------------------------------------------ |
| 563 | |
| 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. |
| 585 | |
| 586 | See the <<example,EXAMPLE>> section below for a complete example. |
| 587 | |
| 588 | |
| 589 | [[tracepoint-loglevel]] |
| 590 | `LTTNG_UST_TRACEPOINT_LOGLEVEL()` usage |
| 591 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 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 |
| 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: |
| 604 | |
| 605 | ------------------------------------------------------------------------ |
| 606 | LTTNG_UST_TRACEPOINT_LOGLEVEL( |
| 607 | /* Tracepoint provider name */ |
| 608 | my_provider, |
| 609 | |
| 610 | /* Tracepoint/event name */ |
| 611 | my_tracepoint, |
| 612 | |
| 613 | /* Log level */ |
| 614 | LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO |
| 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 |
| 631 | `lttng_ust_tracepoint()` macro: |
| 632 | |
| 633 | [verse] |
| 634 | #define *lttng_ust_tracepoint*('prov_name', 't_name', ...) |
| 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 |
| 648 | use `lttng_ust_tracepoint()` for this provider. |
| 649 | |
| 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. |
| 655 | |
| 656 | Sometimes, arguments to the tracepoint are expensive to compute (take |
| 657 | call stack, for example). To avoid the computation when the tracepoint |
| 658 | is disabled, you can use the `lttng_ust_tracepoint_enabled()` and |
| 659 | `lttng_ust_do_tracepoint()` macros: |
| 660 | |
| 661 | [verse] |
| 662 | #define *lttng_ust_tracepoint_enabled*('prov_name', 't_name') |
| 663 | #define *lttng_ust_do_tracepoint*('prov_name', 't_name', ...) |
| 664 | |
| 665 | `lttng_ust_tracepoint_enabled()` returns a non-zero value if the tracepoint |
| 666 | named 't_name' from the provider named 'prov_name' is enabled at |
| 667 | run time. |
| 668 | |
| 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 |
| 673 | in this situation: |
| 674 | |
| 675 | ------------------------------------------------------------------------ |
| 676 | if (lttng_ust_tracepoint_enabled(my_provider, my_tracepoint)) { |
| 677 | stuff = prepare_stuff(); |
| 678 | } |
| 679 | |
| 680 | lttng_ust_tracepoint(my_provider, my_tracepoint, stuff); |
| 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 | |
| 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. |
| 690 | |
| 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. |
| 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 | |
| 719 | Define `LTTNG_UST_TRACEPOINT_DEFINE` definition below the |
| 720 | `LTTNG_UST_TRACEPOINT_CREATE_PROBES` definition in the tracepoint |
| 721 | provider source: |
| 722 | |
| 723 | ------------------------------------------------------------------------ |
| 724 | #define LTTNG_UST_TRACEPOINT_CREATE_PROBES |
| 725 | #define LTTNG_UST_TRACEPOINT_DEFINE |
| 726 | |
| 727 | #include "tp.h" |
| 728 | ------------------------------------------------------------------------ |
| 729 | |
| 730 | Create the tracepoint provider object file: |
| 731 | |
| 732 | [role="term"] |
| 733 | ---- |
| 734 | $ cc -c -I. tp.c |
| 735 | ---- |
| 736 | |
| 737 | NOTE: Although an application instrumented with LTTng-UST tracepoints |
| 738 | can be compiled with a $$C++$$ compiler, tracepoint probes |
| 739 | should be compiled with a C compiler. |
| 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"] |
| 746 | ---- |
| 747 | $ ar rc tp.a tp.o |
| 748 | ---- |
| 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 |
| 759 | library containing it) and with `liblttng-ust` and `libdl` (`libc` on a |
| 760 | BSD system): |
| 761 | |
| 762 | [role="term"] |
| 763 | ---- |
| 764 | $ cc -o app tp.o app.o -llttng-ust -ldl |
| 765 | ---- |
| 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, |
| 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` |
| 787 | |
| 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`: |
| 793 | |
| 794 | ------------------------------------------------------------------------ |
| 795 | #define LTTNG_UST_TRACEPOINT_DEFINE |
| 796 | #define LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE |
| 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"] |
| 806 | ---- |
| 807 | $ cc -c -fpic -I. tp.c |
| 808 | ---- |
| 809 | |
| 810 | It is then linked as a shared library like this: |
| 811 | |
| 812 | [role="term"] |
| 813 | ---- |
| 814 | $ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust |
| 815 | ---- |
| 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"] |
| 823 | ---- |
| 824 | $ cc -o app app.o tp-define.o -ldl |
| 825 | ---- |
| 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 | |
| 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 | |
| 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 | |
| 883 | General context fields:: |
| 884 | + |
| 885 | `cpu_id`::: |
| 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 | |
| 893 | `ip`::: |
| 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 | |
| 899 | `pthread_id`::: |
| 900 | POSIX thread identifier. |
| 901 | + |
| 902 | Can be used on architectures where `pthread_t` maps nicely to an |
| 903 | `unsigned long` type. |
| 904 | |
| 905 | Process context fields:: |
| 906 | + |
| 907 | `procname`::: |
| 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 | |
| 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)). |
| 915 | |
| 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)). |
| 919 | |
| 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. |
| 927 | |
| 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. |
| 931 | |
| 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. |
| 937 | |
| 938 | `ipc_ns`::: |
| 939 | Inode number of the current IPC namespace (see |
| 940 | man:ipc_namespaces(7)) in the proc file system. |
| 941 | |
| 942 | `mnt_ns`::: |
| 943 | Inode number of the current mount point namespace (see |
| 944 | man:mount_namespaces(7)) in the proc file system. |
| 945 | |
| 946 | `net_ns`::: |
| 947 | Inode number of the current network namespace (see |
| 948 | man:network_namespaces(7)) in the proc file system. |
| 949 | |
| 950 | `pid_ns`::: |
| 951 | Inode number of the current process ID namespace (see |
| 952 | man:pid_namespaces(7)) in the proc file system. |
| 953 | |
| 954 | `time_ns`::: |
| 955 | Inode number of the current clock namespace (see |
| 956 | man:time_namespaces(7)) in the proc file system. |
| 957 | |
| 958 | `user_ns`::: |
| 959 | Inode number of the current user namespace (see |
| 960 | man:user_namespaces(7)) in the proc file system. |
| 961 | |
| 962 | `uts_ns`::: |
| 963 | Inode number of the current UTS namespace (see |
| 964 | man:uts_namespaces(7)) in the proc file system. |
| 965 | |
| 966 | Credential context fields (see man:credentials(7)):: |
| 967 | + |
| 968 | `vuid`::: |
| 969 | Virtual real user ID: real user ID as seen from the point of view of |
| 970 | the current user namespace (see man:user_namespaces(7)). |
| 971 | |
| 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)). |
| 975 | |
| 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)). |
| 979 | |
| 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)). |
| 984 | |
| 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)). |
| 988 | |
| 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)). |
| 993 | |
| 994 | |
| 995 | [[state-dump]] |
| 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 |
| 1000 | build IDs, and their debug link information are emitted as events |
| 1001 | by the tracer. |
| 1002 | |
| 1003 | The following LTTng-UST state dump events exist and must be enabled |
| 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). |
| 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 | |
| 1020 | `lttng_ust_statedump:bin_info`:: |
| 1021 | Emitted when information about a currently loaded executable or |
| 1022 | shared object is found. |
| 1023 | + |
| 1024 | Fields: |
| 1025 | + |
| 1026 | [options="header"] |
| 1027 | |=== |
| 1028 | |Field name |Description |
| 1029 | |
| 1030 | |`baddr` |
| 1031 | |Base address of loaded executable. |
| 1032 | |
| 1033 | |`memsz` |
| 1034 | |Size of loaded executable in memory. |
| 1035 | |
| 1036 | |`path` |
| 1037 | |Path to loaded executable file. |
| 1038 | |
| 1039 | |`is_pic` |
| 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). |
| 1051 | |=== |
| 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"] |
| 1062 | |=== |
| 1063 | |Field name |Description |
| 1064 | |
| 1065 | |`baddr` |
| 1066 | |Base address of loaded library. |
| 1067 | |
| 1068 | |`build_id` |
| 1069 | |Build ID. |
| 1070 | |=== |
| 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"] |
| 1081 | |=== |
| 1082 | |Field name |Description |
| 1083 | |
| 1084 | |`baddr` |
| 1085 | |Base address of loaded library. |
| 1086 | |
| 1087 | |`crc` |
| 1088 | |Debug link file's CRC. |
| 1089 | |
| 1090 | |`filename` |
| 1091 | |Debug link file name. |
| 1092 | |=== |
| 1093 | |
| 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 | |
| 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. |
| 1200 | |=== |
| 1201 | |
| 1202 | |
| 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 | |
| 1230 | [[example]] |
| 1231 | EXAMPLE |
| 1232 | ------- |
| 1233 | |
| 1234 | NOTE: A few examples are available in the |
| 1235 | https://github.com/lttng/lttng-ust/tree/stable-{lttng_version}/doc/examples[`doc/examples`] |
| 1236 | directory of LTTng-UST's source tree. |
| 1237 | |
| 1238 | This example shows all the features documented in the previous |
| 1239 | sections. The <<build-static,static linking>> method is chosen here |
| 1240 | to link the application with the tracepoint provider. |
| 1241 | |
| 1242 | You can compile the source files and link them together statically |
| 1243 | like this: |
| 1244 | |
| 1245 | [role="term"] |
| 1246 | ---- |
| 1247 | $ cc -c -I. tp.c |
| 1248 | $ cc -c app.c |
| 1249 | $ cc -o app tp.o app.o -llttng-ust -ldl |
| 1250 | ---- |
| 1251 | |
| 1252 | Using the man:lttng(1) tool, create an LTTng tracing session, enable |
| 1253 | all the events of this tracepoint provider, and start tracing: |
| 1254 | |
| 1255 | [role="term"] |
| 1256 | ---- |
| 1257 | $ lttng create my-session |
| 1258 | $ lttng enable-event --userspace 'my_provider:*' |
| 1259 | $ lttng start |
| 1260 | ---- |
| 1261 | |
| 1262 | You may also enable specific events: |
| 1263 | |
| 1264 | [role="term"] |
| 1265 | ---- |
| 1266 | $ lttng enable-event --userspace my_provider:big_event |
| 1267 | $ lttng enable-event --userspace my_provider:event_instance2 |
| 1268 | ---- |
| 1269 | |
| 1270 | Run the application: |
| 1271 | |
| 1272 | [role="term"] |
| 1273 | ---- |
| 1274 | $ ./app some arguments |
| 1275 | ---- |
| 1276 | |
| 1277 | Stop the current tracing session and inspect the recorded events: |
| 1278 | |
| 1279 | [role="term"] |
| 1280 | ---- |
| 1281 | $ lttng stop |
| 1282 | $ lttng view |
| 1283 | ---- |
| 1284 | |
| 1285 | |
| 1286 | Tracepoint provider header file |
| 1287 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1288 | `tp.h`: |
| 1289 | |
| 1290 | ------------------------------------------------------------------------ |
| 1291 | #undef LTTNG_UST_TRACEPOINT_PROVIDER |
| 1292 | #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider |
| 1293 | |
| 1294 | #undef LTTNG_USTTRACEPOINT_INCLUDE |
| 1295 | #define LTTNG_USTTRACEPOINT_INCLUDE "./tp.h" |
| 1296 | |
| 1297 | #if !defined(_TP_H) || \ |
| 1298 | defined(LTTNG_UST_TRACEPOINT_HEADER_MULTI_READ) |
| 1299 | #define _TP_H |
| 1300 | |
| 1301 | #include <lttng/tracepoint.h> |
| 1302 | #include <stdio.h> |
| 1303 | |
| 1304 | #include "app.h" |
| 1305 | |
| 1306 | LTTNG_UST_TRACEPOINT_EVENT( |
| 1307 | my_provider, |
| 1308 | simple_event, |
| 1309 | LTTNG_UST_TP_ARGS( |
| 1310 | int, my_integer_arg, |
| 1311 | const char *, my_string_arg |
| 1312 | ), |
| 1313 | LTTNG_UST_TP_FIELDS( |
| 1314 | lttng_ust_field_string(argc, my_string_arg) |
| 1315 | lttng_ust_field_integer(int, argv, my_integer_arg) |
| 1316 | ) |
| 1317 | ) |
| 1318 | |
| 1319 | LTTNG_UST_TRACEPOINT_ENUM( |
| 1320 | my_provider, |
| 1321 | my_enum, |
| 1322 | LTTNG_UST_TP_ENUM_VALUES( |
| 1323 | lttng_ust_field_enum_value("ZERO", 0) |
| 1324 | lttng_ust_field_enum_value("ONE", 1) |
| 1325 | lttng_ust_field_enum_value("TWO", 2) |
| 1326 | lttng_ust_field_enum_range("A RANGE", 52, 125) |
| 1327 | lttng_ust_field_enum_value("ONE THOUSAND", 1000) |
| 1328 | ) |
| 1329 | ) |
| 1330 | |
| 1331 | LTTNG_UST_TRACEPOINT_EVENT( |
| 1332 | my_provider, |
| 1333 | big_event, |
| 1334 | LTTNG_UST_TP_ARGS( |
| 1335 | int, my_integer_arg, |
| 1336 | const char *, my_string_arg, |
| 1337 | FILE *, stream, |
| 1338 | double, flt_arg, |
| 1339 | int *, array_arg |
| 1340 | ), |
| 1341 | LTTNG_UST_TP_FIELDS( |
| 1342 | lttng_ust_field_integer(int, int_field1, my_integer_arg * 2) |
| 1343 | lttng_ust_field_integer_hex(long int, stream_pos, |
| 1344 | ftell(stream)) |
| 1345 | lttng_ust_field_float(double, float_field, flt_arg) |
| 1346 | lttng_ust_field_string(string_field, my_string_arg) |
| 1347 | lttng_ust_field_array(int, array_field, array_arg, 7) |
| 1348 | lttng_ust_field_array_text(char, array_text_field, |
| 1349 | array_arg, 5) |
| 1350 | lttng_ust_field_sequence(int, seq_field, array_arg, unsigned int, |
| 1351 | my_integer_arg / 10) |
| 1352 | lttng_ust_field_sequence_text(char, seq_text_field, |
| 1353 | array_arg, unsigned int, |
| 1354 | my_integer_arg / 5) |
| 1355 | lttng_ust_field_enum(my_provider, my_enum, int, |
| 1356 | enum_field, array_arg[1]) |
| 1357 | ) |
| 1358 | ) |
| 1359 | |
| 1360 | LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, big_event, |
| 1361 | LTTNG_UST_TRACEPOINT_LOGLEVEL_WARNING) |
| 1362 | |
| 1363 | LTTNG_UST_TRACEPOINT_EVENT_CLASS( |
| 1364 | my_provider, |
| 1365 | my_tracepoint_class, |
| 1366 | LTTNG_UST_TP_ARGS( |
| 1367 | int, my_integer_arg, |
| 1368 | struct app_struct *, app_struct_arg |
| 1369 | ), |
| 1370 | LTTNG_UST_TP_FIELDS( |
| 1371 | lttng_ust_field_integer(int, a, my_integer_arg) |
| 1372 | lttng_ust_field_integer(unsigned long, b, app_struct_arg->b) |
| 1373 | lttng_ust_field_string(c, app_struct_arg->c) |
| 1374 | ) |
| 1375 | ) |
| 1376 | |
| 1377 | LTTNG_UST_TRACEPOINT_EVENT_INSTANCE( |
| 1378 | my_provider, |
| 1379 | my_tracepoint_class, |
| 1380 | my_provider, |
| 1381 | event_instance1, |
| 1382 | LTTNG_UST_TP_ARGS( |
| 1383 | int, my_integer_arg, |
| 1384 | struct app_struct *, app_struct_arg |
| 1385 | ) |
| 1386 | ) |
| 1387 | |
| 1388 | LTTNG_UST_TRACEPOINT_EVENT_INSTANCE( |
| 1389 | my_provider, |
| 1390 | my_tracepoint_class, |
| 1391 | my_provider, |
| 1392 | event_instance2, |
| 1393 | LTTNG_UST_TP_ARGS( |
| 1394 | int, my_integer_arg, |
| 1395 | struct app_struct *, app_struct_arg |
| 1396 | ) |
| 1397 | ) |
| 1398 | |
| 1399 | LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, event_instance2, |
| 1400 | LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO) |
| 1401 | |
| 1402 | LTTNG_UST_TRACEPOINT_EVENT_INSTANCE( |
| 1403 | my_provider, |
| 1404 | my_tracepoint_class, |
| 1405 | my_provider, |
| 1406 | event_instance3, |
| 1407 | LTTNG_UST_TP_ARGS( |
| 1408 | int, my_integer_arg, |
| 1409 | struct app_struct *, app_struct_arg |
| 1410 | ) |
| 1411 | ) |
| 1412 | |
| 1413 | #endif /* _TP_H */ |
| 1414 | |
| 1415 | #include <lttng/tracepoint-event.h> |
| 1416 | ------------------------------------------------------------------------ |
| 1417 | |
| 1418 | |
| 1419 | Tracepoint provider source file |
| 1420 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1421 | `tp.c`: |
| 1422 | |
| 1423 | ------------------------------------------------------------------------ |
| 1424 | #define LTTNG_UST_TRACEPOINT_CREATE_PROBES |
| 1425 | #define LTTNG_UST_TRACEPOINT_DEFINE |
| 1426 | |
| 1427 | #include "tp.h" |
| 1428 | ------------------------------------------------------------------------ |
| 1429 | |
| 1430 | |
| 1431 | Application header file |
| 1432 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 1433 | `app.h`: |
| 1434 | |
| 1435 | ------------------------------------------------------------------------ |
| 1436 | #ifndef _APP_H |
| 1437 | #define _APP_H |
| 1438 | |
| 1439 | struct app_struct { |
| 1440 | unsigned long b; |
| 1441 | const char *c; |
| 1442 | double d; |
| 1443 | }; |
| 1444 | |
| 1445 | #endif /* _APP_H */ |
| 1446 | ------------------------------------------------------------------------ |
| 1447 | |
| 1448 | |
| 1449 | Application source file |
| 1450 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 1451 | `app.c`: |
| 1452 | |
| 1453 | ------------------------------------------------------------------------ |
| 1454 | #include <stdlib.h> |
| 1455 | #include <stdio.h> |
| 1456 | |
| 1457 | #include "tp.h" |
| 1458 | #include "app.h" |
| 1459 | |
| 1460 | static int array_of_ints[] = { |
| 1461 | 100, -35, 1, 23, 14, -6, 28, 1001, -3000, |
| 1462 | }; |
| 1463 | |
| 1464 | int main(int argc, char* argv[]) |
| 1465 | { |
| 1466 | FILE *stream; |
| 1467 | struct app_struct app_struct; |
| 1468 | |
| 1469 | lttng_ust_tracepoint(my_provider, simple_event, argc, argv[0]); |
| 1470 | stream = fopen("/tmp/app.txt", "w"); |
| 1471 | |
| 1472 | if (!stream) { |
| 1473 | fprintf(stderr, |
| 1474 | "Error: Cannot open /tmp/app.txt for writing\n"); |
| 1475 | return EXIT_FAILURE; |
| 1476 | } |
| 1477 | |
| 1478 | if (fprintf(stream, "0123456789") != 10) { |
| 1479 | fclose(stream); |
| 1480 | fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n"); |
| 1481 | return EXIT_FAILURE; |
| 1482 | } |
| 1483 | |
| 1484 | lttng_ust_tracepoint(my_provider, big_event, 35, |
| 1485 | "hello tracepoint", stream, -3.14, |
| 1486 | array_of_ints); |
| 1487 | fclose(stream); |
| 1488 | app_struct.b = argc; |
| 1489 | app_struct.c = "[the string]"; |
| 1490 | lttng_ust_tracepoint(my_provider, event_instance1, 23, |
| 1491 | &app_struct); |
| 1492 | app_struct.b = argc * 5; |
| 1493 | app_struct.c = "[other string]"; |
| 1494 | lttng_ust_tracepoint(my_provider, event_instance2, 17, |
| 1495 | &app_struct); |
| 1496 | app_struct.b = 23; |
| 1497 | app_struct.c = "nothing"; |
| 1498 | lttng_ust_tracepoint(my_provider, event_instance3, -52, |
| 1499 | &app_struct); |
| 1500 | return EXIT_SUCCESS; |
| 1501 | } |
| 1502 | ------------------------------------------------------------------------ |
| 1503 | |
| 1504 | |
| 1505 | ENVIRONMENT VARIABLES |
| 1506 | --------------------- |
| 1507 | `LTTNG_UST_APP_PATH`:: |
| 1508 | Path under which unix sockets used for the communication between |
| 1509 | the application (tracee) instrumented with `liblttng-ust` and the |
| 1510 | LTTng session and consumer daemons (part of the LTTng-tools project) |
| 1511 | are located. When `$LTTNG_UST_APP_PATH` is specified, only this path |
| 1512 | is considered for connecting to a session daemon. The |
| 1513 | `$LTTNG_UST_APP_PATH` target directory must exist and be accessible |
| 1514 | by the user before the application is executed for tracing to work. |
| 1515 | Setting this environment variable disables connection to root and |
| 1516 | per-user session daemons. |
| 1517 | |
| 1518 | `LTTNG_HOME`:: |
| 1519 | Alternative user's home directory. This variable is useful when the |
| 1520 | user running the instrumented application has a non-writable home |
| 1521 | directory. This path is where unix sockets for communication with |
| 1522 | the per-user session daemon are located. |
| 1523 | |
| 1524 | `LTTNG_UST_ALLOW_BLOCKING`:: |
| 1525 | If set, allow the application to retry event tracing when there's |
| 1526 | no space left for the event record in the sub-buffer, therefore |
| 1527 | effectively blocking the application until space is made available |
| 1528 | or the configured timeout is reached. |
| 1529 | + |
| 1530 | To allow an application to block during tracing, you also need to |
| 1531 | specify a blocking timeout when you create a channel with the |
| 1532 | nloption:--blocking-timeout option of the man:lttng-enable-channel(1) |
| 1533 | command. |
| 1534 | + |
| 1535 | This option can be useful in workloads generating very large trace data |
| 1536 | throughput, where blocking the application is an acceptable trade-off to |
| 1537 | prevent discarding event records. |
| 1538 | + |
| 1539 | WARNING: Setting this environment variable may significantly |
| 1540 | affect application timings. |
| 1541 | |
| 1542 | `LTTNG_UST_ABORT_ON_CRITICAL`:: |
| 1543 | If set, abort the instrumented application on a critical error message. |
| 1544 | |
| 1545 | `LTTNG_UST_CLOCK_PLUGIN`:: |
| 1546 | Path to the shared object which acts as the clock override plugin. |
| 1547 | An example of such a plugin can be found in the LTTng-UST |
| 1548 | documentation under |
| 1549 | https://github.com/lttng/lttng-ust/tree/stable-{lttng_version}/doc/examples/clock-override[`examples/clock-override`]. |
| 1550 | |
| 1551 | `LTTNG_UST_DEBUG`:: |
| 1552 | If set, enable `liblttng-ust`'s debug and error output. |
| 1553 | |
| 1554 | `LTTNG_UST_GETCPU_PLUGIN`:: |
| 1555 | Path to the shared object which acts as the `getcpu()` override |
| 1556 | plugin. An example of such a plugin can be found in the LTTng-UST |
| 1557 | documentation under |
| 1558 | https://github.com/lttng/lttng-ust/tree/stable-{lttng_version}/doc/examples/getcpu-override[`examples/getcpu-override`]. |
| 1559 | |
| 1560 | `LTTNG_UST_MAP_POPULATE_POLICY`:: |
| 1561 | + |
| 1562 | -- |
| 1563 | If set, override the policy used to populate shared memory pages |
| 1564 | within the application. The expected values are: |
| 1565 | |
| 1566 | `none`::: |
| 1567 | Do not pre-populate any pages, take minor faults on first access |
| 1568 | while tracing. |
| 1569 | |
| 1570 | `cpu_possible`::: |
| 1571 | Pre-populate pages for all possible CPUs in the system, as |
| 1572 | listed by `/sys/devices/system/cpu/possible`. |
| 1573 | -- |
| 1574 | + |
| 1575 | Default: `none`. If the policy is unknown, use the default. |
| 1576 | |
| 1577 | `LTTNG_UST_REGISTER_TIMEOUT`:: |
| 1578 | Waiting time for the _registration done_ session daemon command |
| 1579 | before proceeding to execute the main program (milliseconds). |
| 1580 | + |
| 1581 | The value `0` means _do not wait_. The value `-1` means _wait forever_. |
| 1582 | Setting this environment variable to `0` is recommended for applications |
| 1583 | with time constraints on the process startup time. |
| 1584 | + |
| 1585 | Default: 3000. |
| 1586 | |
| 1587 | `LTTNG_UST_WITHOUT_BADDR_STATEDUMP`:: |
| 1588 | If set, prevents `liblttng-ust` from performing a base address state |
| 1589 | dump (see the <<state-dump,LTTng-UST state dump>> section above). |
| 1590 | |
| 1591 | `LTTNG_UST_WITHOUT_PROCNAME_STATEDUMP`:: |
| 1592 | If set, prevents `liblttng-ust` from performing a procname state |
| 1593 | dump (see the <<state-dump,LTTng-UST state dump>> section above). |
| 1594 | |
| 1595 | |
| 1596 | include::common-footer.txt[] |
| 1597 | |
| 1598 | include::common-copyrights.txt[] |
| 1599 | |
| 1600 | include::common-authors.txt[] |
| 1601 | |
| 1602 | |
| 1603 | SEE ALSO |
| 1604 | -------- |
| 1605 | man:lttng_ust_tracef(3), |
| 1606 | man:lttng_ust_tracelog(3), |
| 1607 | man:lttng-gen-tp(1), |
| 1608 | man:lttng-ust-dl(3), |
| 1609 | man:lttng-ust-cyg-profile(3), |
| 1610 | man:lttng(1), |
| 1611 | man:lttng-enable-event(1), |
| 1612 | man:lttng-list(1), |
| 1613 | man:lttng-add-context(1), |
| 1614 | man:babeltrace(1), |
| 1615 | man:dlopen(3), |
| 1616 | man:ld.so(8) |