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