doc/man/lttng-ust.3.txt

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