doc/man/lttng-ust.3.txt

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