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
 692 [[build-static]]
 693 Statically linking the tracepoint provider
 694 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 695 With the static linking method, compiled tracepoint providers are copied
 696 into the target application.
 697
 698 Define `LTTNG_UST_TRACEPOINT_DEFINE` definition below the
 699 `LTTNG_UST_TRACEPOINT_CREATE_PROBES` definition in the tracepoint
 700 provider source:
 701
 702 ------------------------------------------------------------------------
 703 #define LTTNG_UST_TRACEPOINT_CREATE_PROBES
 704 #define LTTNG_UST_TRACEPOINT_DEFINE
 705
 706 #include "tp.h"
 707 ------------------------------------------------------------------------
 708
 709 Create the tracepoint provider object file:
 710
 711 [role="term"]
 712 ----
 713 $ cc -c -I. tp.c
 714 ----
 715
 716 NOTE: Although an application instrumented with LTTng-UST tracepoints
 717 can be compiled with a $$C++$$ compiler, tracepoint probes
 718 should be compiled with a C compiler.
 719
 720 At this point, you _can_ archive this tracepoint provider object file,
 721 possibly with other object files of your application or with other
 722 tracepoint provider object files, as a static library:
 723
 724 [role="term"]
 725 ----
 726 $ ar rc tp.a tp.o
 727 ----
 728
 729 Using a static library does have the advantage of centralising the
 730 tracepoint providers objects so they can be shared between multiple
 731 applications. This way, when the tracepoint provider is modified, the
 732 source code changes don't have to be patched into each application's
 733 source code tree. The applications need to be relinked after each
 734 change, but need not to be otherwise recompiled (unless the tracepoint
 735 provider's API changes).
 736
 737 Then, link your application with this object file (or with the static
 738 library containing it) and with `liblttng-ust` and `libdl` (`libc` on a
 739 BSD system):
 740
 741 [role="term"]
 742 ----
 743 $ cc -o app tp.o app.o -llttng-ust -ldl
 744 ----
 745
 746
 747 [[build-dynamic]]
 748 Dynamically loading the tracepoint provider
 749 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 750 The second approach to package the tracepoint provider is to use the
 751 dynamic loader: the library and its member functions are explicitly
 752 sought, loaded at run time.
 753
 754 In this scenario, the tracepoint provider is compiled as a shared
 755 object.
 756
 757 The process to create the tracepoint provider shared object is pretty
 758 much the same as the <<build-static,static linking method>>, except
 759 that:
 760
 761   * Since the tracepoint provider is not part of the application,
 762     `LTTNG_UST_TRACEPOINT_DEFINE` must be defined, for each tracepoint
 763     provider, in exactly one source file of the _application_
 764   * `LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next to
 765     `LTTNG_UST_TRACEPOINT_DEFINE`
 766
 767 Regarding `LTTNG_UST_TRACEPOINT_DEFINE` and
 768 `LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE`, the recommended practice
 769 is to use a separate C source file in your application to define them,
 770 then include the tracepoint provider header files afterwards. For
 771 example, as `tp-define.c`:
 772
 773 ------------------------------------------------------------------------
 774 #define LTTNG_UST_TRACEPOINT_DEFINE
 775 #define LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE
 776
 777 #include "tp.h"
 778 ------------------------------------------------------------------------
 779
 780 The tracepoint provider object file used to create the shared library is
 781 built like it is using the static linking method, but with the
 782 nloption:-fpic option:
 783
 784 [role="term"]
 785 ----
 786 $ cc -c -fpic -I. tp.c
 787 ----
 788
 789 It is then linked as a shared library like this:
 790
 791 [role="term"]
 792 ----
 793 $ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
 794 ----
 795
 796 This tracepoint provider shared object isn't linked with the user
 797 application: it must be loaded manually. This is why the application is
 798 built with no mention of this tracepoint provider, but still needs
 799 libdl:
 800
 801 [role="term"]
 802 ----
 803 $ cc -o app app.o tp-define.o -ldl
 804 ----
 805
 806 There are two ways to dynamically load the tracepoint provider shared
 807 object:
 808
 809   * Load it manually from the application using man:dlopen(3)
 810   * Make the dynamic loader load it with the `LD_PRELOAD`
 811     environment variable (see man:ld.so(8))
 812
 813 If the application does not dynamically load the tracepoint provider
 814 shared object using one of the methods above, tracing is disabled for
 815 this application, and the events are not listed in the output of
 816 man:lttng-list(1).
 817
 818 Note that it is not safe to use man:dlclose(3) on a tracepoint provider
 819 shared object that is being actively used for tracing, due to a lack of
 820 reference counting from LTTng-UST to the shared object.
 821
 822 For example, statically linking a tracepoint provider to a shared object
 823 which is to be dynamically loaded by an application (a plugin, for
 824 example) is not safe: the shared object, which contains the tracepoint
 825 provider, could be dynamically closed (man:dlclose(3)) at any time by
 826 the application.
 827
 828 To instrument a shared object, either:
 829
 830   * Statically link the tracepoint provider to the application, or
 831   * Build the tracepoint provider as a shared object (following the
 832     procedure shown in this section), and preload it when tracing is
 833     needed using the `LD_PRELOAD` environment variable.
 834
 835
 836 Using LTTng-UST with daemons
 837 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 838 Some extra care is needed when using `liblttng-ust` with daemon
 839 applications that call man:fork(2), man:clone(2), or BSD's man:rfork(2)
 840 without a following man:exec(3) family system call. The library
 841 `liblttng-ust-fork.so` needs to be preloaded before starting the
 842 application with the `LD_PRELOAD` environment variable (see
 843 man:ld.so(8)).
 844
 845 To use `liblttng-ust` with a daemon application which closes file
 846 descriptors that were not opened by it, preload the `liblttng-ust-fd.so`
 847 library before you start the application. Typical use cases include
 848 daemons closing all file descriptors after man:fork(2), and buggy
 849 applications doing ``double-closes''.
 850
 851
 852 Context information
 853 ~~~~~~~~~~~~~~~~~~~
 854 Context information can be prepended by the LTTng-UST tracer before
 855 each event, or before specific events.
 856
 857 Context fields can be added to specific channels using
 858 man:lttng-add-context(1).
 859
 860 The following context fields are supported by LTTng-UST:
 861
 862 General context fields::
 863 +
 864 `cpu_id`:::
 865     CPU ID.
 866 +
 867 NOTE: This context field is always enabled, and it cannot be added
 868 with man:lttng-add-context(1). Its main purpose is to be used for
 869 dynamic event filtering. See man:lttng-enable-event(1) for more
 870 information about event filtering.
 871
 872 `ip`:::
 873     Instruction pointer: enables recording the exact address from which
 874     an event was emitted. This context field can be used to
 875     reverse-lookup the source location that caused the event
 876     to be emitted.
 877
 878 `pthread_id`:::
 879     POSIX thread identifier.
 880 +
 881 Can be used on architectures where `pthread_t` maps nicely to an
 882 `unsigned long` type.
 883
 884 Process context fields::
 885 +
 886 `procname`:::
 887     Thread name, as set by man:exec(3) or man:prctl(2). It is
 888     recommended that programs set their thread name with man:prctl(2)
 889     before hitting the first tracepoint for that thread.
 890
 891 `vpid`:::
 892     Virtual process ID: process ID as seen from the point of view of the
 893     current process ID namespace (see man:pid_namespaces(7)).
 894
 895 `vtid`:::
 896     Virtual thread ID: thread ID as seen from the point of view of the
 897     current process ID namespace (see man:pid_namespaces(7)).
 898
 899 perf context fields::
 900 +
 901 `perf:thread:COUNTER`:::
 902     perf counter named 'COUNTER'. Use `lttng add-context --list` to
 903     list the available perf counters.
 904 +
 905 Only available on IA-32 and x86-64 architectures.
 906
 907 `perf:thread:raw:rN:NAME`:::
 908     perf counter with raw ID 'N' and custom name 'NAME'. See
 909     man:lttng-add-context(1) for more details.
 910
 911 Namespace context fields (see man:namespaces(7))::
 912 +
 913 `cgroup_ns`:::
 914     Inode number of the current control group namespace (see
 915     man:cgroup_namespaces(7)) in the proc file system.
 916
 917 `ipc_ns`:::
 918     Inode number of the current IPC namespace (see
 919     man:ipc_namespaces(7)) in the proc file system.
 920
 921 `mnt_ns`:::
 922     Inode number of the current mount point namespace (see
 923     man:mount_namespaces(7)) in the proc file system.
 924
 925 `net_ns`:::
 926     Inode number of the current network namespace (see
 927     man:network_namespaces(7)) in the proc file system.
 928
 929 `pid_ns`:::
 930     Inode number of the current process ID namespace (see
 931     man:pid_namespaces(7)) in the proc file system.
 932
 933 `time_ns`:::
 934     Inode number of the current clock namespace (see
 935     man:time_namespaces(7)) in the proc file system.
 936
 937 `user_ns`:::
 938     Inode number of the current user namespace (see
 939     man:user_namespaces(7)) in the proc file system.
 940
 941 `uts_ns`:::
 942     Inode number of the current UTS namespace (see
 943     man:uts_namespaces(7)) in the proc file system.
 944
 945 Credential context fields (see man:credentials(7))::
 946 +
 947 `vuid`:::
 948     Virtual real user ID: real user ID as seen from the point of view of
 949     the current user namespace (see man:user_namespaces(7)).
 950
 951 `vgid`:::
 952     Virtual real group ID: real group ID as seen from the point of view
 953     of the current user namespace (see man:user_namespaces(7)).
 954
 955 `veuid`:::
 956     Virtual effective user ID: effective user ID as seen from the point
 957     of view of the current user namespace (see man:user_namespaces(7)).
 958
 959 `vegid`:::
 960     Virtual effective group ID: effective group ID as seen from the
 961     point of view of the current user namespace (see
 962     man:user_namespaces(7)).
 963
 964 `vsuid`:::
 965     Virtual saved set-user ID: saved set-user ID as seen from the point
 966     of view of the current user namespace (see man:user_namespaces(7)).
 967
 968 `vsgid`:::
 969     Virtual saved set-group ID: saved set-group ID as seen from the
 970     point of view of the current user namespace (see
 971     man:user_namespaces(7)).
 972
 973
 974 [[state-dump]]
 975 LTTng-UST state dump
 976 ~~~~~~~~~~~~~~~~~~~~
 977 If an application that uses `liblttng-ust` becomes part of a tracing
 978 session, information about its currently loaded shared objects, their
 979 build IDs, and their debug link information are emitted as events
 980 by the tracer.
 981
 982 The following LTTng-UST state dump events exist and must be enabled
 983 to record application state dumps. Note that, during the state dump
 984 phase, LTTng-UST can also emit _shared library load/unload_ events
 985 (see <<ust-lib,Shared library load/unload tracking>> below).
 986
 987 `lttng_ust_statedump:start`::
 988     Emitted when the state dump begins.
 989 +
 990 This event has no fields.
 991
 992 `lttng_ust_statedump:end`::
 993     Emitted when the state dump ends. Once this event is emitted, it
 994     is guaranteed that, for a given process, the state dump is
 995     complete.
 996 +
 997 This event has no fields.
 998
 999 `lttng_ust_statedump:bin_info`::
1000     Emitted when information about a currently loaded executable or
1001     shared object is found.
1002 +
1003 Fields:
1004 +
1005 [options="header"]
1006 |===
1007 |Field name |Description
1008
1009 |`baddr`
1010 |Base address of loaded executable.
1011
1012 |`memsz`
1013 |Size of loaded executable in memory.
1014
1015 |`path`
1016 |Path to loaded executable file.
1017
1018 |`is_pic`
1019 |Whether or not the executable is position-independent code.
1020
1021 |`has_build_id`
1022 |Whether or not the executable has a build ID. If this field is 1, you
1023 can expect that an `lttng_ust_statedump:build_id` event record follows
1024 this one (not necessarily immediately after).
1025
1026 |`has_debug_link`
1027 |Whether or not the executable has debug link information. If this field
1028 is 1, you can expect that an `lttng_ust_statedump:debug_link` event
1029 record follows this one (not necessarily immediately after).
1030 |===
1031
1032 `lttng_ust_statedump:build_id`::
1033     Emitted when a build ID is found in a currently loaded shared
1034     library. See
1035     https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1036     for more information about build IDs.
1037 +
1038 Fields:
1039 +
1040 [options="header"]
1041 |===
1042 |Field name |Description
1043
1044 |`baddr`
1045 |Base address of loaded library.
1046
1047 |`build_id`
1048 |Build ID.
1049 |===
1050
1051 `lttng_ust_statedump:debug_link`::
1052     Emitted when debug link information is found in a currently loaded
1053     shared library. See
1054     https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1055     for more information about debug links.
1056 +
1057 Fields:
1058 +
1059 [options="header"]
1060 |===
1061 |Field name |Description
1062
1063 |`baddr`
1064 |Base address of loaded library.
1065
1066 |`crc`
1067 |Debug link file's CRC.
1068
1069 |`filename`
1070 |Debug link file name.
1071 |===
1072
1073 `lttng_ust_statedump:procname`::
1074     The process procname at process start.
1075 +
1076 Fields:
1077 +
1078 [options="header"]
1079 |===
1080 |Field name |Description
1081
1082 |`procname`
1083 |The process name.
1084
1085 |===
1086
1087
1088 [[ust-lib]]
1089 Shared library load/unload tracking
1090 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1091 The <<state-dump,LTTng-UST state dump>> and the LTTng-UST helper library
1092 to instrument the dynamic linker (see man:liblttng-ust-dl(3)) can emit
1093 **shared library load/unload tracking** events.
1094
1095 The following shared library load/unload tracking events exist and must
1096 be enabled to track the loading and unloading of shared libraries:
1097
1098 `lttng_ust_lib:load`::
1099     Emitted when a shared library (shared object) is loaded.
1100 +
1101 Fields:
1102 +
1103 [options="header"]
1104 |===
1105 |Field name |Description
1106
1107 |`baddr`
1108 |Base address of loaded library.
1109
1110 |`memsz`
1111 |Size of loaded library in memory.
1112
1113 |`path`
1114 |Path to loaded library file.
1115
1116 |`has_build_id`
1117 |Whether or not the library has a build ID. If this field is 1, you
1118 can expect that an `lttng_ust_lib:build_id` event record follows
1119 this one (not necessarily immediately after).
1120
1121 |`has_debug_link`
1122 |Whether or not the library has debug link information. If this field
1123 is 1, you can expect that an `lttng_ust_lib:debug_link` event
1124 record follows this one (not necessarily immediately after).
1125 |===
1126
1127 `lttng_ust_lib:unload`::
1128     Emitted when a shared library (shared object) is unloaded.
1129 +
1130 Fields:
1131 +
1132 [options="header"]
1133 |===
1134 |Field name |Description
1135
1136 |`baddr`
1137 |Base address of unloaded library.
1138 |===
1139
1140 `lttng_ust_lib:build_id`::
1141     Emitted when a build ID is found in a loaded shared library (shared
1142     object). See
1143     https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1144     for more information about build IDs.
1145 +
1146 Fields:
1147 +
1148 [options="header"]
1149 |===
1150 |Field name |Description
1151
1152 |`baddr`
1153 |Base address of loaded library.
1154
1155 |`build_id`
1156 |Build ID.
1157 |===
1158
1159 `lttng_ust_lib:debug_link`::
1160     Emitted when debug link information is found in a loaded
1161     shared library (shared object). See
1162     https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
1163     for more information about debug links.
1164 +
1165 Fields:
1166 +
1167 [options="header"]
1168 |===
1169 |Field name |Description
1170
1171 |`baddr`
1172 |Base address of loaded library.
1173
1174 |`crc`
1175 |Debug link file's CRC.
1176
1177 |`filename`
1178 |Debug link file name.
1179 |===
1180
1181
1182 Detect if LTTng-UST is loaded
1183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1184 To detect if `liblttng-ust` is loaded from an application:
1185
1186 . Define the `lttng_ust_loaded` weak symbol globally:
1187 +
1188 ------------------------------------------------------------------------
1189 int lttng_ust_loaded __attribute__((weak));
1190 ------------------------------------------------------------------------
1191 +
1192 This weak symbol is set by the constructor of `liblttng-ust`.
1193
1194 . Test `lttng_ust_loaded` where needed:
1195 +
1196 ------------------------------------------------------------------------
1197 /* ... */
1198
1199 if (lttng_ust_loaded) {
1200     /* LTTng-UST is loaded */
1201 } else {
1202     /* LTTng-UST is NOT loaded */
1203 }
1204
1205 /* ... */
1206 ------------------------------------------------------------------------
1207
1208
1209 [[example]]
1210 EXAMPLE
1211 -------
1212 NOTE: A few examples are available in the
1213 https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples[`doc/examples`]
1214 directory of LTTng-UST's source tree.
1215
1216 This example shows all the features documented in the previous
1217 sections. The <<build-static,static linking>> method is chosen here
1218 to link the application with the tracepoint provider.
1219
1220 You can compile the source files and link them together statically
1221 like this:
1222
1223 [role="term"]
1224 ----
1225 $ cc -c -I. tp.c
1226 $ cc -c app.c
1227 $ cc -o app tp.o app.o -llttng-ust -ldl
1228 ----
1229
1230 Using the man:lttng(1) tool, create an LTTng tracing session, enable
1231 all the events of this tracepoint provider, and start tracing:
1232
1233 [role="term"]
1234 ----
1235 $ lttng create my-session
1236 $ lttng enable-event --userspace 'my_provider:*'
1237 $ lttng start
1238 ----
1239
1240 You may also enable specific events:
1241
1242 [role="term"]
1243 ----
1244 $ lttng enable-event --userspace my_provider:big_event
1245 $ lttng enable-event --userspace my_provider:event_instance2
1246 ----
1247
1248 Run the application:
1249
1250 [role="term"]
1251 ----
1252 $ ./app some arguments
1253 ----
1254
1255 Stop the current tracing session and inspect the recorded events:
1256
1257 [role="term"]
1258 ----
1259 $ lttng stop
1260 $ lttng view
1261 ----
1262
1263
1264 Tracepoint provider header file
1265 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1266 `tp.h`:
1267
1268 ------------------------------------------------------------------------
1269 #undef LTTNG_UST_TRACEPOINT_PROVIDER
1270 #define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
1271
1272 #undef LTTNG_USTTRACEPOINT_INCLUDE
1273 #define LTTNG_USTTRACEPOINT_INCLUDE "./tp.h"
1274
1275 #if !defined(_TP_H) || \
1276     defined(LTTNG_UST_TRACEPOINT_HEADER_MULTI_READ)
1277 #define _TP_H
1278
1279 #include <lttng/tracepoint.h>
1280 #include <stdio.h>
1281
1282 #include "app.h"
1283
1284 LTTNG_UST_TRACEPOINT_EVENT(
1285     my_provider,
1286     simple_event,
1287     LTTNG_UST_TP_ARGS(
1288         int, my_integer_arg,
1289         const char *, my_string_arg
1290     ),
1291     LTTNG_UST_TP_FIELDS(
1292         lttng_ust_field_string(argc, my_string_arg)
1293         lttng_ust_field_integer(int, argv, my_integer_arg)
1294     )
1295 )
1296
1297 LTTNG_UST_TRACEPOINT_ENUM(
1298     my_provider,
1299     my_enum,
1300     LTTNG_UST_TP_ENUM_VALUES(
1301         lttng_ust_field_enum_value("ZERO", 0)
1302         lttng_ust_field_enum_value("ONE", 1)
1303         lttng_ust_field_enum_value("TWO", 2)
1304         lttng_ust_field_enum_range("A RANGE", 52, 125)
1305         lttng_ust_field_enum_value("ONE THOUSAND", 1000)
1306     )
1307 )
1308
1309 LTTNG_UST_TRACEPOINT_EVENT(
1310     my_provider,
1311     big_event,
1312     LTTNG_UST_TP_ARGS(
1313         int, my_integer_arg,
1314         const char *, my_string_arg,
1315         FILE *, stream,
1316         double, flt_arg,
1317         int *, array_arg
1318     ),
1319     LTTNG_UST_TP_FIELDS(
1320         lttng_ust_field_integer(int, int_field1, my_integer_arg * 2)
1321         lttng_ust_field_integer_hex(long int, stream_pos,
1322                                     ftell(stream))
1323         lttng_ust_field_float(double, float_field, flt_arg)
1324         lttng_ust_field_string(string_field, my_string_arg)
1325         lttng_ust_field_array(int, array_field, array_arg, 7)
1326         lttng_ust_field_array_text(char, array_text_field,
1327                                    array_arg, 5)
1328         lttng_ust_field_sequence(int, seq_field, array_arg, int,
1329                                  my_integer_arg / 10)
1330         lttng_ust_field_sequence_text(char, seq_text_field,
1331                                       array_arg, int,
1332                                       my_integer_arg / 5)
1333         lttng_ust_field_enum(my_provider, my_enum, int,
1334                              enum_field, array_arg[1])
1335     )
1336 )
1337
1338 LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, big_event,
1339                               LTTNG_UST_TRACEPOINT_LOGLEVEL_WARNING)
1340
1341 LTTNG_UST_TRACEPOINT_EVENT_CLASS(
1342     my_provider,
1343     my_tracepoint_class,
1344     LTTNG_UST_TP_ARGS(
1345         int, my_integer_arg,
1346         struct app_struct *, app_struct_arg
1347     ),
1348     LTTNG_UST_TP_FIELDS(
1349         lttng_ust_field_integer(int, a, my_integer_arg)
1350         lttng_ust_field_integer(unsigned long, b, app_struct_arg->b)
1351         lttng_ust_field_string(c, app_struct_arg->c)
1352     )
1353 )
1354
1355 LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
1356     my_provider,
1357     my_tracepoint_class,
1358     my_provider,
1359     event_instance1,
1360     LTTNG_UST_TP_ARGS(
1361         int, my_integer_arg,
1362         struct app_struct *, app_struct_arg
1363     )
1364 )
1365
1366 LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
1367     my_provider,
1368     my_tracepoint_class,
1369     my_provider,
1370     event_instance2,
1371     LTTNG_UST_TP_ARGS(
1372         int, my_integer_arg,
1373         struct app_struct *, app_struct_arg
1374     )
1375 )
1376
1377 LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, event_instance2,
1378                               LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO)
1379
1380 LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
1381     my_provider,
1382     my_tracepoint_class,
1383     my_provider,
1384     event_instance3,
1385     LTTNG_UST_TP_ARGS(
1386         int, my_integer_arg,
1387         struct app_struct *, app_struct_arg
1388     )
1389 )
1390
1391 #endif /* _TP_H */
1392
1393 #include <lttng/tracepoint-event.h>
1394 ------------------------------------------------------------------------
1395
1396
1397 Tracepoint provider source file
1398 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1399 `tp.c`:
1400
1401 ------------------------------------------------------------------------
1402 #define LTTNG_UST_TRACEPOINT_CREATE_PROBES
1403 #define LTTNG_UST_TRACEPOINT_DEFINE
1404
1405 #include "tp.h"
1406 ------------------------------------------------------------------------
1407
1408
1409 Application header file
1410 ~~~~~~~~~~~~~~~~~~~~~~~
1411 `app.h`:
1412
1413 ------------------------------------------------------------------------
1414 #ifndef _APP_H
1415 #define _APP_H
1416
1417 struct app_struct {
1418     unsigned long b;
1419     const char *c;
1420     double d;
1421 };
1422
1423 #endif /* _APP_H */
1424 ------------------------------------------------------------------------
1425
1426
1427 Application source file
1428 ~~~~~~~~~~~~~~~~~~~~~~~
1429 `app.c`:
1430
1431 ------------------------------------------------------------------------
1432 #include <stdlib.h>
1433 #include <stdio.h>
1434
1435 #include "tp.h"
1436 #include "app.h"
1437
1438 static int array_of_ints[] = {
1439     100, -35, 1, 23, 14, -6, 28, 1001, -3000,
1440 };
1441
1442 int main(int argc, char* argv[])
1443 {
1444     FILE *stream;
1445     struct app_struct app_struct;
1446
1447     lttng_ust_tracepoint(my_provider, simple_event, argc, argv[0]);
1448     stream = fopen("/tmp/app.txt", "w");
1449
1450     if (!stream) {
1451         fprintf(stderr,
1452                 "Error: Cannot open /tmp/app.txt for writing\n");
1453         return EXIT_FAILURE;
1454     }
1455
1456     if (fprintf(stream, "0123456789") != 10) {
1457         fclose(stream);
1458         fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
1459         return EXIT_FAILURE;
1460     }
1461
1462     lttng_ust_tracepoint(my_provider, big_event, 35,
1463                          "hello tracepoint", stream, -3.14,
1464                          array_of_ints);
1465     fclose(stream);
1466     app_struct.b = argc;
1467     app_struct.c = "[the string]";
1468     lttng_ust_tracepoint(my_provider, event_instance1, 23,
1469                          &app_struct);
1470     app_struct.b = argc * 5;
1471     app_struct.c = "[other string]";
1472     lttng_ust_tracepoint(my_provider, event_instance2, 17,
1473                          &app_struct);
1474     app_struct.b = 23;
1475     app_struct.c = "nothing";
1476     lttng_ust_tracepoint(my_provider, event_instance3, -52,
1477                          &app_struct);
1478     return EXIT_SUCCESS;
1479 }
1480 ------------------------------------------------------------------------
1481
1482
1483 ENVIRONMENT VARIABLES
1484 ---------------------
1485 `LTTNG_HOME`::
1486     Alternative user's home directory. This variable is useful when the
1487     user running the instrumented application has a non-writable home
1488     directory.
1489 +
1490 Unix sockets used for the communication between `liblttng-ust` and the
1491 LTTng session and consumer daemons (part of the LTTng-tools project)
1492 are located in a specific directory under `$LTTNG_HOME` (or `$HOME` if
1493 `$LTTNG_HOME` is not set).
1494
1495 `LTTNG_UST_ALLOW_BLOCKING`::
1496     If set, allow the application to retry event tracing when there's
1497     no space left for the event record in the sub-buffer, therefore
1498     effectively blocking the application until space is made available
1499     or the configured timeout is reached.
1500 +
1501 To allow an application to block during tracing, you also need to
1502 specify a blocking timeout when you create a channel with the
1503 nloption:--blocking-timeout option of the man:lttng-enable-channel(1)
1504 command.
1505 +
1506 This option can be useful in workloads generating very large trace data
1507 throughput, where blocking the application is an acceptable trade-off to
1508 prevent discarding event records.
1509 +
1510 WARNING: Setting this environment variable may significantly
1511 affect application timings.
1512
1513 `LTTNG_UST_ABORT_ON_CRITICAL`::
1514     If set, abort the instrumented application on a critical error message.
1515
1516 `LTTNG_UST_CLOCK_PLUGIN`::
1517     Path to the shared object which acts as the clock override plugin.
1518     An example of such a plugin can be found in the LTTng-UST
1519     documentation under
1520     https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/clock-override[`examples/clock-override`].
1521
1522 `LTTNG_UST_DEBUG`::
1523     If set, enable `liblttng-ust`'s debug and error output.
1524
1525 `LTTNG_UST_GETCPU_PLUGIN`::
1526     Path to the shared object which acts as the `getcpu()` override
1527     plugin. An example of such a plugin can be found in the LTTng-UST
1528     documentation under
1529     https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/getcpu-override[`examples/getcpu-override`].
1530
1531 `LTTNG_UST_REGISTER_TIMEOUT`::
1532     Waiting time for the _registration done_ session daemon command
1533     before proceeding to execute the main program (milliseconds).
1534 +
1535 The value `0` means _do not wait_. The value `-1` means _wait forever_.
1536 Setting this environment variable to `0` is recommended for applications
1537 with time constraints on the process startup time.
1538 +
1539 Default: 3000.
1540
1541 `LTTNG_UST_WITHOUT_BADDR_STATEDUMP`::
1542     If set, prevents `liblttng-ust` from performing a base address state
1543     dump (see the <<state-dump,LTTng-UST state dump>> section above).
1544
1545 `LTTNG_UST_WITHOUT_PROCNAME_STATEDUMP`::
1546     If set, prevents `liblttng-ust` from performing a procname state
1547     dump (see the <<state-dump,LTTng-UST state dump>> section above).
1548
1549
1550 include::common-footer.txt[]
1551
1552 include::common-copyrights.txt[]
1553
1554 include::common-authors.txt[]
1555
1556
1557 SEE ALSO
1558 --------
1559 man:lttng_ust_tracef(3),
1560 man:lttng_ust_tracelog(3),
1561 man:lttng-gen-tp(1),
1562 man:lttng-ust-dl(3),
1563 man:lttng-ust-cyg-profile(3),
1564 man:lttng(1),
1565 man:lttng-enable-event(1),
1566 man:lttng-list(1),
1567 man:lttng-add-context(1),
1568 man:babeltrace(1),
1569 man:dlopen(3),
1570 man:ld.so(8)