doc/man/lttng-ust.3.txt

   1 lttng-ust(3)
   2 ============
   3 :object-type: library
   4
   5
   6 NAME
   7 ----
   8 lttng-ust - LTTng user space tracing
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *#include <lttng/tracepoint.h>*
  15
  16 [verse]
  17 #define *TRACEPOINT_ENUM*('prov_name', 'enum_name', 'mappings')
  18 #define *TRACEPOINT_EVENT*('prov_name', 't_name', 'args', 'fields')
  19 #define *TRACEPOINT_EVENT_CLASS*('prov_name', 'class_name',
  20                                'args', 'fields')
  21 #define *TRACEPOINT_EVENT_INSTANCE*('prov_name', 'class_name',
  22                                   't_name', 'args')
  23 #define *TRACEPOINT_LOGLEVEL*('prov_name', 't_name', 'level')
  24 #define *ctf_array*('int_type', 'field_name', 'expr', 'count')
  25 #define *ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count')
  26 #define *ctf_array_text*(char, 'field_name', 'expr', 'count')
  27 #define *ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count')
  28 #define *ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
  29 #define *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type',
  30                          'field_name', 'expr')
  31 #define *ctf_enum_value*('label', 'value')
  32 #define *ctf_enum_range*('label', 'start', 'end')
  33 #define *ctf_float*('float_type', 'field_name', 'expr')
  34 #define *ctf_float_nowrite*('float_type', 'field_name', 'expr')
  35 #define *ctf_integer*('int_type', 'field_name', 'expr')
  36 #define *ctf_integer_hex*('int_type', 'field_name', 'expr')
  37 #define *ctf_integer_network*('int_type', 'field_name', 'expr')
  38 #define *ctf_integer_network_hex*('int_type', 'field_name', 'expr')
  39 #define *ctf_integer_nowrite*('int_type', 'field_name', 'expr')
  40 #define *ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
  41 #define *ctf_sequence_nowrite*('int_type', 'field_name', 'expr',
  42                              'len_type', 'len_expr')
  43 #define *ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr')
  44 #define *ctf_sequence_text_nowrite*(char, 'field_name', 'expr',
  45                                   'len_type', 'len_expr')
  46 #define *ctf_string*('field_name', 'expr')
  47 #define *ctf_string_nowrite*('field_name', 'expr')
  48 #define *do_tracepoint*('prov_name', 't_name', ...)
  49 #define *tracepoint*('prov_name', 't_name', ...)
  50 #define *tracepoint_enabled*('prov_name', 't_name')
  51
  52 Link with `-llttng-ust -ldl`, following this man page.
  53
  54
  55 DESCRIPTION
  56 -----------
  57 The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
  58 source software package used for correlated tracing of the Linux kernel,
  59 user applications, and user libraries.
  60
  61 LTTng-UST is the user space tracing component of the LTTng project. It
  62 is a port to user space of the low-overhead tracing capabilities of the
  63 LTTng Linux kernel tracer. The `liblttng-ust` library is used to trace
  64 user applications and libraries.
  65
  66 NOTE: This man page is about the `liblttng-ust` library. The LTTng-UST
  67 project also provides Java and Python packages to trace applications
  68 written in those languages. How to instrument and trace Java and Python
  69 applications is documented in
  70 http://lttng.org/docs/[the online LTTng documentation].
  71
  72 There are three ways to use `liblttng-ust`:
  73
  74   * Using the man:tracef(3) API, which is similar to man:printf(3).
  75   * Using the man:tracelog(3) API, which is man:tracef(3) with
  76     a log level parameter.
  77   * Defining your own tracepoints. See the
  78     <<creating-tp,Creating a tracepoint provider>> section below.
  79
  80
  81 [[creating-tp]]
  82 Creating a tracepoint provider
  83 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  84 Creating a tracepoint provider is the first step of using
  85 `liblttng-ust`. The next steps are:
  86
  87   * <<tracepoint,Instrumenting your application with `tracepoint()` calls>>
  88   * Building your application with LTTng-UST support, either
  89     <<build-static,statically>> or <<build-dynamic,dynamically>>.
  90
  91 A *tracepoint provider* is a compiled object containing the event
  92 probes corresponding to your custom tracepoint definitions. A tracepoint
  93 provider contains the code to get the size of an event and to serialize
  94 it, amongst other things.
  95
  96 To create a tracepoint provider, start with the following
  97 _tracepoint provider header_ template:
  98
  99 ------------------------------------------------------------------------
 100 #undef TRACEPOINT_PROVIDER
 101 #define TRACEPOINT_PROVIDER my_provider
 102
 103 #undef TRACEPOINT_INCLUDE
 104 #define TRACEPOINT_INCLUDE "./tp.h"
 105
 106 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
 107 #define _TP_H
 108
 109 #include <lttng/tracepoint.h>
 110
 111 /*
 112  * TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
 113  * TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(),
 114  * and `TRACEPOINT_ENUM()` are used here.
 115  */
 116
 117 #endif /* _TP_H */
 118
 119 #include <lttng/tracepoint-event.h>
 120 ------------------------------------------------------------------------
 121
 122 In this template, the tracepoint provider is named `my_provider`
 123 (`TRACEPOINT_PROVIDER` definition). The file needs to bear the
 124 name of the `TRACEPOINT_INCLUDE` definition (`tp.h` in this case).
 125 Between `#include <lttng/tracepoint.h>` and `#endif` go
 126 the invocations of the <<tracepoint-event,`TRACEPOINT_EVENT()`>>,
 127 <<tracepoint-event-class,`TRACEPOINT_EVENT_CLASS()`>>,
 128 <<tracepoint-event-class,`TRACEPOINT_EVENT_INSTANCE()`>>,
 129 <<tracepoint-loglevel,`TRACEPOINT_LOGLEVEL()`>>, and
 130 <<tracepoint-enum,`TRACEPOINT_ENUM()`>> macros.
 131
 132 NOTE: You can avoid writing the prologue and epilogue boilerplate in the
 133 template file above by using the man:lttng-gen-tp(1) tool shipped with
 134 LTTng-UST.
 135
 136 The tracepoint provider header file needs to be included in a source
 137 file which looks like this:
 138
 139 ------------------------------------------------------------------------
 140 #define TRACEPOINT_CREATE_PROBES
 141
 142 #include "tp.h"
 143 ------------------------------------------------------------------------
 144
 145 Together, those two files (let's call them `tp.h` and `tp.c`) form the
 146 tracepoint provider sources, ready to be compiled.
 147
 148 You can create multiple tracepoint providers to be used in a single
 149 application, but each one must have its own header file.
 150
 151 The <<tracepoint-event,`TRACEPOINT_EVENT()` usage>> section below
 152 shows how to use the `TRACEPOINT_EVENT()` macro to define the actual
 153 tracepoints in the tracepoint provider header file.
 154
 155 See the <<example,EXAMPLE>> section below for a complete example.
 156
 157
 158 [[tracepoint-event]]
 159 `TRACEPOINT_EVENT()` usage
 160 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 161 The `TRACEPOINT_EVENT()` macro is used in a template provider
 162 header file (see the <<creating-tp,Creating a tracepoint provider>>
 163 section above) to define LTTng-UST tracepoints.
 164
 165 The `TRACEPOINT_EVENT()` usage template is as follows:
 166
 167 ------------------------------------------------------------------------
 168 TRACEPOINT_EVENT(
 169     /* Tracepoint provider name */
 170     my_provider,
 171
 172     /* Tracepoint/event name */
 173     my_tracepoint,
 174
 175     /* List of tracepoint arguments (input) */
 176     TP_ARGS(
 177         ...
 178     ),
 179
 180     /* List of fields of eventual event (output) */
 181     TP_FIELDS(
 182         ...
 183     )
 184 )
 185 ------------------------------------------------------------------------
 186
 187 The `TP_ARGS()` macro contains the input arguments of the tracepoint.
 188 Those arguments can be used in the argument expressions of the output
 189 fields defined in `TP_FIELDS()`.
 190
 191 The format of the `TP_ARGS()` parameters is: C type, then argument name;
 192 repeat as needed, up to ten times. For example:
 193
 194 ------------------------------------------------------------------------
 195 TP_ARGS(
 196     int, my_int,
 197     const char *, my_string,
 198     FILE *, my_file,
 199     double, my_float,
 200     struct my_data *, my_data
 201 )
 202 ------------------------------------------------------------------------
 203
 204 The `TP_FIELDS()` macro contains the output fields of the tracepoint,
 205 that is, the actual data that can be recorded in the payload of an
 206 event emitted by this tracepoint.
 207
 208 The `TP_FIELDS()` macro contains a list of `ctf_*()` macros
 209 :not: separated by commas. The available macros are documented in the
 210 <<ctf-macros,Available `ctf_*()` field type macros>> section below.
 211
 212
 213 [[ctf-macros]]
 214 Available `ctf_*()` field type macros
 215 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 216 This section documents the available `ctf_*()` macros that can be
 217 inserted in the `TP_FIELDS()` macro of the
 218 <<tracepoint-event,`TRACEPOINT_EVENT()` macro>>.
 219
 220 Standard integer, displayed in base 10:
 221
 222 [verse]
 223 *ctf_integer*('int_type', 'field_name', 'expr')
 224 *ctf_integer_nowrite*('int_type', 'field_name', 'expr')
 225
 226 Standard integer, displayed in base 16:
 227
 228 [verse]
 229 *ctf_integer_hex*('int_type', 'field_name', 'expr')
 230
 231 Integer in network byte order (big endian), displayed in base 10:
 232
 233 [verse]
 234 *ctf_integer_network*('int_type', 'field_name', 'expr')
 235
 236 Integer in network byte order, displayed in base 16:
 237
 238 [verse]
 239 *ctf_integer_network_hex*('int_type', 'field_name', 'expr')
 240
 241 Floating point number:
 242
 243 [verse]
 244 *ctf_float*('float_type', 'field_name', 'expr')
 245 *ctf_float_nowrite*('float_type', 'field_name', 'expr')
 246
 247 Null-terminated string:
 248
 249 [verse]
 250 *ctf_string*('field_name', 'expr')
 251 *ctf_string_nowrite*('field_name', 'expr')
 252
 253 Statically-sized array of integers:
 254
 255 [verse]
 256 *ctf_array*('int_type', 'field_name', 'expr', 'count')
 257 *ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count')
 258
 259 Statically-sized array, printed as text; no need to be null-terminated:
 260
 261 [verse]
 262 *ctf_array_text*(char, 'field_name', 'expr', 'count')
 263 *ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count')
 264
 265 Dynamically-sized array of integers:
 266
 267 [verse]
 268 *ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
 269 *ctf_sequence_nowrite*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
 270
 271 Dynamically-sized array, displayed as text; no need to be null-terminated:
 272
 273 [verse]
 274 *ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr')
 275 *ctf_sequence_text_nowrite*(char, 'field_name', 'expr', 'len_type', 'len_expr')
 276
 277 Enumeration. The enumeration field must be defined before using this
 278 macro with the `TRACEPOINT_ENUM()` macro. See the
 279 <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more
 280 information.
 281
 282 [verse]
 283 *ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
 284 *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
 285
 286 The parameters are:
 287
 288 'int_type'::
 289     Integer C type. The size of this type determines the size of the
 290     integer/enumeration field.
 291
 292 'float_type'::
 293     Float C type (`float` or `double`). The size of this type determines
 294     the size of the floating point number field.
 295
 296 'field_name'::
 297     Event field name (C identifier syntax, :not: a literal string).
 298
 299 'expr'::
 300     C expression resulting in the field's value. This expression can
 301     use one or more arguments passed to the tracepoint. The arguments
 302     of a given tracepoint are defined in the `TP_ARGS()` macro (see
 303     the <<creating-tp,Creating a tracepoint provider>> section above).
 304
 305 'count'::
 306     Number of elements in array/sequence. This must be known at
 307     compile time.
 308
 309 'len_type'::
 310     Unsigned integer C type of sequence's length.
 311
 312 'len_expr'::
 313     C expression resulting in the sequence's length. This expression
 314     can use one or more arguments passed to the tracepoint.
 315
 316 'prov_name'::
 317     Tracepoint provider name. This must be the same as the tracepoint
 318     provider name used in a previous field definition.
 319
 320 'enum_name'::
 321     Name of an enumeration field previously defined with the
 322     `TRACEPOINT_ENUM()` macro. See the
 323     <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more
 324     information.
 325
 326 The `_nowrite` versions omit themselves from the recorded trace, but are
 327 otherwise identical. Their primary purpose is to make some of the
 328 event context available to the event filters without having to commit
 329 the data to sub-buffers. See man:lttng-enable-event(1) to learn more
 330 about dynamic event filtering.
 331
 332 See the <<example,EXAMPLE>> section below for a complete example.
 333
 334
 335 [[tracepoint-enum]]
 336 `TRACEPOINT_ENUM()` usage
 337 ~~~~~~~~~~~~~~~~~~~~~~~~~
 338 An enumeration field is a list of mappings between an integers, or a
 339 range of integers, and strings (sometimes called _labels_ or
 340 _enumerators_). Enumeration fields can be used to have a more compact
 341 trace when the possible values for a field are limited.
 342
 343 An enumeration field is defined with the `TRACEPOINT_ENUM()` macro:
 344
 345 ------------------------------------------------------------------------
 346 TRACEPOINT_ENUM(
 347     /* Tracepoint provider name */
 348     my_provider,
 349
 350     /* Enumeration name (unique in the whole tracepoint provider) */
 351     my_enum,
 352
 353     /* Enumeration mappings */
 354     TP_ENUM_VALUES(
 355         ...
 356     )
 357 )
 358 ------------------------------------------------------------------------
 359
 360 `TP_ENUM_VALUES()` contains a list of enumeration mappings, :not:
 361 separated by commas. Two macros can be used in the `TP_ENUM_VALUES()`:
 362 `ctf_enum_value()` and `ctf_enum_range()`.
 363
 364 `ctf_enum_value()` is a single value mapping:
 365
 366 [verse]
 367 *ctf_enum_value*('label', 'value')
 368
 369 This macro maps the given 'label' string to the value 'value'.
 370
 371 `ctf_enum_range()` is a range mapping:
 372
 373 [verse]
 374 *ctf_enum_range*('label', 'start', 'end')
 375
 376 This macro maps the given 'label' string to the range of integers from
 377 'start' to 'end', inclusively. Range mappings may overlap, but the
 378 behaviour is implementation-defined: each trace reader handles
 379 overlapping ranges as it wishes.
 380
 381 See the <<example,EXAMPLE>> section below for a complete example.
 382
 383
 384 [[tracepoint-event-class]]
 385 `TRACEPOINT_EVENT_CLASS()` usage
 386 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 387 A *tracepoint class* is a class of tracepoints sharing the
 388 same field types and names. A tracepoint instance is one instance of
 389 such a declared tracepoint class, with its own event name.
 390
 391 LTTng-UST creates one event serialization function per tracepoint
 392 class. Using `TRACEPOINT_EVENT()` creates one tracepoint class per
 393 tracepoint definition, whereas using `TRACEPOINT_EVENT_CLASS()` and
 394 `TRACEPOINT_EVENT_INSTANCE()` creates one tracepoint class, and one or
 395 more tracepoint instances of this class. In other words, many
 396 tracepoints can reuse the same serialization code. Reusing the same
 397 code, when possible, can reduce cache pollution, thus improve
 398 performance.
 399
 400 The `TRACEPOINT_EVENT_CLASS()` macro accepts the same parameters as
 401 the `TRACEPOINT_EVENT()` macro, except that instead of an event name,
 402 its second parameter is the _tracepoint class name_:
 403
 404 ------------------------------------------------------------------------
 405 TRACEPOINT_EVENT_CLASS(
 406     /* Tracepoint provider name */
 407     my_provider,
 408
 409     /* Tracepoint class name */
 410     my_tracepoint_class,
 411
 412     /* List of tracepoint arguments (input) */
 413     TP_ARGS(
 414         ...
 415     ),
 416
 417     /* List of fields of eventual event (output) */
 418     TP_FIELDS(
 419         ...
 420     )
 421 )
 422 ------------------------------------------------------------------------
 423
 424 Once the tracepoint class is defined, you can create as many tracepoint
 425 instances as needed:
 426
 427 -------------------------------------------------------------------------
 428 TRACEPOINT_EVENT_INSTANCE(
 429     /* Tracepoint provider name */
 430     my_provider,
 431
 432     /* Tracepoint class name */
 433     my_tracepoint_class,
 434
 435     /* Tracepoint/event name */
 436     my_tracepoint,
 437
 438     /* List of tracepoint arguments (input) */
 439     TP_ARGS(
 440         ...
 441     )
 442 )
 443 ------------------------------------------------------------------------
 444
 445 As you can see, the `TRACEPOINT_EVENT_INSTANCE()` does not contain
 446 the `TP_FIELDS()` macro, because they are defined at the
 447 `TRACEPOINT_EVENT_CLASS()` level.
 448
 449 See the <<example,EXAMPLE>> section below for a complete example.
 450
 451
 452 [[tracepoint-loglevel]]
 453 `TRACEPOINT_LOGLEVEL()` usage
 454 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 455 Optionally, a *log level* can be assigned to a defined tracepoint.
 456 Assigning different levels of severity to tracepoints can be useful:
 457 when controlling tracing sessions, you can choose to only enable
 458 events falling into a specific log level range using the
 459 nloption:--loglevel and nloption:--loglevel-only options of the
 460 man:lttng-enable-event(1) command.
 461
 462 Log levels are assigned to tracepoints that are already defined using
 463 the `TRACEPOINT_LOGLEVEL()` macro. The latter must be used after having
 464 used `TRACEPOINT_EVENT()` or `TRACEPOINT_EVENT_INSTANCE()` for a given
 465 tracepoint. The `TRACEPOINT_LOGLEVEL()` macro is used as follows:
 466
 467 ------------------------------------------------------------------------
 468 TRACEPOINT_LOGLEVEL(
 469     /* Tracepoint provider name */
 470     my_provider,
 471
 472     /* Tracepoint/event name */
 473     my_tracepoint,
 474
 475     /* Log level */
 476     TRACE_INFO
 477 )
 478 ------------------------------------------------------------------------
 479
 480 The available log level definitions are:
 481
 482 include::log-levels.txt[]
 483
 484 See the <<example,EXAMPLE>> section below for a complete example.
 485
 486
 487 [[tracepoint]]
 488 Instrumenting your application
 489 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 490 Once the tracepoint provider is created (see the
 491 <<creating-tp,Creating a tracepoint provider>> section above), you can
 492 instrument your application with the defined tracepoints thanks to the
 493 `tracepoint()` macro:
 494
 495 [verse]
 496 #define *tracepoint*('prov_name', 't_name', ...)
 497
 498 With:
 499
 500 'prov_name'::
 501     Tracepoint provider name.
 502
 503 't_name'::
 504     Tracepoint/event name.
 505
 506 `...`::
 507     Tracepoint arguments, if any.
 508
 509 Make sure to include the tracepoint provider header file anywhere you
 510 use `tracepoint()` for this provider.
 511
 512 NOTE: Even though LTTng-UST supports `tracepoint()` call site duplicates
 513 having the same provider and tracepoint names, it is recommended to use
 514 a provider/tracepoint name pair only once within the application source
 515 code to help map events back to their call sites when analyzing the
 516 trace.
 517
 518 Sometimes, arguments to the tracepoint are expensive to compute (take
 519 call stack, for example). To avoid the computation when the tracepoint
 520 is disabled, you can use the `tracepoint_enabled()` and
 521 `do_tracepoint()` macros:
 522
 523 [verse]
 524 #define *tracepoint_enabled*('prov_name', 't_name')
 525 #define *do_tracepoint*('prov_name', 't_name', ...)
 526
 527 `tracepoint_enabled()` returns a non-zero value if the tracepoint
 528 named 't_name' from the provider named 'prov_name' is enabled at
 529 run time.
 530
 531 `do_tracepoint()` is like `tracepoint()`, except that it doesn't check
 532 if the tracepoint is enabled. Using `tracepoint()` with
 533 `tracepoint_enabled()` is dangerous since `tracepoint()` also contains
 534 the `tracepoint_enabled()` check, thus a race condition is possible
 535 in this situation:
 536
 537 ------------------------------------------------------------------------
 538 if (tracepoint_enabled(my_provider, my_tracepoint)) {
 539     stuff = prepare_stuff();
 540 }
 541
 542 tracepoint(my_provider, my_tracepoint, stuff);
 543 ------------------------------------------------------------------------
 544
 545 If the tracepoint is enabled after the condition, then `stuff` is not
 546 prepared: the emitted event will either contain wrong data, or the
 547 whole application could crash (segmentation fault, for example).
 548
 549 NOTE: Neither `tracepoint_enabled()` nor `do_tracepoint()` have
 550 a `STAP_PROBEV()` call, so if you need it, you should emit this call
 551 yourself.
 552
 553
 554 [[build-static]]
 555 Statically linking the tracepoint provider
 556 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 557 With the static linking method, compiled tracepoint providers are copied
 558 into the target application.
 559
 560 Define `TRACEPOINT_DEFINE` definition below the
 561 `TRACEPOINT_CREATE_PROBES` definition in the tracepoint provider
 562 source:
 563
 564 ------------------------------------------------------------------------
 565 #define TRACEPOINT_CREATE_PROBES
 566 #define TRACEPOINT_DEFINE
 567
 568 #include "tp.h"
 569 ------------------------------------------------------------------------
 570
 571 Create the tracepoint provider object file:
 572
 573 [role="term"]
 574 --------------
 575 cc -c -I. tp.c
 576 --------------
 577
 578 NOTE: Although an application instrumented with LTTng-UST tracepoints
 579 can be compiled with a C++ compiler, tracepoint probes should be
 580 compiled with a C compiler.
 581
 582 At this point, you _can_ archive this tracepoint provider object file,
 583 possibly with other object files of your application or with other
 584 tracepoint provider object files, as a static library:
 585
 586 [role="term"]
 587 ---------------
 588 ar rc tp.a tp.o
 589 ---------------
 590
 591 Using a static library does have the advantage of centralising the
 592 tracepoint providers objects so they can be shared between multiple
 593 applications. This way, when the tracepoint provider is modified, the
 594 source code changes don't have to be patched into each application's
 595 source code tree. The applications need to be relinked after each
 596 change, but need not to be otherwise recompiled (unless the tracepoint
 597 provider's API changes).
 598
 599 Then, link your application with this object file (or with the static
 600 library containing it) and with `liblttng-ust` and `libdl`
 601 (`libc` on a BSD system):
 602
 603 [role="term"]
 604 -------------------------------------
 605 cc -o app tp.o app.o -llttng-ust -ldl
 606 -------------------------------------
 607
 608
 609 [[build-dynamic]]
 610 Dynamically loading the tracepoint provider
 611 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 612 The second approach to package the tracepoint provider is to use the
 613 dynamic loader: the library and its member functions are explicitly
 614 sought, loaded at run time.
 615
 616 In this scenario, the tracepoint provider is compiled as a shared
 617 object.
 618
 619 The process to create the tracepoint provider shared object is pretty
 620 much the same as the <<build-static,static linking method>>, except
 621 that:
 622
 623   * Since the tracepoint provider is not part of the application,
 624     `TRACEPOINT_DEFINE` must be defined, for each tracepoint
 625     provider, in exactly one source file of the
 626     _application_
 627   * `TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next
 628     to `TRACEPOINT_DEFINE`
 629
 630 Regarding `TRACEPOINT_DEFINE` and `TRACEPOINT_PROBE_DYNAMIC_LINKAGE`,
 631 the recommended practice is to use a separate C source file in your
 632 application to define them, then include the tracepoint provider header
 633 files afterwards. For example, as `tp-define.c`:
 634
 635 ------------------------------------------------------------------------
 636 #define TRACEPOINT_DEFINE
 637 #define TRACEPOINT_PROBE_DYNAMIC_LINKAGE
 638
 639 #include "tp.h"
 640 ------------------------------------------------------------------------
 641
 642 The tracepoint provider object file used to create the shared library is
 643 built like it is using the static linking method, but with the
 644 nloption:-fpic option:
 645
 646 [role="term"]
 647 --------------------
 648 cc -c -fpic -I. tp.c
 649 --------------------
 650
 651 It is then linked as a shared library like this:
 652
 653 [role="term"]
 654 -------------------------------------------------------
 655 cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
 656 -------------------------------------------------------
 657
 658 This tracepoint provider shared object isn't linked with the user
 659 application: it must be loaded manually. This is why the application is
 660 built with no mention of this tracepoint provider, but still needs
 661 libdl:
 662
 663 [role="term"]
 664 --------------------------------
 665 cc -o app app.o tp-define.o -ldl
 666 --------------------------------
 667
 668 There are two ways to dynamically load the tracepoint provider shared
 669 object:
 670
 671   * Load it manually from the application using man:dlopen(3)
 672   * Make the dynamic loader load it with the `LD_PRELOAD`
 673     environment variable (see man:ld.so(8))
 674
 675 If the application does not dynamically load the tracepoint provider
 676 shared object using one of the methods above, tracing is disabled for
 677 this application, and the events are not listed in the output of
 678 man:lttng-list(1).
 679
 680 Note that it is not safe to use man:dlclose(3) on a tracepoint provider
 681 shared object that is being actively used for tracing, due to a lack of
 682 reference counting from LTTng-UST to the shared object.
 683
 684 For example, statically linking a tracepoint provider to a shared object
 685 which is to be dynamically loaded by an application (a plugin, for
 686 example) is not safe: the shared object, which contains the tracepoint
 687 provider, could be dynamically closed (man:dlclose(3)) at any time by
 688 the application.
 689
 690 To instrument a shared object, either:
 691
 692   * Statically link the tracepoint provider to the application, or
 693   * Build the tracepoint provider as a shared object (following the
 694     procedure shown in this section), and preload it when tracing is
 695     needed using the `LD_PRELOAD` environment variable.
 696
 697
 698 Using LTTng-UST with daemons
 699 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 700 Some extra care is needed when using `liblttng-ust` with daemon
 701 applications that call man:fork(2), man:clone(2), or BSD's man:rfork(2)
 702 without a following man:exec(3) family system call. The library
 703 `liblttng-ust-fork.so` needs to be preloaded before starting the
 704 application with the `LD_PRELOAD` environment variable (see
 705 man:ld.so(8)).
 706
 707
 708 Context information
 709 ~~~~~~~~~~~~~~~~~~~
 710 Context information can be prepended by the LTTng-UST tracer before
 711 each event, or before specific events.
 712
 713 Context fields can be added to specific channels using
 714 man:lttng-add-context(1).
 715
 716 The following context fields are supported by LTTng-UST:
 717
 718 `cpu_id`::
 719     CPU ID.
 720 +
 721 NOTE: This context field is always enabled, and it cannot be added
 722 with man:lttng-add-context(1). Its main purpose is to be used for
 723 dynamic event filtering. See man:lttng-enable-event(1) for more
 724 information about event filtering.
 725
 726 `ip`::
 727     Instruction pointer: enables recording the exact address from which
 728     an event was emitted. This context field can be used to
 729     reverse-lookup the source location that caused the event
 730     to be emitted.
 731
 732 +perf:thread:COUNTER+::
 733     perf counter named 'COUNTER'. Use `lttng add-context --list` to
 734     list the available perf counters.
 735 +
 736 Only available on IA-32 and x86-64 architectures.
 737
 738 `pthread_id`::
 739     POSIX thread identifier. Can be used on architectures where
 740     `pthread_t` maps nicely to an `unsigned long` type.
 741
 742 `procname`::
 743     Thread name, as set by man:exec(3) or man:prctl(2). It is
 744     recommended that programs set their thread name with man:prctl(2)
 745     before hitting the first tracepoint for that thread.
 746
 747 `vpid`::
 748     Virtual process ID: process ID as seen from the point of view of
 749     the process namespace.
 750
 751 `vtid`::
 752     Virtual thread ID: thread ID as seen from the point of view of
 753     the process namespace.
 754
 755
 756 LTTng-UST state dump
 757 ~~~~~~~~~~~~~~~~~~~~
 758 If an application that uses `liblttng-ust` becomes part of a tracing
 759 session, information about its currently loaded shared objects, their
 760 build IDs, and their debug link informations are emitted as events
 761 by the tracer.
 762
 763 The following LTTng-UST state dump events exist and must be enabled
 764 to record application state dumps.
 765
 766 `lttng_ust_statedump:start`::
 767     Emitted when the state dump begins.
 768 +
 769 This event has no fields.
 770
 771 `lttng_ust_statedump:end`::
 772     Emitted when the state dump ends. Once this event is emitted, it
 773     is guaranteed that, for a given process, the state dump is
 774     complete.
 775 +
 776 This event has no fields.
 777
 778 `lttng_ust_statedump:soinfo`::
 779     Emitted when information about a currently loaded shared object is
 780     found.
 781 +
 782 Fields:
 783 +
 784 [options="header"]
 785 |==============================================================
 786 | Field name                 | Description
 787 | `baddr`                    | Base address of loaded library
 788 | `memsz`                    | Size of loaded library in memory
 789 | `sopath`                   | Path to loaded library file
 790 |==============================================================
 791
 792 `lttng_ust_statedump:build_id`::
 793     Emitted when a build ID is found in a currently loaded shared
 794     library. See
 795     https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
 796     for more information about build IDs.
 797 +
 798 Fields:
 799 +
 800 [options="header"]
 801 |==============================================================
 802 | Field name                 | Description
 803 | `baddr`                    | Base address of loaded library
 804 | `build_id`                 | Build ID
 805 |==============================================================
 806
 807 `lttng_ust_statedump:debug_link`::
 808     Emitted when debug link information is found in a currently loaded
 809     shared library. See
 810     https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging Information in Separate Files]
 811     for more information about debug links.
 812 +
 813 Fields:
 814 +
 815 [options="header"]
 816 |==============================================================
 817 | Field name                 | Description
 818 | `baddr`                    | Base address of loaded library
 819 | `crc`                      | Debug link file's CRC
 820 | `filename`                 | Debug link file name
 821 |==============================================================
 822
 823
 824 [[example]]
 825 EXAMPLE
 826 -------
 827 NOTE: A few examples are available in the
 828 https://github.com/lttng/lttng-ust/tree/master/doc/examples[`doc/examples`]
 829 directory of LTTng-UST's source tree.
 830
 831 This example shows all the features documented in the previous
 832 sections. The <<build-static,static linking>> method is chosen here
 833 to link the application with the tracepoint provider.
 834
 835 Let's start with the tracepoint provider header file (`tp.h`):
 836
 837 ------------------------------------------------------------------------
 838 #undef TRACEPOINT_PROVIDER
 839 #define TRACEPOINT_PROVIDER my_provider
 840
 841 #undef TRACEPOINT_INCLUDE
 842 #define TRACEPOINT_INCLUDE "./tp.h"
 843
 844 #if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
 845 #define _TP_H
 846
 847 #include <lttng/tracepoint.h>
 848 #include <stdio.h>
 849
 850 #include "app.h"
 851
 852 TRACEPOINT_EVENT(
 853     my_provider,
 854     simple_event,
 855     TP_ARGS(
 856         int, my_integer_arg,
 857         const char *, my_string_arg
 858     ),
 859     TP_FIELDS(
 860         ctf_string(argc, my_string_arg)
 861         ctf_integer(int, argv, my_integer_arg)
 862     )
 863 )
 864
 865 TRACEPOINT_ENUM(
 866     my_provider,
 867     my_enum,
 868     TP_ENUM_VALUES(
 869         ctf_enum_value("ZERO", 0)
 870         ctf_enum_value("ONE", 1)
 871         ctf_enum_value("TWO", 2)
 872         ctf_enum_range("A RANGE", 52, 125)
 873         ctf_enum_value("ONE THOUSAND", 1000)
 874     )
 875 )
 876
 877 TRACEPOINT_EVENT(
 878     my_provider,
 879     big_event,
 880     TP_ARGS(
 881         int, my_integer_arg,
 882         const char *, my_string_arg,
 883         FILE *, stream,
 884         double, flt_arg,
 885         int *, array_arg
 886     ),
 887     TP_FIELDS(
 888         ctf_integer(int, int_field1, my_integer_arg * 2)
 889         ctf_integer_hex(long int, stream_pos, ftell(stream))
 890         ctf_float(double, float_field, flt_arg)
 891         ctf_string(string_field, my_string_arg)
 892         ctf_array(int, array_field, array_arg, 7)
 893         ctf_array_text(char, array_text_field, array_arg, 5)
 894         ctf_sequence(int, seq_field, array_arg, int,
 895                      my_integer_arg / 10)
 896         ctf_sequence_text(char, seq_text_field, array_arg,
 897                           int, my_integer_arg / 5)
 898         ctf_enum(my_provider, my_enum, int,
 899                  enum_field, array_arg[1])
 900     )
 901 )
 902
 903 TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING)
 904
 905 TRACEPOINT_EVENT_CLASS(
 906     my_provider,
 907     my_tracepoint_class,
 908     TP_ARGS(
 909         int, my_integer_arg,
 910         struct app_struct *, app_struct_arg
 911     ),
 912     TP_FIELDS(
 913         ctf_integer(int, a, my_integer_arg)
 914         ctf_integer(unsigned long, b, app_struct_arg->b)
 915         ctf_string(c, app_struct_arg->c)
 916     )
 917 )
 918
 919 TRACEPOINT_EVENT_INSTANCE(
 920     my_provider,
 921     my_tracepoint_class,
 922     event_instance1,
 923     TP_ARGS(
 924         int, my_integer_arg,
 925         struct app_struct *, app_struct_arg
 926     )
 927 )
 928
 929 TRACEPOINT_EVENT_INSTANCE(
 930     my_provider,
 931     my_tracepoint_class,
 932     event_instance2,
 933     TP_ARGS(
 934         int, my_integer_arg,
 935         struct app_struct *, app_struct_arg
 936     )
 937 )
 938
 939 TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO)
 940
 941 TRACEPOINT_EVENT_INSTANCE(
 942     my_provider,
 943     my_tracepoint_class,
 944     event_instance3,
 945     TP_ARGS(
 946         int, my_integer_arg,
 947         struct app_struct *, app_struct_arg
 948     )
 949 )
 950
 951 #endif /* _TP_H */
 952
 953 #include <lttng/tracepoint-event.h>
 954 ------------------------------------------------------------------------
 955
 956 The tracepoint provider source file looks like this (`tp.c`):
 957
 958 ------------------------------------------------------------------------
 959 #define TRACEPOINT_CREATE_PROBES
 960 #define TRACEPOINT_DEFINE
 961
 962 #include "tp.h"
 963 ------------------------------------------------------------------------
 964
 965 The included `app.h`, where the application structure resides, is:
 966
 967 ------------------------------------------------------------------------
 968 #ifndef _APP_H
 969 #define _APP_H
 970
 971 struct app_struct {
 972     unsigned long b;
 973     const char *c;
 974     double d;
 975 };
 976
 977 #endif /* _APP_H */
 978 ------------------------------------------------------------------------
 979
 980 Finally, the application itself, `app.c`, using the defined tracepoints:
 981
 982 ------------------------------------------------------------------------
 983 #include <stdlib.h>
 984 #include <stdio.h>
 985
 986 #include "tp.h"
 987 #include "app.h"
 988
 989 static int array_of_ints[] = {
 990     100, -35, 1, 23, 14, -6, 28, 1001, -3000,
 991 };
 992
 993 int main(int argc, char* argv[])
 994 {
 995     FILE *stream;
 996     struct app_struct app_struct;
 997
 998     tracepoint(my_provider, simple_event, argc, argv[0]);
 999     stream = fopen("/tmp/app.txt", "w");
1000
1001     if (!stream) {
1002         fprintf(stderr,
1003                 "Error: Cannot open /tmp/app.txt for writing\n");
1004         return EXIT_FAILURE;
1005     }
1006
1007     if (fprintf(stream, "0123456789") != 10) {
1008         fclose(stream);
1009         fprintf(stderr, "Error: Cannot write to /tmp/app.txt\n");
1010         return EXIT_FAILURE;
1011     }
1012
1013     tracepoint(my_provider, big_event, 35, "hello tracepoint",
1014                stream, -3.14, array_of_ints);
1015     fclose(stream);
1016     app_struct.b = argc;
1017     app_struct.c = "[the string]";
1018     tracepoint(my_provider, event_instance1, 23, &app_struct);
1019     app_struct.b = argc * 5;
1020     app_struct.c = "[other string]";
1021     tracepoint(my_provider, event_instance2, 17, &app_struct);
1022     app_struct.b = 23;
1023     app_struct.c = "nothing";
1024     tracepoint(my_provider, event_instance3, -52, &app_struct);
1025
1026     return EXIT_SUCCESS;
1027 }
1028 ------------------------------------------------------------------------
1029
1030 Here are the steps to compile the source files and link them together
1031 statically:
1032
1033 [role="term"]
1034 -------------------------------------
1035 cc -c -I. tp.c
1036 cc -c app.c
1037 cc -o app tp.o app.o -llttng-ust -ldl
1038 -------------------------------------
1039
1040
1041 include::common-footer.txt[]
1042
1043 include::common-copyrights.txt[]
1044
1045 include::common-authors.txt[]
1046
1047
1048 SEE ALSO
1049 --------
1050 man:tracef(3),
1051 man:tracelog(3),
1052 man:lttng-gen-tp(1),
1053 man:lttng-ust-dl(3),
1054 man:lttng-ust-cyg-profile(3),
1055 man:lttng(1),
1056 man:lttng-enable-event(1),
1057 man:lttng-list(1),
1058 man:lttng-add-context(1),
1059 man:babeltrace(1),
1060 man:dlopen(3),
1061 man:ld.so(8)