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