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', '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 General context fields::
 759 +
 760 `cpu_id`:::
 761     CPU ID.
 762 +
 763 NOTE: This context field is always enabled, and it cannot be added
 764 with man:lttng-add-context(1). Its main purpose is to be used for
 765 dynamic event filtering. See man:lttng-enable-event(1) for more
 766 information about event filtering.
 767
 768 `ip`:::
 769     Instruction pointer: enables recording the exact address from which
 770     an event was emitted. This context field can be used to
 771     reverse-lookup the source location that caused the event
 772     to be emitted.
 773
 774 `pthread_id`:::
 775     POSIX thread identifier.
 776 +
 777 Can be used on architectures where `pthread_t` maps nicely to an
 778 `unsigned long` type.
 779
 780 Process context fields::
 781 +
 782 `procname`:::
 783     Thread name, as set by man:exec(3) or man:prctl(2). It is
 784     recommended that programs set their thread name with man:prctl(2)
 785     before hitting the first tracepoint for that thread.
 786
 787 `vpid`:::
 788     Virtual process ID: process ID as seen from the point of view of the
 789     current process ID namespace (see man:pid_namespaces(7)).
 790
 791 `vtid`:::
 792     Virtual thread ID: thread ID as seen from the point of view of the
 793     current process ID namespace (see man:pid_namespaces(7)).
 794
 795 perf context fields::
 796 +
 797 `perf:thread:COUNTER`:::
 798     perf counter named 'COUNTER'. Use `lttng add-context --list` to
 799     list the available perf counters.
 800 +
 801 Only available on IA-32 and x86-64 architectures.
 802
 803 `perf:thread:raw:rN:NAME`:::
 804     perf counter with raw ID 'N' and custom name 'NAME'. See
 805     man:lttng-add-context(1) for more details.
 806
 807 Namespace context fields (see man:namespaces(7))::
 808 +
 809 `cgroup_ns`:::
 810     Inode number of the current control group namespace (see
 811     man:cgroup_namespaces(7)) in the proc file system.
 812
 813 `ipc_ns`:::
 814     Inode number of the current IPC namespace (see
 815     man:ipc_namespaces(7)) in the proc file system.
 816
 817 `mnt_ns`:::
 818     Inode number of the current mount point namespace (see
 819     man:mount_namespaces(7)) in the proc file system.
 820
 821 `net_ns`:::
 822     Inode number of the current network namespace (see
 823     man:network_namespaces(7)) in the proc file system.
 824
 825 `pid_ns`:::
 826     Inode number of the current process ID namespace (see
 827     man:pid_namespaces(7)) in the proc file system.
 828
 829 `time_ns`:::
 830     Inode number of the current clock namespace (see
 831     man:time_namespaces(7)) in the proc file system.
 832
 833 `user_ns`:::
 834     Inode number of the current user namespace (see
 835     man:user_namespaces(7)) in the proc file system.
 836
 837 `uts_ns`:::
 838     Inode number of the current UTS namespace (see
 839     man:uts_namespaces(7)) in the proc file system.
 840
 841 Credential context fields (see man:credentials(7))::
 842 +
 843 `vuid`:::
 844     Virtual real user ID: real user ID as seen from the point of view of
 845     the current user namespace (see man:user_namespaces(7)).
 846
 847 `vgid`:::
 848     Virtual real group ID: real group ID as seen from the point of view
 849     of the current user namespace (see man:user_namespaces(7)).
 850
 851 `veuid`:::
 852     Virtual effective user ID: effective user ID as seen from the point
 853     of view of the current user namespace (see man:user_namespaces(7)).
 854
 855 `vegid`:::
 856     Virtual effective group ID: effective group ID as seen from the
 857     point of view of the current user namespace (see
 858     man:user_namespaces(7)).
 859
 860 `vsuid`:::
 861     Virtual saved set-user ID: saved set-user ID as seen from the point
 862     of view of the current user namespace (see man:user_namespaces(7)).
 863
 864 `vsgid`:::
 865     Virtual saved set-group ID: saved set-group ID as seen from the
 866     point of view of the current user namespace (see
 867     man:user_namespaces(7)).
 868
 869
 870 [[state-dump]]
 871 LTTng-UST state dump
 872 ~~~~~~~~~~~~~~~~~~~~
 873 If an application that uses `liblttng-ust` becomes part of a tracing
 874 session, information about its currently loaded shared objects, their
 875 build IDs, and their debug link information are emitted as events
 876 by the tracer.
 877
 878 The following LTTng-UST state dump events exist and must be enabled
 879 to record application state dumps. Note that, during the state dump
 880 phase, LTTng-UST can also emit _shared library load/unload_ events
 881 (see <<ust-lib,Shared library load/unload tracking>> below).
 882
 883 `lttng_ust_statedump:start`::
 884     Emitted when the state dump begins.
 885 +
 886 This event has no fields.
 887
 888 `lttng_ust_statedump:end`::
 889     Emitted when the state dump ends. Once this event is emitted, it
 890     is guaranteed that, for a given process, the state dump is
 891     complete.
 892 +
 893 This event has no fields.
 894
 895 `lttng_ust_statedump:bin_info`::
 896     Emitted when information about a currently loaded executable or
 897     shared object is found.
 898 +
 899 Fields:
 900 +
 901 [options="header"]
 902 |===
 903 |Field name |Description
 904
 905 |`baddr`
 906 |Base address of loaded executable.
 907
 908 |`memsz`
 909 |Size of loaded executable in memory.
 910
 911 |`path`
 912 |Path to loaded executable file.
 913
 914 |`is_pic`
 915 |Whether or not the executable is position-independent code.
 916
 917 |`has_build_id`
 918 |Whether or not the executable has a build ID. If this field is 1, you
 919 can expect that an `lttng_ust_statedump:build_id` event record follows
 920 this one (not necessarily immediately after).
 921
 922 |`has_debug_link`
 923 |Whether or not the executable has debug link information. If this field
 924 is 1, you can expect that an `lttng_ust_statedump:debug_link` event
 925 record follows this one (not necessarily immediately after).
 926 |===
 927
 928 `lttng_ust_statedump:build_id`::
 929     Emitted when a build ID is found in a currently loaded shared
 930     library. See
 931     https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
 932     for more information about build IDs.
 933 +
 934 Fields:
 935 +
 936 [options="header"]
 937 |===
 938 |Field name |Description
 939
 940 |`baddr`
 941 |Base address of loaded library.
 942
 943 |`build_id`
 944 |Build ID.
 945 |===
 946
 947 `lttng_ust_statedump:debug_link`::
 948     Emitted when debug link information is found in a currently loaded
 949     shared library. See
 950     https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
 951     for more information about debug links.
 952 +
 953 Fields:
 954 +
 955 [options="header"]
 956 |===
 957 |Field name |Description
 958
 959 |`baddr`
 960 |Base address of loaded library.
 961
 962 |`crc`
 963 |Debug link file's CRC.
 964
 965 |`filename`
 966 |Debug link file name.
 967 |===
 968
 969 `lttng_ust_statedump:procname`::
 970     The process procname at process start.
 971 +
 972 Fields:
 973 +
 974 [options="header"]
 975 |===
 976 |Field name |Description
 977
 978 |`procname`
 979 |The process name.
 980
 981 |===
 982
 983
 984 [[ust-lib]]
 985 Shared library load/unload tracking
 986 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 987 The <<state-dump,LTTng-UST state dump>> and the LTTng-UST helper library
 988 to instrument the dynamic linker (see man:liblttng-ust-dl(3)) can emit
 989 **shared library load/unload tracking** events.
 990
 991 The following shared library load/unload tracking events exist and must
 992 be enabled to track the loading and unloading of shared libraries:
 993
 994 `lttng_ust_lib:load`::
 995     Emitted when a shared library (shared object) is loaded.
 996 +
 997 Fields:
 998 +
 999 [options="header"]
