doc/man/lttng-ust.3.txt

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