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