1000 |===
1001 |Field name |Description
1002
1003 |`baddr`
1004 |Base address of loaded library.
1005
1006 |`memsz`
1007 |Size of loaded library in memory.
1008
1009 |`path`
1010 |Path to loaded library file.
1011
1012 |`has_build_id`
1013 |Whether or not the library has a build ID. If this field is 1, you
1014 can expect that an `lttng_ust_lib:build_id` event record follows
1015 this one (not necessarily immediately after).
1016
1017 |`has_debug_link`
1018 |Whether or not the library has debug link information. If this field
1019 is 1, you can expect that an `lttng_ust_lib:debug_link` event
1020 record follows this one (not necessarily immediately after).
1021 |===
1022
1023 `lttng_ust_lib:unload`::
1024     Emitted when a shared library (shared object) is unloaded.
1025 +
1026 Fields:
1027 +
1028 [options="header"]
1029 |===
1030 |Field name |Description
1031
1032 |`baddr`
1033 |Base address of unloaded library.
1034 |===
1035
1036 `lttng_ust_lib:build_id`::
1037     Emitted when a build ID is found in a loaded shared library (shared
1038     object). See
1039     https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1040     for more information about build IDs.
1041 +
1042 Fields:
1043 +
1044 [options="header"]
1045 |===
1046 |Field name |Description
1047
1048 |`baddr`
1049 |Base address of loaded library.
1050
1051 |`build_id`
1052 |Build ID.
1053 |===
1054
1055 `lttng_ust_lib:debug_link`::
1056     Emitted when debug link information is found in a loaded
1057     shared library (shared object). See
1058     https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1059     for more information about debug links.
1060 +
1061 Fields:
1062 +
1063 [options="header"]
1064 |===
1065 |Field name |Description
1066
1067 |`baddr`
1068 |Base address of loaded library.
1069
1070 |`crc`
1071 |Debug link file's CRC.
1072
1073 |`filename`
1074 |Debug link file name.
1075 |===
1076
1077
1078 Detect if LTTng-UST is loaded
1079 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1080 To detect if `liblttng-ust` is loaded from an application:
1081
1082 . Define the `lttng_ust_loaded` weak symbol globally:
1083 +
1084 ------------------------------------------------------------------------
1085 int lttng_ust_loaded __attribute__((weak));
1086 ------------------------------------------------------------------------
1087 +
1088 This weak symbol is set by the constructor of `liblttng-ust`.
1089
1090 . Test `lttng_ust_loaded` where needed:
1091 +
1092 ------------------------------------------------------------------------
1093 /* ... */
1094
1095 if (lttng_ust_loaded) {
1096     /* LTTng-UST is loaded */
1097 } else {
1098     /* LTTng-UST is NOT loaded */
1099 }
1100
1101 /* ... */
1102 ------------------------------------------------------------------------
1103
1104
1105 [[example]]
1106 EXAMPLE
1107 -------
1108 NOTE: A few examples are available in the
1109 https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples[`doc/examples`]
1110 directory of LTTng-UST's source tree.
1111
1112 This example shows all the features documented in the previous
1113 sections. The <<build-static,static linking>> method is chosen here
1114 to link the application with the tracepoint provider.
1115
1116 You can compile the source files and link them together statically
1117 like this:
1118
1119 [role="term"]
1120 ----
1121 $ cc -c -I. tp.c
1122 $ cc -c app.c
1123 $ cc -o app tp.o app.o -llttng-ust -ldl
1124 ----
1125
1126 Using the man:lttng(1) tool, create an LTTng tracing session, enable
1127 all the events of this tracepoint provider, and start tracing:
1128
1129 [role="term"]
1130 ----
1131 $ lttng create my-session
1132 $ lttng enable-event --userspace 'my_provider:*'
1133 $ lttng start
1134 ----
1135
1136 You may also enable specific events:
1137
1138 [role="term"]
1139 ----
1140 $ lttng enable-event --userspace my_provider:big_event
1141 $ lttng enable-event --userspace my_provider:event_instance2
1142 ----
1143
1144 Run the application:
1145
1146 [role="term"]
1147 ----
1148 $ ./app some arguments
1149 ----
1150
1151 Stop the current tracing session and inspect the recorded events:
1152
1153 [role="term"]
1154 ----
1155 $ lttng stop
1156 $ lttng view
1157 ----
1158
1159
1160 Tracepoint provider header file
1161 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1162 `tp.h`:
1163
1164 ------------------------------------------------------------------------
1165 #undef TRACEPOINT_PROVIDER
1166 #define TRACEPOINT_PROVIDER my_provider
1167
1168 #undef TRACEPOINT_INCLUDE
1169 #define TRACEPOINT_INCLUDE "./tp.h"
1170
1171 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
1172 #define _TP_H
1173
1174 #include <lttng/tracepoint.h>
1175 #include <stdio.h>
1176
1177 #include "app.h"
1178
1179 TRACEPOINT_EVENT(
1180     my_provider,
1181     simple_event,
1182     TP_ARGS(
1183         int, my_integer_arg,
1184         const char *, my_string_arg
1185     ),
1186     TP_FIELDS(
1187         ctf_string(argc, my_string_arg)
1188         ctf_integer(int, argv, my_integer_arg)
1189     )
1190 )
1191
1192 TRACEPOINT_ENUM(
1193     my_provider,
1194     my_enum,
1195     TP_ENUM_VALUES(
1196         ctf_enum_value("ZERO", 0)
1197         ctf_enum_value("ONE", 1)
1198         ctf_enum_value("TWO", 2)
1199         ctf_enum_range("A RANGE", 52, 125)
1200         ctf_enum_value("ONE THOUSAND", 1000)
1201     )
1202 )
1203
1204 TRACEPOINT_EVENT(
1205     my_provider,
1206     big_event,
1207     TP_ARGS(
1208         int, my_integer_arg,
1209         const char *, my_string_arg,
1210         FILE *, stream,
1211         double, flt_arg,
1212         int *, array_arg
1213     ),
1214     TP_FIELDS(
1215         ctf_integer(int, int_field1, my_integer_arg * 2)
1216         ctf_integer_hex(long int, stream_pos, ftell(stream))
1217         ctf_float(double, float_field, flt_arg)
1218         ctf_string(string_field, my_string_arg)
1219         ctf_array(int, array_field, array_arg, 7)
1220         ctf_array_text(char, array_text_field, array_arg, 5)
1221         ctf_sequence(int, seq_field, array_arg, int,
1222                      my_integer_arg / 10)
1223         ctf_sequence_text(char, seq_text_field, array_arg,
1224                           int, my_integer_arg / 5)
1225         ctf_enum(my_provider, my_enum, int,
1226                  enum_field, array_arg[1])
1227     )
1228 )
1229
1230 TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING)
1231
1232 TRACEPOINT_EVENT_CLASS(
1233     my_provider,
1234     my_tracepoint_class,
1235     TP_ARGS(
1236         int, my_integer_arg,
1237         struct app_struct *, app_struct_arg
1238     ),
1239     TP_FIELDS(
1240         ctf_integer(int, a, my_integer_arg)
1241         ctf_integer(unsigned long, b, app_struct_arg->b)
1242         ctf_string(c, app_struct_arg->c)
1243     )
1244 )
1245
1246 TRACEPOINT_EVENT_INSTANCE(
1247     my_provider,
1248     my_tracepoint_class,
1249     event_instance1,
1250     TP_ARGS(
1251         int, my_integer_arg,
1252         struct app_struct *, app_struct_arg
1253     )
1254 )
1255
1256 TRACEPOINT_EVENT_INSTANCE(
1257     my_provider,
1258     my_tracepoint_class,
1259     event_instance2,
1260     TP_ARGS(
1261         int, my_integer_arg,
1262         struct app_struct *, app_struct_arg
1263     )
1264 )
1265
1266 TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO)
1267
1268 TRACEPOINT_EVENT_INSTANCE(
1269     my_provider,
1270     my_tracepoint_class,
1271     event_instance3,
1272     TP_ARGS(
1273         int, my_integer_arg,
1274         struct app_struct *, app_struct_arg
1275     )
1276 )
1277
1278 #endif /* _TP_H */
1279
1280 #include <lttng/tracepoint-event.h>
1281 ------------------------------------------------------------------------
1282
1283
1284 Tracepoint provider source file
1285 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1286 `tp.c`:
1287
1288 ------------------------------------------------------------------------
1289 #define TRACEPOINT_CREATE_PROBES
1290 #define TRACEPOINT_DEFINE
1291
1292 #include "tp.h"
1293 ------------------------------------------------------------------------
1294
1295
1296 Application header file
1297 ~~~~~~~~~~~~~~~~~~~~~~~
1298 `app.h`:
1299
1300 ------------------------------------------------------------------------
1301 #ifndef _APP_H
1302 #define _APP_H
1303
1304 struct app_struct {
1305     unsigned long b;
1306     const char *c;
1307     double d;
1308 };
1309
1310 #endif /* _APP_H */
1311 ------------------------------------------------------------------------
1312
1313
1314 Application source file
1315 ~~~~~~~~~~~~~~~~~~~~~~~
1316 `app.c`:
1317
1318 ------------------------------------------------------------------------
1319 #include <stdlib.h>
1320 #include <stdio.h>
1321
1322 #include "tp.h"
1323 #include "app.h"
1324
1325 static int array_of_ints[] = {
1326     100, -35, 1, 23, 14, -6, 28, 1001, -3000,
1327 };
1328
1329 int main(int argc, char* argv[])
1330 {
1331     FILE *stream;
1332     struct app_struct app_struct;
1333
1334     tracepoint(my_provider, simple_event, argc, argv[0]);
1335     stream = fopen("/tmp/app.txt", "w");
1336
1337     if (!stream) {
1338         fprintf(stderr,
1339                 "Error: Cannot open /tmp/app.txt for writing\n");
1340         return EXIT_FAILURE;
1341     }
1342
1343     if (fprintf(stream, "0123456789") != 10) {
1344         fclose(stream);
1345         fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
1346         return EXIT_FAILURE;
1347     }
1348
1349     tracepoint(my_provider, big_event, 35, "hello tracepoint",
1350                stream, -3.14, array_of_ints);
1351     fclose(stream);
1352     app_struct.b = argc;
1353     app_struct.c = "[the string]";
1354     tracepoint(my_provider, event_instance1, 23, &app_struct);
1355     app_struct.b = argc * 5;
1356     app_struct.c = "[other string]";
1357     tracepoint(my_provider, event_instance2, 17, &app_struct);
1358     app_struct.b = 23;
1359     app_struct.c = "nothing";
1360     tracepoint(my_provider, event_instance3, -52, &app_struct);
1361
1362     return EXIT_SUCCESS;
1363 }
1364 ------------------------------------------------------------------------
1365
1366
1367 ENVIRONMENT VARIABLES
1368 ---------------------
1369 `LTTNG_HOME`::
1370     Alternative user's home directory. This variable is useful when the
1371     user running the instrumented application has a non-writable home
1372     directory.
1373 +
1374 Unix sockets used for the communication between `liblttng-ust` and the
1375 LTTng session and consumer daemons (part of the LTTng-tools project)
1376 are located in a specific directory under `$LTTNG_HOME` (or `$HOME` if
1377 `$LTTNG_HOME` is not set).
1378
1379 `LTTNG_UST_ALLOW_BLOCKING`::
1380     If set, allow the application to retry event tracing when there's
1381     no space left for the event record in the sub-buffer, therefore
1382     effectively blocking the application until space is made available
1383     or the configured timeout is reached.
1384 +
1385 To allow an application to block during tracing, you also need to
1386 specify a blocking timeout when you create a channel with the
1387 nloption:--blocking-timeout option of the man:lttng-enable-channel(1)
1388 command.
1389 +
1390 This option can be useful in workloads generating very large trace data
1391 throughput, where blocking the application is an acceptable trade-off to
1392 prevent discarding event records.
1393 +
1394 WARNING: Setting this environment variable may significantly
1395 affect application timings.
1396
1397 `LTTNG_UST_CLOCK_PLUGIN`::
1398     Path to the shared object which acts as the clock override plugin.
1399     An example of such a plugin can be found in the LTTng-UST
1400     documentation under
1401     https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/clock-override[`examples/clock-override`].
1402
1403 `LTTNG_UST_DEBUG`::
1404     If set, enable `liblttng-ust`'s debug and error output.
1405
1406 `LTTNG_UST_GETCPU_PLUGIN`::
1407     Path to the shared object which acts as the `getcpu()` override
1408     plugin. An example of such a plugin can be found in the LTTng-UST
1409     documentation under
1410     https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/getcpu-override[`examples/getcpu-override`].
1411
1412 `LTTNG_UST_REGISTER_TIMEOUT`::
1413     Waiting time for the _registration done_ session daemon command
1414     before proceeding to execute the main program (milliseconds).
1415 +
1416 The value `0` means _do not wait_. The value `-1` means _wait forever_.
1417 Setting this environment variable to `0` is recommended for applications
1418 with time constraints on the process startup time.
1419 +
1420 Default: {lttng_ust_register_timeout}.
1421
1422 `LTTNG_UST_WITHOUT_BADDR_STATEDUMP`::
1423     If set, prevents `liblttng-ust` from performing a base address state
1424     dump (see the <<state-dump,LTTng-UST state dump>> section above).
1425
1426 `LTTNG_UST_WITHOUT_PROCNAME_STATEDUMP`::
1427     If set, prevents `liblttng-ust` from performing a procname state
1428     dump (see the <<state-dump,LTTng-UST state dump>> section above).
1429
1430
1431 include::common-footer.txt[]
1432
1433 include::common-copyrights.txt[]
1434
1435 include::common-authors.txt[]
1436
1437
1438 SEE ALSO
1439 --------
1440 man:tracef(3),
1441 man:tracelog(3),
1442 man:lttng-gen-tp(1),
1443 man:lttng-ust-dl(3),
1444 man:lttng-ust-cyg-profile(3),
1445 man:lttng(1),
1446 man:lttng-enable-event(1),
1447 man:lttng-list(1),
1448 man:lttng-add-context(1),
1449 man:babeltrace(1),
1450 man:dlopen(3),
1451 man:ld.so(8)