| 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 *TRACEPOINT_ENUM*('prov_name', 'enum_name', 'mappings') |
| 18 | #define *TRACEPOINT_EVENT*('prov_name', 't_name', 'args', 'fields') |
| 19 | #define *TRACEPOINT_EVENT_CLASS*('prov_name', 'class_name', |
| 20 | 'args', 'fields') |
| 21 | #define *TRACEPOINT_EVENT_INSTANCE*('prov_name', 'class_name', |
| 22 | 't_name', 'args') |
| 23 | #define *TRACEPOINT_LOGLEVEL*('prov_name', 't_name', 'level') |
| 24 | #define *ctf_array*('int_type', 'field_name', 'expr', 'count') |
| 25 | #define *ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count') |
| 26 | #define *ctf_array_text*(char, 'field_name', 'expr', 'count') |
| 27 | #define *ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count') |
| 28 | #define *ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr') |
| 29 | #define *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type', |
| 30 | 'field_name', 'expr') |
| 31 | #define *ctf_enum_value*('label', 'value') |
| 32 | #define *ctf_enum_range*('label', 'start', 'end') |
| 33 | #define *ctf_float*('float_type', 'field_name', 'expr') |
| 34 | #define *ctf_float_nowrite*('float_type', 'field_name', 'expr') |
| 35 | #define *ctf_integer*('int_type', 'field_name', 'expr') |
| 36 | #define *ctf_integer_hex*('int_type', 'field_name', 'expr') |
| 37 | #define *ctf_integer_network*('int_type', 'field_name', 'expr') |
| 38 | #define *ctf_integer_network_hex*('int_type', 'field_name', 'expr') |
| 39 | #define *ctf_integer_nowrite*('int_type', 'field_name', 'expr') |
| 40 | #define *ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr') |
| 41 | #define *ctf_sequence_nowrite*('int_type', 'field_name', 'expr', |
| 42 | 'len_type', 'len_expr') |
| 43 | #define *ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr') |
| 44 | #define *ctf_sequence_text_nowrite*(char, 'field_name', 'expr', |
| 45 | 'len_type', 'len_expr') |
| 46 | #define *ctf_string*('field_name', 'expr') |
| 47 | #define *ctf_string_nowrite*('field_name', 'expr') |
| 48 | #define *do_tracepoint*('prov_name', 't_name', ...) |
| 49 | #define *tracepoint*('prov_name', 't_name', ...) |
| 50 | #define *tracepoint_enabled*('prov_name', 't_name') |
| 51 | |
| 52 | Link with `-llttng-ust -ldl`, following this man page. |
| 53 | |
| 54 | |
| 55 | DESCRIPTION |
| 56 | ----------- |
| 57 | The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open |
| 58 | source software package used for correlated tracing of the Linux kernel, |
| 59 | user applications, and user libraries. |
| 60 | |
| 61 | LTTng-UST is the user space tracing component of the LTTng project. It |
| 62 | is a port to user space of the low-overhead tracing capabilities of the |
| 63 | LTTng Linux kernel tracer. The `liblttng-ust` library is used to trace |
| 64 | user applications and libraries. |
| 65 | |
| 66 | NOTE: This man page is about the `liblttng-ust` library. The LTTng-UST |
| 67 | project also provides Java and Python packages to trace applications |
| 68 | written in those languages. How to instrument and trace Java and Python |
| 69 | applications is documented in |
| 70 | http://lttng.org/docs/[the online LTTng documentation]. |
| 71 | |
| 72 | There are three ways to use `liblttng-ust`: |
| 73 | |
| 74 | * Using the man:tracef(3) API, which is similar to man:printf(3). |
| 75 | * Using the man:tracelog(3) API, which is man:tracef(3) with |
| 76 | a log level parameter. |
| 77 | * Defining your own tracepoints. See the |
| 78 | <<creating-tp,Creating a tracepoint provider>> section below. |
| 79 | |
| 80 | |
| 81 | [[creating-tp]] |
| 82 | Creating a tracepoint provider |
| 83 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 84 | Creating a tracepoint provider is the first step of using |
| 85 | `liblttng-ust`. The next steps are: |
| 86 | |
| 87 | * <<tracepoint,Instrumenting your application with `tracepoint()` calls>> |
| 88 | * Building your application with LTTng-UST support, either |
| 89 | <<build-static,statically>> or <<build-dynamic,dynamically>>. |
| 90 | |
| 91 | A *tracepoint provider* is a compiled object containing the event |
| 92 | probes corresponding to your custom tracepoint definitions. A tracepoint |
| 93 | provider contains the code to get the size of an event and to serialize |
| 94 | it, amongst other things. |
| 95 | |
| 96 | To create a tracepoint provider, start with the following |
| 97 | _tracepoint provider header_ template: |
| 98 | |
| 99 | ------------------------------------------------------------------------ |
| 100 | #undef TRACEPOINT_PROVIDER |
| 101 | #define TRACEPOINT_PROVIDER my_provider |
| 102 | |
| 103 | #undef TRACEPOINT_INCLUDE |
| 104 | #define TRACEPOINT_INCLUDE "./tp.h" |
| 105 | |
| 106 | #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ) |
| 107 | #define _TP_H |
| 108 | |
| 109 | #include <lttng/tracepoint.h> |
| 110 | |
| 111 | /* |
| 112 | * TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(), |
| 113 | * TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(), |
| 114 | * and `TRACEPOINT_ENUM()` are used here. |
| 115 | */ |
| 116 | |
| 117 | #endif /* _TP_H */ |
| 118 | |
| 119 | #include <lttng/tracepoint-event.h> |
| 120 | ------------------------------------------------------------------------ |
| 121 | |
| 122 | In this template, the tracepoint provider is named `my_provider` |
| 123 | (`TRACEPOINT_PROVIDER` definition). The file needs to bear the |
| 124 | name of the `TRACEPOINT_INCLUDE` definition (`tp.h` in this case). |
| 125 | Between `#include <lttng/tracepoint.h>` and `#endif` go |
| 126 | the invocations of the <<tracepoint-event,`TRACEPOINT_EVENT()`>>, |
| 127 | <<tracepoint-event-class,`TRACEPOINT_EVENT_CLASS()`>>, |
| 128 | <<tracepoint-event-class,`TRACEPOINT_EVENT_INSTANCE()`>>, |
| 129 | <<tracepoint-loglevel,`TRACEPOINT_LOGLEVEL()`>>, and |
| 130 | <<tracepoint-enum,`TRACEPOINT_ENUM()`>> macros. |
| 131 | |
| 132 | NOTE: You can avoid writing the prologue and epilogue boilerplate in the |
| 133 | template file above by using the man:lttng-gen-tp(1) tool shipped with |
| 134 | LTTng-UST. |
| 135 | |
| 136 | The tracepoint provider header file needs to be included in a source |
| 137 | file which looks like this: |
| 138 | |
| 139 | ------------------------------------------------------------------------ |
| 140 | #define TRACEPOINT_CREATE_PROBES |
| 141 | |
| 142 | #include "tp.h" |
| 143 | ------------------------------------------------------------------------ |
| 144 | |
| 145 | Together, those two files (let's call them `tp.h` and `tp.c`) form the |
| 146 | tracepoint provider sources, ready to be compiled. |
| 147 | |
| 148 | You can create multiple tracepoint providers to be used in a single |
| 149 | application, but each one must have its own header file. |
| 150 | |
| 151 | The <<tracepoint-event,`TRACEPOINT_EVENT()` usage>> section below |
| 152 | shows how to use the `TRACEPOINT_EVENT()` macro to define the actual |
| 153 | tracepoints in the tracepoint provider header file. |
| 154 | |
| 155 | See the <<example,EXAMPLE>> section below for a complete example. |
| 156 | |
| 157 | |
| 158 | [[tracepoint-event]] |
| 159 | `TRACEPOINT_EVENT()` usage |
| 160 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 161 | The `TRACEPOINT_EVENT()` macro is used in a template provider |
| 162 | header file (see the <<creating-tp,Creating a tracepoint provider>> |
| 163 | section above) to define LTTng-UST tracepoints. |
| 164 | |
| 165 | The `TRACEPOINT_EVENT()` usage template is as follows: |
| 166 | |
| 167 | ------------------------------------------------------------------------ |
| 168 | TRACEPOINT_EVENT( |
| 169 | /* Tracepoint provider name */ |
| 170 | my_provider, |
| 171 | |
| 172 | /* Tracepoint/event name */ |
| 173 | my_tracepoint, |
| 174 | |
| 175 | /* List of tracepoint arguments (input) */ |
| 176 | TP_ARGS( |
| 177 | ... |
| 178 | ), |
| 179 | |
| 180 | /* List of fields of eventual event (output) */ |
| 181 | TP_FIELDS( |
| 182 | ... |
| 183 | ) |
| 184 | ) |
| 185 | ------------------------------------------------------------------------ |
| 186 | |
| 187 | The `TP_ARGS()` macro contains the input arguments of the tracepoint. |
| 188 | Those arguments can be used in the argument expressions of the output |
| 189 | fields defined in `TP_FIELDS()`. |
| 190 | |
| 191 | The format of the `TP_ARGS()` parameters is: C type, then argument name; |
| 192 | repeat as needed, up to ten times. For example: |
| 193 | |
| 194 | ------------------------------------------------------------------------ |
| 195 | TP_ARGS( |
| 196 | int, my_int, |
| 197 | const char *, my_string, |
| 198 | FILE *, my_file, |
| 199 | double, my_float, |
| 200 | struct my_data *, my_data |
| 201 | ) |
| 202 | ------------------------------------------------------------------------ |
| 203 | |
| 204 | The `TP_FIELDS()` macro contains the output fields of the tracepoint, |
| 205 | that is, the actual data that can be recorded in the payload of an |
| 206 | event emitted by this tracepoint. |
| 207 | |
| 208 | The `TP_FIELDS()` macro contains a list of `ctf_*()` macros |
| 209 | :not: separated by commas. The available macros are documented in the |
| 210 | <<ctf-macros,Available `ctf_*()` field type macros>> section below. |
| 211 | |
| 212 | |
| 213 | [[ctf-macros]] |
| 214 | Available `ctf_*()` field type macros |
| 215 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 216 | This section documents the available `ctf_*()` macros that can be |
| 217 | inserted in the `TP_FIELDS()` macro of the |
| 218 | <<tracepoint-event,`TRACEPOINT_EVENT()` macro>>. |
| 219 | |
| 220 | Standard integer, displayed in base 10: |
| 221 | |
| 222 | [verse] |
| 223 | *ctf_integer*('int_type', 'field_name', 'expr') |
| 224 | *ctf_integer_nowrite*('int_type', 'field_name', 'expr') |
| 225 | |
| 226 | Standard integer, displayed in base 16: |
| 227 | |
| 228 | [verse] |
| 229 | *ctf_integer_hex*('int_type', 'field_name', 'expr') |
| 230 | |
| 231 | Integer in network byte order (big endian), displayed in base 10: |
| 232 | |
| 233 | [verse] |
| 234 | *ctf_integer_network*('int_type', 'field_name', 'expr') |
| 235 | |
| 236 | Integer in network byte order, displayed in base 16: |
| 237 | |
| 238 | [verse] |
| 239 | *ctf_integer_network_hex*('int_type', 'field_name', 'expr') |
| 240 | |
| 241 | Floating point number: |
| 242 | |
| 243 | [verse] |
| 244 | *ctf_float*('float_type', 'field_name', 'expr') |
| 245 | *ctf_float_nowrite*('float_type', 'field_name', 'expr') |
| 246 | |
| 247 | Null-terminated string: |
| 248 | |
| 249 | [verse] |
| 250 | *ctf_string*('field_name', 'expr') |
| 251 | *ctf_string_nowrite*('field_name', 'expr') |
| 252 | |
| 253 | Statically-sized array of integers: |
| 254 | |
| 255 | [verse] |
| 256 | *ctf_array*('int_type', 'field_name', 'expr', 'count') |
| 257 | *ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count') |
| 258 | |
| 259 | Statically-sized array, printed as text; no need to be null-terminated: |
| 260 | |
| 261 | [verse] |
| 262 | *ctf_array_text*(char, 'field_name', 'expr', 'count') |
| 263 | *ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count') |
| 264 | |
| 265 | Dynamically-sized array of integers: |
| 266 | |
| 267 | [verse] |
| 268 | *ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr') |
| 269 | *ctf_sequence_nowrite*('int_type', 'field_name', 'expr', 'len_type', 'len_expr') |
| 270 | |
| 271 | Dynamically-sized array, displayed as text; no need to be null-terminated: |
| 272 | |
| 273 | [verse] |
| 274 | *ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr') |
| 275 | *ctf_sequence_text_nowrite*(char, 'field_name', 'expr', 'len_type', 'len_expr') |
| 276 | |
| 277 | Enumeration. The enumeration field must be defined before using this |
| 278 | macro with the `TRACEPOINT_ENUM()` macro. See the |
| 279 | <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more |
| 280 | information. |
| 281 | |
| 282 | [verse] |
| 283 | *ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr') |
| 284 | *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr') |
| 285 | |
| 286 | The parameters are: |
| 287 | |
| 288 | 'int_type':: |
| 289 | Integer C type. The size of this type determines the size of the |
| 290 | integer/enumeration field. |
| 291 | |
| 292 | 'float_type':: |
| 293 | Float C type (`float` or `double`). The size of this type determines |
| 294 | the size of the floating point number field. |
| 295 | |
| 296 | 'field_name':: |
| 297 | Event field name (C identifier syntax, :not: a literal string). |
| 298 | |
| 299 | 'expr':: |
| 300 | C expression resulting in the field's value. This expression can |
| 301 | use one or more arguments passed to the tracepoint. The arguments |
| 302 | of a given tracepoint are defined in the `TP_ARGS()` macro (see |
| 303 | the <<creating-tp,Creating a tracepoint provider>> section above). |
| 304 | |
| 305 | 'count':: |
| 306 | Number of elements in array/sequence. This must be known at |
| 307 | compile time. |
| 308 | |
| 309 | 'len_type':: |
| 310 | Unsigned integer C type of sequence's length. |
| 311 | |
| 312 | 'len_expr':: |
| 313 | C expression resulting in the sequence's length. This expression |
| 314 | can use one or more arguments passed to the tracepoint. |
| 315 | |
| 316 | 'prov_name':: |
| 317 | Tracepoint provider name. This must be the same as the tracepoint |
| 318 | provider name used in a previous field definition. |
| 319 | |
| 320 | 'enum_name':: |
| 321 | Name of an enumeration field previously defined with the |
| 322 | `TRACEPOINT_ENUM()` macro. See the |
| 323 | <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more |
| 324 | information. |
| 325 | |
| 326 | The `_nowrite` versions omit themselves from the recorded trace, but are |
| 327 | otherwise identical. Their primary purpose is to make some of the |
| 328 | event context available to the event filters without having to commit |
| 329 | the data to sub-buffers. See man:lttng-enable-event(1) to learn more |
| 330 | about dynamic event filtering. |
| 331 | |
| 332 | See the <<example,EXAMPLE>> section below for a complete example. |
| 333 | |
| 334 | |
| 335 | [[tracepoint-enum]] |
| 336 | `TRACEPOINT_ENUM()` usage |
| 337 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 338 | An enumeration field is a list of mappings between an integers, or a |
| 339 | range of integers, and strings (sometimes called _labels_ or |
| 340 | _enumerators_). Enumeration fields can be used to have a more compact |
| 341 | trace when the possible values for a field are limited. |
| 342 | |
| 343 | An enumeration field is defined with the `TRACEPOINT_ENUM()` macro: |
| 344 | |
| 345 | ------------------------------------------------------------------------ |
| 346 | TRACEPOINT_ENUM( |
| 347 | /* Tracepoint provider name */ |
| 348 | my_provider, |
| 349 | |
| 350 | /* Enumeration name (unique in the whole tracepoint provider) */ |
| 351 | my_enum, |
| 352 | |
| 353 | /* Enumeration mappings */ |
| 354 | TP_ENUM_VALUES( |
| 355 | ... |
| 356 | ) |
| 357 | ) |
| 358 | ------------------------------------------------------------------------ |
| 359 | |
| 360 | `TP_ENUM_VALUES()` contains a list of enumeration mappings, :not: |
| 361 | separated by commas. Two macros can be used in the `TP_ENUM_VALUES()`: |
| 362 | `ctf_enum_value()` and `ctf_enum_range()`. |
| 363 | |
| 364 | `ctf_enum_value()` is a single value mapping: |
| 365 | |
| 366 | [verse] |
| 367 | *ctf_enum_value*('label', 'value') |
| 368 | |
| 369 | This macro maps the given 'label' string to the value 'value'. |
| 370 | |
| 371 | `ctf_enum_range()` is a range mapping: |
| 372 | |
| 373 | [verse] |
| 374 | *ctf_enum_range*('label', 'start', 'end') |
| 375 | |
| 376 | This macro maps the given 'label' string to the range of integers from |
| 377 | 'start' to 'end', inclusively. Range mappings may overlap, but the |
| 378 | behaviour is implementation-defined: each trace reader handles |
| 379 | overlapping ranges as it wishes. |
| 380 | |
| 381 | See the <<example,EXAMPLE>> section below for a complete example. |
| 382 | |
| 383 | |
| 384 | [[tracepoint-event-class]] |
| 385 | `TRACEPOINT_EVENT_CLASS()` usage |
| 386 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 387 | A *tracepoint class* is a class of tracepoints sharing the |
| 388 | same field types and names. A tracepoint instance is one instance of |
| 389 | such a declared tracepoint class, with its own event name. |
| 390 | |
| 391 | LTTng-UST creates one event serialization function per tracepoint |
| 392 | class. Using `TRACEPOINT_EVENT()` creates one tracepoint class per |
| 393 | tracepoint definition, whereas using `TRACEPOINT_EVENT_CLASS()` and |
| 394 | `TRACEPOINT_EVENT_INSTANCE()` creates one tracepoint class, and one or |
| 395 | more tracepoint instances of this class. In other words, many |
| 396 | tracepoints can reuse the same serialization code. Reusing the same |
| 397 | code, when possible, can reduce cache pollution, thus improve |
| 398 | performance. |
| 399 | |
| 400 | The `TRACEPOINT_EVENT_CLASS()` macro accepts the same parameters as |
| 401 | the `TRACEPOINT_EVENT()` macro, except that instead of an event name, |
| 402 | its second parameter is the _tracepoint class name_: |
| 403 | |
| 404 | ------------------------------------------------------------------------ |
| 405 | TRACEPOINT_EVENT_CLASS( |
| 406 | /* Tracepoint provider name */ |
| 407 | my_provider, |
| 408 | |
| 409 | /* Tracepoint class name */ |
| 410 | my_tracepoint_class, |
| 411 | |
| 412 | /* List of tracepoint arguments (input) */ |
| 413 | TP_ARGS( |
| 414 | ... |
| 415 | ), |
| 416 | |
| 417 | /* List of fields of eventual event (output) */ |
| 418 | TP_FIELDS( |
| 419 | ... |
| 420 | ) |
| 421 | ) |
| 422 | ------------------------------------------------------------------------ |
| 423 | |
| 424 | Once the tracepoint class is defined, you can create as many tracepoint |
| 425 | instances as needed: |
| 426 | |
| 427 | ------------------------------------------------------------------------- |
| 428 | TRACEPOINT_EVENT_INSTANCE( |
| 429 | /* Tracepoint provider name */ |
| 430 | my_provider, |
| 431 | |
| 432 | /* Tracepoint class name */ |
| 433 | my_tracepoint_class, |
| 434 | |
| 435 | /* Tracepoint/event name */ |
| 436 | my_tracepoint, |
| 437 | |
| 438 | /* List of tracepoint arguments (input) */ |
| 439 | TP_ARGS( |
| 440 | ... |
| 441 | ) |
| 442 | ) |
| 443 | ------------------------------------------------------------------------ |
| 444 | |
| 445 | As you can see, the `TRACEPOINT_EVENT_INSTANCE()` does not contain |
| 446 | the `TP_FIELDS()` macro, because they are defined at the |
| 447 | `TRACEPOINT_EVENT_CLASS()` level. |
| 448 | |
| 449 | See the <<example,EXAMPLE>> section below for a complete example. |
| 450 | |
| 451 | |
| 452 | [[tracepoint-loglevel]] |
| 453 | `TRACEPOINT_LOGLEVEL()` usage |
| 454 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 455 | Optionally, a *log level* can be assigned to a defined tracepoint. |
| 456 | Assigning different levels of severity to tracepoints can be useful: |
| 457 | when controlling tracing sessions, you can choose to only enable |
| 458 | events falling into a specific log level range using the |
| 459 | nloption:--loglevel and nloption:--loglevel-only options of the |
| 460 | man:lttng-enable-event(1) command. |
| 461 | |
| 462 | Log levels are assigned to tracepoints that are already defined using |
| 463 | the `TRACEPOINT_LOGLEVEL()` macro. The latter must be used after having |
| 464 | used `TRACEPOINT_EVENT()` or `TRACEPOINT_EVENT_INSTANCE()` for a given |
| 465 | tracepoint. The `TRACEPOINT_LOGLEVEL()` macro is used as follows: |
| 466 | |
| 467 | ------------------------------------------------------------------------ |
| 468 | TRACEPOINT_LOGLEVEL( |
| 469 | /* Tracepoint provider name */ |
| 470 | my_provider, |
| 471 | |
| 472 | /* Tracepoint/event name */ |
| 473 | my_tracepoint, |
| 474 | |
| 475 | /* Log level */ |
| 476 | TRACE_INFO |
| 477 | ) |
| 478 | ------------------------------------------------------------------------ |
| 479 | |
| 480 | The available log level definitions are: |
| 481 | |
| 482 | include::log-levels.txt[] |
| 483 | |
| 484 | See the <<example,EXAMPLE>> section below for a complete example. |
| 485 | |
| 486 | |
| 487 | [[tracepoint]] |
| 488 | Instrumenting your application |
| 489 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 490 | Once the tracepoint provider is created (see the |
| 491 | <<creating-tp,Creating a tracepoint provider>> section above), you can |
| 492 | instrument your application with the defined tracepoints thanks to the |
| 493 | `tracepoint()` macro: |
| 494 | |
| 495 | [verse] |
| 496 | #define *tracepoint*('prov_name', 't_name', ...) |
| 497 | |
| 498 | With: |
| 499 | |
| 500 | 'prov_name':: |
| 501 | Tracepoint provider name. |
| 502 | |
| 503 | 't_name':: |
| 504 | Tracepoint/event name. |
| 505 | |
| 506 | `...`:: |
| 507 | Tracepoint arguments, if any. |
| 508 | |
| 509 | Make sure to include the tracepoint provider header file anywhere you |
| 510 | use `tracepoint()` for this provider. |
| 511 | |
| 512 | NOTE: Even though LTTng-UST supports `tracepoint()` call site duplicates |
| 513 | having the same provider and tracepoint names, it is recommended to use |
| 514 | a provider/tracepoint name pair only once within the application source |
| 515 | code to help map events back to their call sites when analyzing the |
| 516 | trace. |
| 517 | |
| 518 | Sometimes, arguments to the tracepoint are expensive to compute (take |
| 519 | call stack, for example). To avoid the computation when the tracepoint |
| 520 | is disabled, you can use the `tracepoint_enabled()` and |
| 521 | `do_tracepoint()` macros: |
| 522 | |
| 523 | [verse] |
| 524 | #define *tracepoint_enabled*('prov_name', 't_name') |
| 525 | #define *do_tracepoint*('prov_name', 't_name', ...) |
| 526 | |
| 527 | `tracepoint_enabled()` returns a non-zero value if the tracepoint |
| 528 | named 't_name' from the provider named 'prov_name' is enabled at |
| 529 | run time. |
| 530 | |
| 531 | `do_tracepoint()` is like `tracepoint()`, except that it doesn't check |
| 532 | if the tracepoint is enabled. Using `tracepoint()` with |
| 533 | `tracepoint_enabled()` is dangerous since `tracepoint()` also contains |
| 534 | the `tracepoint_enabled()` check, thus a race condition is possible |
| 535 | in this situation: |
| 536 | |
| 537 | ------------------------------------------------------------------------ |
| 538 | if (tracepoint_enabled(my_provider, my_tracepoint)) { |
| 539 | stuff = prepare_stuff(); |
| 540 | } |
| 541 | |
| 542 | tracepoint(my_provider, my_tracepoint, stuff); |
| 543 | ------------------------------------------------------------------------ |
| 544 | |
| 545 | If the tracepoint is enabled after the condition, then `stuff` is not |
| 546 | prepared: the emitted event will either contain wrong data, or the |
| 547 | whole application could crash (segmentation fault, for example). |
| 548 | |
| 549 | NOTE: Neither `tracepoint_enabled()` nor `do_tracepoint()` have |
| 550 | a `STAP_PROBEV()` call, so if you need it, you should emit this call |
| 551 | yourself. |
| 552 | |
| 553 | |
| 554 | [[build-static]] |
| 555 | Statically linking the tracepoint provider |
| 556 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 557 | With the static linking method, compiled tracepoint providers are copied |
| 558 | into the target application. |
| 559 | |
| 560 | Define `TRACEPOINT_DEFINE` definition below the |
| 561 | `TRACEPOINT_CREATE_PROBES` definition in the tracepoint provider |
| 562 | source: |
| 563 | |
| 564 | ------------------------------------------------------------------------ |
| 565 | #define TRACEPOINT_CREATE_PROBES |
| 566 | #define TRACEPOINT_DEFINE |
| 567 | |
| 568 | #include "tp.h" |
| 569 | ------------------------------------------------------------------------ |
| 570 | |
| 571 | Create the tracepoint provider object file: |
| 572 | |
| 573 | [role="term"] |
| 574 | -------------- |
| 575 | cc -c -I. tp.c |
| 576 | -------------- |
| 577 | |
| 578 | NOTE: Although an application instrumented with LTTng-UST tracepoints |
| 579 | can be compiled with a C++ compiler, tracepoint probes should be |
| 580 | compiled with a C compiler. |
| 581 | |
| 582 | At this point, you _can_ archive this tracepoint provider object file, |
| 583 | possibly with other object files of your application or with other |
| 584 | tracepoint provider object files, as a static library: |
| 585 | |
| 586 | [role="term"] |
| 587 | --------------- |
| 588 | ar rc tp.a tp.o |
| 589 | --------------- |
| 590 | |
| 591 | Using a static library does have the advantage of centralising the |
| 592 | tracepoint providers objects so they can be shared between multiple |
| 593 | applications. This way, when the tracepoint provider is modified, the |
| 594 | source code changes don't have to be patched into each application's |
| 595 | source code tree. The applications need to be relinked after each |
| 596 | change, but need not to be otherwise recompiled (unless the tracepoint |
| 597 | provider's API changes). |
| 598 | |
| 599 | Then, link your application with this object file (or with the static |
| 600 | library containing it) and with `liblttng-ust` and `libdl` |
| 601 | (`libc` on a BSD system): |
| 602 | |
| 603 | [role="term"] |
| 604 | ------------------------------------- |
| 605 | cc -o app tp.o app.o -llttng-ust -ldl |
| 606 | ------------------------------------- |
| 607 | |
| 608 | |
| 609 | [[build-dynamic]] |
| 610 | Dynamically loading the tracepoint provider |
| 611 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 612 | The second approach to package the tracepoint provider is to use the |
| 613 | dynamic loader: the library and its member functions are explicitly |
| 614 | sought, loaded at run time. |
| 615 | |
| 616 | In this scenario, the tracepoint provider is compiled as a shared |
| 617 | object. |
| 618 | |
| 619 | The process to create the tracepoint provider shared object is pretty |
| 620 | much the same as the <<build-static,static linking method>>, except |
| 621 | that: |
| 622 | |
| 623 | * Since the tracepoint provider is not part of the application, |
| 624 | `TRACEPOINT_DEFINE` must be defined, for each tracepoint |
| 625 | provider, in exactly one source file of the |
| 626 | _application_ |
| 627 | * `TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next |
| 628 | to `TRACEPOINT_DEFINE` |
| 629 | |
| 630 | Regarding `TRACEPOINT_DEFINE` and `TRACEPOINT_PROBE_DYNAMIC_LINKAGE`, |
| 631 | the recommended practice is to use a separate C source file in your |
| 632 | application to define them, then include the tracepoint provider header |
| 633 | files afterwards. For example, as `tp-define.c`: |
| 634 | |
| 635 | ------------------------------------------------------------------------ |
| 636 | #define TRACEPOINT_DEFINE |
| 637 | #define TRACEPOINT_PROBE_DYNAMIC_LINKAGE |
| 638 | |
| 639 | #include "tp.h" |
| 640 | ------------------------------------------------------------------------ |
| 641 | |
| 642 | The tracepoint provider object file used to create the shared library is |
| 643 | built like it is using the static linking method, but with the |
| 644 | nloption:-fpic option: |
| 645 | |
| 646 | [role="term"] |
| 647 | -------------------- |
| 648 | cc -c -fpic -I. tp.c |
| 649 | -------------------- |
| 650 | |
| 651 | It is then linked as a shared library like this: |
| 652 | |
| 653 | [role="term"] |
| 654 | ------------------------------------------------------- |
| 655 | cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust |
| 656 | ------------------------------------------------------- |
| 657 | |
| 658 | This tracepoint provider shared object isn't linked with the user |
| 659 | application: it must be loaded manually. This is why the application is |
| 660 | built with no mention of this tracepoint provider, but still needs |
| 661 | libdl: |
| 662 | |
| 663 | [role="term"] |
| 664 | -------------------------------- |
| 665 | cc -o app app.o tp-define.o -ldl |
| 666 | -------------------------------- |
| 667 | |
| 668 | There are two ways to dynamically load the tracepoint provider shared |
| 669 | object: |
| 670 | |
| 671 | * Load it manually from the application using man:dlopen(3) |
| 672 | * Make the dynamic loader load it with the `LD_PRELOAD` |
| 673 | environment variable (see man:ld.so(8)) |
| 674 | |
| 675 | If the application does not dynamically load the tracepoint provider |
| 676 | shared object using one of the methods above, tracing is disabled for |
| 677 | this application, and the events are not listed in the output of |
| 678 | man:lttng-list(1). |
| 679 | |
| 680 | Note that it is not safe to use man:dlclose(3) on a tracepoint provider |
| 681 | shared object that is being actively used for tracing, due to a lack of |
| 682 | reference counting from LTTng-UST to the shared object. |
| 683 | |
| 684 | For example, statically linking a tracepoint provider to a shared object |
| 685 | which is to be dynamically loaded by an application (a plugin, for |
| 686 | example) is not safe: the shared object, which contains the tracepoint |
| 687 | provider, could be dynamically closed (man:dlclose(3)) at any time by |
| 688 | the application. |
| 689 | |
| 690 | To instrument a shared object, either: |
| 691 | |
| 692 | * Statically link the tracepoint provider to the application, or |
| 693 | * Build the tracepoint provider as a shared object (following the |
| 694 | procedure shown in this section), and preload it when tracing is |
| 695 | needed using the `LD_PRELOAD` environment variable. |
| 696 | |
| 697 | |
| 698 | Using LTTng-UST with daemons |
| 699 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 700 | Some extra care is needed when using `liblttng-ust` with daemon |
| 701 | applications that call man:fork(2), man:clone(2), or BSD's man:rfork(2) |
| 702 | without a following man:exec(3) family system call. The library |
| 703 | `liblttng-ust-fork.so` needs to be preloaded before starting the |
| 704 | application with the `LD_PRELOAD` environment variable (see |
| 705 | man:ld.so(8)). |
| 706 | |
| 707 | |
| 708 | Context information |
| 709 | ~~~~~~~~~~~~~~~~~~~ |
| 710 | Context information can be prepended by the LTTng-UST tracer before |
| 711 | each event, or before specific events. |
| 712 | |
| 713 | Context fields can be added to specific channels using |
| 714 | man:lttng-add-context(1). |
| 715 | |
| 716 | The following context fields are supported by LTTng-UST: |
| 717 | |
| 718 | `cpu_id`:: |
| 719 | CPU ID. |
| 720 | + |
| 721 | NOTE: This context field is always enabled, and it cannot be added |
| 722 | with man:lttng-add-context(1). Its main purpose is to be used for |
| 723 | dynamic event filtering. See man:lttng-enable-event(1) for more |
| 724 | information about event filtering. |
| 725 | |
| 726 | `ip`:: |
| 727 | Instruction pointer: enables recording the exact address from which |
| 728 | an event was emitted. This context field can be used to |
| 729 | reverse-lookup the source location that caused the event |
| 730 | to be emitted. |
| 731 | |
| 732 | +perf:thread:COUNTER+:: |
| 733 | perf counter named 'COUNTER'. Use `lttng add-context --list` to |
| 734 | list the available perf counters. |
| 735 | + |
| 736 | Only available on IA-32 and x86-64 architectures. |
| 737 | |
| 738 | `pthread_id`:: |
| 739 | POSIX thread identifier. Can be used on architectures where |
| 740 | `pthread_t` maps nicely to an `unsigned long` type. |
| 741 | |
| 742 | `procname`:: |
| 743 | Thread name, as set by man:exec(3) or man:prctl(2). It is |
| 744 | recommended that programs set their thread name with man:prctl(2) |
| 745 | before hitting the first tracepoint for that thread. |
| 746 | |
| 747 | `vpid`:: |
| 748 | Virtual process ID: process ID as seen from the point of view of |
| 749 | the process namespace. |
| 750 | |
| 751 | `vtid`:: |
| 752 | Virtual thread ID: thread ID as seen from the point of view of |
| 753 | the process namespace. |
| 754 | |
| 755 | |
| 756 | [[state-dump]] |
| 757 | LTTng-UST state dump |
| 758 | ~~~~~~~~~~~~~~~~~~~~ |
| 759 | If an application that uses `liblttng-ust` becomes part of a tracing |
| 760 | session, information about its currently loaded shared objects, their |
| 761 | build IDs, and their debug link informations are emitted as events |
| 762 | by the tracer. |
| 763 | |
| 764 | The following LTTng-UST state dump events exist and must be enabled |
| 765 | to record application state dumps. |
| 766 | |
| 767 | `lttng_ust_statedump:start`:: |
| 768 | Emitted when the state dump begins. |
| 769 | + |
| 770 | This event has no fields. |
| 771 | |
| 772 | `lttng_ust_statedump:end`:: |
| 773 | Emitted when the state dump ends. Once this event is emitted, it |
| 774 | is guaranteed that, for a given process, the state dump is |
| 775 | complete. |
| 776 | + |
| 777 | This event has no fields. |
| 778 | |
| 779 | `lttng_ust_statedump:bin_info`:: |
| 780 | Emitted when information about a currently loaded executable or |
| 781 | shared object is found. |
| 782 | + |
| 783 | Fields: |
| 784 | + |
| 785 | [options="header"] |
| 786 | |================================================================== |
| 787 | | Field name | Description |
| 788 | | `baddr` | Base address of loaded executable |
| 789 | | `memsz` | Size of loaded executable in memory |
| 790 | | `path` | Path to loaded executable file |
| 791 | | `is_pic` | Whether the executable is |
| 792 | position-independent code |
| 793 | |================================================================== |
| 794 | |
| 795 | `lttng_ust_statedump:build_id`:: |
| 796 | Emitted when a build ID is found in a currently loaded shared |
| 797 | library. See |
| 798 | https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files] |
| 799 | for more information about build IDs. |
| 800 | + |
| 801 | Fields: |
| 802 | + |
| 803 | [options="header"] |
| 804 | |============================================================== |
| 805 | | Field name | Description |
| 806 | | `baddr` | Base address of loaded library |
| 807 | | `build_id` | Build ID |
| 808 | |============================================================== |
| 809 | |
| 810 | `lttng_ust_statedump:debug_link`:: |
| 811 | Emitted when debug link information is found in a currently loaded |
| 812 | shared library. See |
| 813 | https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files] |
| 814 | for more information about debug links. |
| 815 | + |
| 816 | Fields: |
| 817 | + |
| 818 | [options="header"] |
| 819 | |============================================================== |
| 820 | | Field name | Description |
| 821 | | `baddr` | Base address of loaded library |
| 822 | | `crc` | Debug link file's CRC |
| 823 | | `filename` | Debug link file name |
| 824 | |============================================================== |
| 825 | |
| 826 | |
| 827 | [[example]] |
| 828 | EXAMPLE |
| 829 | ------- |
| 830 | NOTE: A few examples are available in the |
| 831 | https://github.com/lttng/lttng-ust/tree/master/doc/examples[`doc/examples`] |
| 832 | directory of LTTng-UST's source tree. |
| 833 | |
| 834 | This example shows all the features documented in the previous |
| 835 | sections. The <<build-static,static linking>> method is chosen here |
| 836 | to link the application with the tracepoint provider. |
| 837 | |
| 838 | You can compile the source files and link them together statically |
| 839 | like this: |
| 840 | |
| 841 | [role="term"] |
| 842 | ------------------------------------- |
| 843 | cc -c -I. tp.c |
| 844 | cc -c app.c |
| 845 | cc -o app tp.o app.o -llttng-ust -ldl |
| 846 | ------------------------------------- |
| 847 | |
| 848 | Using the man:lttng(1) tool, create an LTTng tracing session, enable |
| 849 | all the events of this tracepoint provider, and start tracing: |
| 850 | |
| 851 | [role="term"] |
| 852 | ---------------------------------------------- |
| 853 | lttng create my-session |
| 854 | lttng enable-event --userspace 'my_provider:*' |
| 855 | lttng start |
| 856 | ---------------------------------------------- |
| 857 | |
| 858 | You may also enable specific events: |
| 859 | |
| 860 | [role="term"] |
| 861 | ---------------------------------------------------------- |
| 862 | lttng enable-event --userspace my_provider:big_event |
| 863 | lttng enable-event --userspace my_provider:event_instance2 |
| 864 | ---------------------------------------------------------- |
| 865 | |
| 866 | Run the application: |
| 867 | |
| 868 | [role="term"] |
| 869 | -------------------- |
| 870 | ./app some arguments |
| 871 | -------------------- |
| 872 | |
| 873 | Stop the current tracing session and inspect the recorded events: |
| 874 | |
| 875 | [role="term"] |
| 876 | ---------- |
| 877 | lttng stop |
| 878 | lttng view |
| 879 | ---------- |
| 880 | |
| 881 | |
| 882 | Tracepoint provider header file |
| 883 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 884 | `tp.h`: |
| 885 | |
| 886 | ------------------------------------------------------------------------ |
| 887 | #undef TRACEPOINT_PROVIDER |
| 888 | #define TRACEPOINT_PROVIDER my_provider |
| 889 | |
| 890 | #undef TRACEPOINT_INCLUDE |
| 891 | #define TRACEPOINT_INCLUDE "./tp.h" |
| 892 | |
| 893 | #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ) |
| 894 | #define _TP_H |
| 895 | |
| 896 | #include <lttng/tracepoint.h> |
| 897 | #include <stdio.h> |
| 898 | |
| 899 | #include "app.h" |
| 900 | |
| 901 | TRACEPOINT_EVENT( |
| 902 | my_provider, |
| 903 | simple_event, |
| 904 | TP_ARGS( |
| 905 | int, my_integer_arg, |
| 906 | const char *, my_string_arg |
| 907 | ), |
| 908 | TP_FIELDS( |
| 909 | ctf_string(argc, my_string_arg) |
| 910 | ctf_integer(int, argv, my_integer_arg) |
| 911 | ) |
| 912 | ) |
| 913 | |
| 914 | TRACEPOINT_ENUM( |
| 915 | my_provider, |
| 916 | my_enum, |
| 917 | TP_ENUM_VALUES( |
| 918 | ctf_enum_value("ZERO", 0) |
| 919 | ctf_enum_value("ONE", 1) |
| 920 | ctf_enum_value("TWO", 2) |
| 921 | ctf_enum_range("A RANGE", 52, 125) |
| 922 | ctf_enum_value("ONE THOUSAND", 1000) |
| 923 | ) |
| 924 | ) |
| 925 | |
| 926 | TRACEPOINT_EVENT( |
| 927 | my_provider, |
| 928 | big_event, |
| 929 | TP_ARGS( |
| 930 | int, my_integer_arg, |
| 931 | const char *, my_string_arg, |
| 932 | FILE *, stream, |
| 933 | double, flt_arg, |
| 934 | int *, array_arg |
| 935 | ), |
| 936 | TP_FIELDS( |
| 937 | ctf_integer(int, int_field1, my_integer_arg * 2) |
| 938 | ctf_integer_hex(long int, stream_pos, ftell(stream)) |
| 939 | ctf_float(double, float_field, flt_arg) |
| 940 | ctf_string(string_field, my_string_arg) |
| 941 | ctf_array(int, array_field, array_arg, 7) |
| 942 | ctf_array_text(char, array_text_field, array_arg, 5) |
| 943 | ctf_sequence(int, seq_field, array_arg, int, |
| 944 | my_integer_arg / 10) |
| 945 | ctf_sequence_text(char, seq_text_field, array_arg, |
| 946 | int, my_integer_arg / 5) |
| 947 | ctf_enum(my_provider, my_enum, int, |
| 948 | enum_field, array_arg[1]) |
| 949 | ) |
| 950 | ) |
| 951 | |
| 952 | TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING) |
| 953 | |
| 954 | TRACEPOINT_EVENT_CLASS( |
| 955 | my_provider, |
| 956 | my_tracepoint_class, |
| 957 | TP_ARGS( |
| 958 | int, my_integer_arg, |
| 959 | struct app_struct *, app_struct_arg |
| 960 | ), |
| 961 | TP_FIELDS( |
| 962 | ctf_integer(int, a, my_integer_arg) |
| 963 | ctf_integer(unsigned long, b, app_struct_arg->b) |
| 964 | ctf_string(c, app_struct_arg->c) |
| 965 | ) |
| 966 | ) |
| 967 | |
| 968 | TRACEPOINT_EVENT_INSTANCE( |
| 969 | my_provider, |
| 970 | my_tracepoint_class, |
| 971 | event_instance1, |
| 972 | TP_ARGS( |
| 973 | int, my_integer_arg, |
| 974 | struct app_struct *, app_struct_arg |
| 975 | ) |
| 976 | ) |
| 977 | |
| 978 | TRACEPOINT_EVENT_INSTANCE( |
| 979 | my_provider, |
| 980 | my_tracepoint_class, |
| 981 | event_instance2, |
| 982 | TP_ARGS( |
| 983 | int, my_integer_arg, |
| 984 | struct app_struct *, app_struct_arg |
| 985 | ) |
| 986 | ) |
| 987 | |
| 988 | TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO) |
| 989 | |
| 990 | TRACEPOINT_EVENT_INSTANCE( |
| 991 | my_provider, |
| 992 | my_tracepoint_class, |
| 993 | event_instance3, |
| 994 | TP_ARGS( |
| 995 | int, my_integer_arg, |
| 996 | struct app_struct *, app_struct_arg |
| 997 | ) |
| 998 | ) |
| 999 | |
| 1000 | #endif /* _TP_H */ |
| 1001 | |
| 1002 | #include <lttng/tracepoint-event.h> |
| 1003 | ------------------------------------------------------------------------ |
| 1004 | |
| 1005 | |
| 1006 | Tracepoint provider source file |
| 1007 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1008 | `tp.c`: |
| 1009 | |
| 1010 | ------------------------------------------------------------------------ |
| 1011 | #define TRACEPOINT_CREATE_PROBES |
| 1012 | #define TRACEPOINT_DEFINE |
| 1013 | |
| 1014 | #include "tp.h" |
| 1015 | ------------------------------------------------------------------------ |
| 1016 | |
| 1017 | |
| 1018 | Application header file |
| 1019 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 1020 | `app.h`: |
| 1021 | |
| 1022 | ------------------------------------------------------------------------ |
| 1023 | #ifndef _APP_H |
| 1024 | #define _APP_H |
| 1025 | |
| 1026 | struct app_struct { |
| 1027 | unsigned long b; |
| 1028 | const char *c; |
| 1029 | double d; |
| 1030 | }; |
| 1031 | |
| 1032 | #endif /* _APP_H */ |
| 1033 | ------------------------------------------------------------------------ |
| 1034 | |
| 1035 | |
| 1036 | Application source file |
| 1037 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 1038 | `app.c`: |
| 1039 | |
| 1040 | ------------------------------------------------------------------------ |
| 1041 | #include <stdlib.h> |
| 1042 | #include <stdio.h> |
| 1043 | |
| 1044 | #include "tp.h" |
| 1045 | #include "app.h" |
| 1046 | |
| 1047 | static int array_of_ints[] = { |
| 1048 | 100, -35, 1, 23, 14, -6, 28, 1001, -3000, |
| 1049 | }; |
| 1050 | |
| 1051 | int main(int argc, char* argv[]) |
| 1052 | { |
| 1053 | FILE *stream; |
| 1054 | struct app_struct app_struct; |
| 1055 | |
| 1056 | tracepoint(my_provider, simple_event, argc, argv[0]); |
| 1057 | stream = fopen("/tmp/app.txt", "w"); |
| 1058 | |
| 1059 | if (!stream) { |
| 1060 | fprintf(stderr, |
| 1061 | "Error: Cannot open /tmp/app.txt for writing\n"); |
| 1062 | return EXIT_FAILURE; |
| 1063 | } |
| 1064 | |
| 1065 | if (fprintf(stream, "0123456789") != 10) { |
| 1066 | fclose(stream); |
| 1067 | fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n"); |
| 1068 | return EXIT_FAILURE; |
| 1069 | } |
| 1070 | |
| 1071 | tracepoint(my_provider, big_event, 35, "hello tracepoint", |
| 1072 | stream, -3.14, array_of_ints); |
| 1073 | fclose(stream); |
| 1074 | app_struct.b = argc; |
| 1075 | app_struct.c = "[the string]"; |
| 1076 | tracepoint(my_provider, event_instance1, 23, &app_struct); |
| 1077 | app_struct.b = argc * 5; |
| 1078 | app_struct.c = "[other string]"; |
| 1079 | tracepoint(my_provider, event_instance2, 17, &app_struct); |
| 1080 | app_struct.b = 23; |
| 1081 | app_struct.c = "nothing"; |
| 1082 | tracepoint(my_provider, event_instance3, -52, &app_struct); |
| 1083 | |
| 1084 | return EXIT_SUCCESS; |
| 1085 | } |
| 1086 | ------------------------------------------------------------------------ |
| 1087 | |
| 1088 | |
| 1089 | ENVIRONMENT VARIABLES |
| 1090 | --------------------- |
| 1091 | `LTTNG_HOME`:: |
| 1092 | Alternative user's home directory. This variable is useful when the |
| 1093 | user running the instrumented application has a non-writable home |
| 1094 | directory. |
| 1095 | + |
| 1096 | Unix sockets used for the communication between `liblttng-ust` and the |
| 1097 | LTTng session and consumer daemons (part of the LTTng-tools project) |
| 1098 | are located in a specific directory under `$LTTNG_HOME` (or `$HOME` if |
| 1099 | `$LTTNG_HOME` is not set). |
| 1100 | |
| 1101 | `LTTNG_UST_CLOCK_PLUGIN`:: |
| 1102 | Path to the shared object which acts as the clock override plugin. |
| 1103 | An example of such a plugin can be found in the LTTng-UST |
| 1104 | documentation under |
| 1105 | https://github.com/lttng/lttng-ust/tree/master/doc/examples/clock-override[`examples/clock-override`]. |
| 1106 | |
| 1107 | `LTTNG_UST_DEBUG`:: |
| 1108 | Activates `liblttng-ust`'s debug and error output if set to `1`. |
| 1109 | |
| 1110 | `LTTNG_UST_GETCPU_PLUGIN`:: |
| 1111 | Path to the shared object which acts as the `getcpu()` override |
| 1112 | plugin. An example of such a plugin can be found in the LTTng-UST |
| 1113 | documentation under |
| 1114 | https://github.com/lttng/lttng-ust/tree/master/doc/examples/getcpu-override[`examples/getcpu-override`]. |
| 1115 | |
| 1116 | `LTTNG_UST_REGISTER_TIMEOUT`:: |
| 1117 | Waiting time for the _registration done_ session daemon command |
| 1118 | before proceeding to execute the main program (milliseconds). |
| 1119 | + |
| 1120 | The value `0` means _do not wait_. The value `-1` means _wait forever_. |
| 1121 | Setting this environment variable to `0` is recommended for applications |
| 1122 | with time constraints on the process startup time. |
| 1123 | + |
| 1124 | Default: {lttng_ust_register_timeout}. |
| 1125 | |
| 1126 | `LTTNG_UST_WITHOUT_BADDR_STATEDUMP`:: |
| 1127 | Prevents `liblttng-ust` from performing a base address state dump |
| 1128 | (see the <<state-dump,LTTng-UST state dump>> section above) if |
| 1129 | set to `1`. |
| 1130 | |
| 1131 | |
| 1132 | include::common-footer.txt[] |
| 1133 | |
| 1134 | include::common-copyrights.txt[] |
| 1135 | |
| 1136 | include::common-authors.txt[] |
| 1137 | |
| 1138 | |
| 1139 | SEE ALSO |
| 1140 | -------- |
| 1141 | man:tracef(3), |
| 1142 | man:tracelog(3), |
| 1143 | man:lttng-gen-tp(1), |
| 1144 | man:lttng-ust-dl(3), |
| 1145 | man:lttng-ust-cyg-profile(3), |
| 1146 | man:lttng(1), |
| 1147 | man:lttng-enable-event(1), |
| 1148 | man:lttng-list(1), |
| 1149 | man:lttng-add-context(1), |
| 1150 | man:babeltrace(1), |
| 1151 | man:dlopen(3), |
| 1152 | man:ld.so(8) |