doc/man/lttng-ust.3

   1 .TH "LTTNG-UST" "3" "February 16, 2012" "" ""
   2
   3 .SH "NAME"
   4 lttng-ust \(em Linux Trace Toolkit Next Generation User-Space Tracer 2.x
   5
   6 .SH "SYNOPSIS"
   7
   8 .PP
   9 .nf
  10 Link liblttng-ust.so with applications, following this manpage.
  11 .fi
  12 .SH "DESCRIPTION"
  13
  14 .PP
  15 LTTng-UST, the Linux Trace Toolkit Next Generation Userspace Tracer, is a
  16 port of the low-overhead tracing capabilities of the LTTng kernel tracer
  17 to user-space. The library "liblttng-ust" enables tracing of
  18 applications and libraries.
  19
  20 .SH "USAGE WITH TRACEF"
  21 .PP
  22 The simplest way to add instrumentation to your code is by far the
  23 tracef() API. To do it, in a nutshell:
  24
  25 1) #include <lttng/tracef.h>
  26
  27 2) /* in your code, use like a printf */
  28    tracef("my message, this integer %d", 1234);
  29
  30 3) Link your program against liblttng-ust.so.
  31
  32 4) Enable UST events when tracing with the following sequence of commands
  33    from lttng-tools:
  34
  35    lttng create
  36    lttng enable-event -u -a
  37    lttng start
  38    [... run your program ...]
  39    lttng stop
  40    lttng view
  41
  42 That's it!
  43
  44 If you want to have more flexibility and control on the event names,
  45 payload typing, etc, you can continue reading on and use the tracepoints
  46 below. "tracef()" is there for quick and dirty ad hoc instrumentation,
  47 whereas tracepoint.h is meant for thorough instrumentation of a code
  48 base to be integrated with an upstream project.
  49 .PP
  50
  51 .SH "USAGE WITH TRACELOG"
  52 .PP
  53 If you want to migrate existing logging (info, errors, ...)
  54 to LTTng UST, you can use the tracelog() interface.
  55 To do it, in a nutshell:
  56
  57 1) #include <lttng/tracelog.h>
  58
  59 2) /* in your code, use like a printf, with extra loglevel info. */
  60    tracelog(TRACE_INFO, "Message with integer %d", 1234);
  61
  62 3) Link your program against liblttng-ust.so.
  63
  64 4) Enable UST events when tracing with the following sequence of commands
  65    from lttng-tools:
  66
  67    lttng create
  68    lttng enable-event -u "lttng_ust_tracelog:*"
  69    lttng start
  70    [... run your program ...]
  71    lttng stop
  72    lttng view
  73
  74 That's it!
  75
  76 You can replace the enable-event line above with a selection of
  77 loglevels, e.g.:
  78
  79    lttng enable-event -u -a --loglevel TRACE_INFO
  80
  81 Which will gather all events from TRACE_INFO and more important
  82 loglevels.
  83
  84 .PP
  85
  86 .SH "USAGE WITH TRACEPOINT"
  87 .PP
  88 The simple way to generate the lttng-ust tracepoint probes is to use the
  89 lttng-gen-tp(1) tool. See the lttng-gen-tp(1) manpage for explanation.
  90 .PP
  91
  92 .PP
  93 Here is the way to do it manually, without the lttng-gen-tp(1) helper
  94 script, through an example:
  95 .PP
  96
  97 .SH "CREATION OF TRACEPOINT PROVIDER"
  98
  99 .nf
 100
 101 To create a tracepoint provider, within a build tree similar to
 102 examples/easy-ust installed with lttng-ust documentation, see
 103 sample_component_provider.h for the general layout. You will need to
 104 define TRACEPOINT_CREATE_PROBES before including your tracepoint
 105 provider probe in one source file of your application. See tp.c from
 106 easy-ust for an example of a tracepoint probe source file. This manpage
 107 will focus on the various types that can be recorded into a trace
 108 event:
 109
 110 TRACEPOINT_EVENT(
 111         /*
 112          * provider name, not a variable but a string starting with a
 113          * letter and containing either letters, numbers or underscores.
 114          * Needs to be the same as TRACEPOINT_PROVIDER. Needs to
 115          * follow the namespacing guide-lines in lttng/tracepoint.h:
 116          *
 117          * Must be included before include tracepoint provider
 118          * ex.: project_event
 119          * ex.: project_component_event
 120          *
 121          * Optional company name goes here
 122          *  ex.: com_efficios_project_component_event
 123          *
 124          * In this example, "sample" is the project, and "component" is the
 125          * component.
 126          */
 127         sample_component,
 128
 129         /*
 130          * tracepoint name, characters permitted follow the same
 131          * constraints as the provider name. The name of this example
 132          * event is "sample_event".
 133          */
 134         sample_event,
 135
 136         /*
 137          * TP_ARGS macro contains the arguments passed for the tracepoint
 138          * it is in the following format
 139          *            TP_ARGS(type1, name1, type2, name2, ... type10,
 140                                  name10)
 141          * where there can be from zero to ten elements.
 142          * typeN is the datatype, such as int, struct or double **.
 143          * name is the variable name (in "int myInt" the name would be
 144          * myint)
 145          *            TP_ARGS() is valid to mean no arguments
 146          *            TP_ARGS(void) is valid too
 147          */
 148         TP_ARGS(int, anint, int, netint, long *, values,
 149                  char *, text, size_t, textlen,
 150                  double, doublearg, float, floatarg),
 151
 152         /*
 153          * TP_FIELDS describes how to write the fields of the trace event.
 154          * You can put expressions in the "argument expression" area,
 155          * typically using the input arguments from TP_ARGS.
 156          */
 157         TP_FIELDS(
 158                 /*
 159                  * ctf_integer: standard integer field.
 160                  * args: (type, field name, argument expression)
 161                  */
 162                 ctf_integer(int, intfield, anint)
 163                 ctf_integer(long, longfield, anint)
 164
 165                 /*
 166                  * ctf_integer_hex: integer field printed as hexadecimal.
 167                  * args: (type, field name, argument expression)
 168                  */
 169                 ctf_integer_hex(int, intfield2, anint)
 170
 171                 /*
 172                  * ctf_integer_network: integer field in network byte
 173                  * order. (_hex: printed as hexadecimal too)
 174                  * args: (type, field name, argument expression)
 175                  */
 176                 ctf_integer_network(int, netintfield, netint)
 177                 ctf_integer_network_hex(int, netintfieldhex, netint)
 178
 179                 /*
 180                  * ctf_array: a statically-sized array.
 181                  * args: (type, field name, argument expression, value)
 182                  */
 183                 ctf_array(long, arrfield1, values, 3)
 184
 185                 /*
 186                  * ctf_array_text: a statically-sized array, printed as
 187                  * a string. No need to be terminated by a null
 188                  * character.
 189                  * Behavior is undefined if "text" argument is NULL.
 190                  */
 191                 ctf_array_text(char, arrfield2, text, 10)
 192
 193                 /*
 194                  * ctf_sequence: a dynamically-sized array.
 195                  * args: (type, field name, argument expression,
 196                  *      type of length expression, length expression)
 197                  * The "type of length expression" needs to be an
 198                  * unsigned type. As a reminder, "unsigned char" should
 199                  * be preferred to "char", since the signedness of
 200                  * "char" is implementation-defined.
 201                  * Behavior is undefined if "text" argument is NULL.
 202                  */
 203                 ctf_sequence(char, seqfield1, text,
 204                              size_t, textlen)
 205
 206                 /*
 207                  * ctf_sequence_text: a dynamically-sized array, printed
 208                  * as string. No need to be null-terminated.
 209                  * Behavior is undefined if "text" argument is NULL.
 210                  */
 211                 ctf_sequence_text(char, seqfield2, text,
 212                              size_t, textlen)
 213
 214                 /*
 215                  * ctf_string: null-terminated string.
 216                  * args: (field name, argument expression)
 217                  * Behavior is undefined if "text" argument is NULL.
 218                  */
 219                 ctf_string(stringfield, text)
 220
 221                 /*
 222                  * ctf_float: floating-point number.
 223                  * args: (type, field name, argument expression)
 224                  */
 225                 ctf_float(float, floatfield, floatarg)
 226                 ctf_float(double, doublefield, doublearg)
 227
 228                 /*
 229                  * ctf_enum: a field using a previously declared
 230                  * enumeration args: (provider, enum name, container
 231                  * type, field name, argument expression). The
 232                  * enumeration itself and its values must have been
 233                  * defined previously with the TRACEPOINT_ENUM macro,
 234                  * described below.
 235                  */
 236                 ctf_enum(sample_component, enumeration_name, int,
 237                               enumfield, enumarg)
 238         )
 239 )
 240
 241 There can be an arbitrary number of tracepoint providers within an
 242 application, but they must each have their own provider name. Duplicate
 243 provider names are not allowed.
 244
 245 The CTF specification also supports enumerations that can be declared
 246 inside a tracepoint provider and used as fields in the tracepoint. This
 247 shows how to specify enumerations and what they can be used for:
 248
 249 The enumeration is a mapping between an integer, or a range of integers, and a
 250 string. It can be used to have a more compact trace in cases where the possible
 251 values for a field are limited:
 252
 253 TRACEPOINT_ENUM(
 254         /*
 255          * The provider name, as described in the TRACEPOINT_EVENT macro.
 256          */
 257         sample_component,
 258
 259         /*
 260          * The name of this enumeration, that will be used when using this
 261          * global type in tracepoint fields.
 262          */
 263         enumeration_name,
 264
 265         /*
 266          * TP_ENUM_VALUES describe the values of this enumeration and what they
 267          * map to.
 268          */
 269         TP_ENUM_VALUES(
 270                 /*
 271                  * Maps an integer with this string value. By default, enumerations
 272                  * start at 0 and increment 1 for each entry.
 273                  */
 274                 ctf_enum_value(string_value)
 275
 276                 /*
 277                  * Maps the string value to integers in the range 'start' to 'end'
 278                  * inclusively. If 'start' == 'end', then the string is mapped to
 279                  * a specific value.
 280                  * Enumeration ranges may overlap, but the behavior is
 281                  * implementation-defined, each trace reader will handle overlapping
 282                  * as it wishes.
 283                  */
 284                 ctf_enum_range(start, end, string_value)
 285         )
 286 )
 287
 288 .fi
 289
 290 .SH "ASSIGNING LOGLEVEL TO EVENTS"
 291
 292 .nf
 293
 294 Optionally, a loglevel can be assigned to a TRACEPOINT_EVENT using the
 295 following construct:
 296
 297         TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >,
 298                 < event >, < loglevel_name >)
 299
 300 The first field is the provider name, the second field is the name of
 301 the tracepoint, and the third field is the loglevel name.  A
 302 TRACEPOINT_EVENT should be declared prior to the the TRACEPOINT_LOGLEVEL
 303 for a given tracepoint name. The TRACEPOINT_PROVIDER must be already
 304 declared before declaring a TRACEPOINT_LOGLEVEL.
 305
 306 The loglevels go from 0 to 14. Higher numbers imply the most verbosity
 307 (higher event throughput expected.
 308
 309 Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels
 310 semantic. Loglevels 7 through 13 offer more fine-grained selection of
 311 debug information.
 312
 313    TRACE_EMERG           0
 314    system is unusable
 315
 316    TRACE_ALERT           1
 317    action must be taken immediately
 318
 319    TRACE_CRIT            2
 320    critical conditions
 321
 322    TRACE_ERR             3
 323    error conditions
 324
 325    TRACE_WARNING         4
 326    warning conditions
 327
 328    TRACE_NOTICE          5
 329    normal, but significant, condition
 330
 331    TRACE_INFO            6
 332    informational message
 333
 334    TRACE_DEBUG_SYSTEM    7
 335    debug information with system-level scope (set of programs)
 336
 337    TRACE_DEBUG_PROGRAM   8
 338    debug information with program-level scope (set of processes)
 339
 340    TRACE_DEBUG_PROCESS   9
 341    debug information with process-level scope (set of modules)
 342
 343    TRACE_DEBUG_MODULE    10
 344    debug information with module (executable/library) scope (set of
 345    units)
 346
 347    TRACE_DEBUG_UNIT      11
 348    debug information with compilation unit scope (set of functions)
 349
 350    TRACE_DEBUG_FUNCTION  12
 351    debug information with function-level scope
 352
 353    TRACE_DEBUG_LINE      13
 354    debug information with line-level scope (TRACEPOINT_EVENT default)
 355
 356    TRACE_DEBUG           14
 357    debug-level message
 358
 359 See lttng(1) for information on how to use LTTng-UST loglevels.
 360
 361 .fi
 362
 363 .SH "ADDING TRACEPOINTS TO YOUR CODE"
 364
 365 .nf
 366
 367 Include the provider header in each C files you plan to instrument,
 368 following the building/linking directives in the next section.
 369
 370 For instance, add within a function:
 371
 372                 tracepoint(ust_tests_hello, tptest, i, netint, values,
 373                         text, strlen(text), dbl, flt);
 374
 375 As a call to the tracepoint. It will only be activated when requested by
 376 lttng(1) through lttng-sessiond(8).
 377
 378 Even though LTTng-UST supports tracepoint() call site duplicates having
 379 the same provider and event name, it is recommended to use a
 380 provider event name pair only once within the source code to help
 381 map events back to their call sites when analyzing the trace.
 382
 383 Sometimes arguments to the probe are expensive to compute (e.g.
 384 take call stack). To avoid the computation when the tracepoint is
 385 disabled one can use more 'low level' tracepoint_enabled() and
 386 do_tracepoint() macros as following:
 387
 388         if (tracepoint_enabled(ust_tests_hello, tptest)) {
 389                 /* prepare arguments */
 390                 do_tracepoint(ust_tests_hello, tptest, i, netint, values,
 391                         text, strlen(text), dbl, flt);
 392         }
 393
 394 Here do_tracepoint() doesn't contain check if the tracepoint is enabled.
 395 Using tracepoint() in such scenario is dangerous since it also contains
 396 enabled check and thus race condition is possible in the following code
 397 if the tracepoint has been enabled after check in tracepoint_enabled()
 398 but before tracepoint():
 399
 400         if (tracepoint_enabled(provider, name)) { /* tracepoint is disabled */
 401                 prepare(args);
 402         }
 403         /* tracepoint is enabled by 'lttng' tool */
 404         tracepoint(provider, name, args); /* args wasn't prepared properly */
 405
 406 Note also that neither tracepoint_enabled() nor do_tracepoint() have
 407 STAP_PROBEV() call so if you need it you should emit this call yourself.
 408
 409 .fi
 410
 411 .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER"
 412
 413 .nf
 414 There are 2 ways to compile the Tracepoint Provider with the
 415 application: either statically or dynamically. Please follow
 416 carefully:
 417
 418   1) Compile the Tracepoint Provider with the application, either
 419      directly or through a static library (.a):
 420     - Into exactly one object of your application, define
 421       "TRACEPOINT_DEFINE" and include the tracepoint provider.
 422     - Use "\-I." for the compilation unit containing the tracepoint
 423       provider include (e.g., tp.c).
 424     - Link the application with "\-llttng-ust" and "\-ldl".
 425     - Include the tracepoint provider header into all C files using
 426       the provider.
 427     - Examples:
 428       - doc/examples/easy-ust/   sample.c sample_component_provider.h tp.c
 429         Makefile
 430       - doc/examples/hello-static-lib/   hello.c tp.c ust_test_hello.h Makefile
 431
 432   2) Compile the Tracepoint Provider separately from the application,
 433      using dynamic linking:
 434     - Into exactly one object of your application: define
 435       "TRACEPOINT_DEFINE" _and_ also define
 436       "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint
 437       provider header.
 438     - Include the tracepoint provider header into all instrumented C
 439       files that use the provider.
 440     - Compile the tracepoint provider with "\-I.".
 441     - Link the tracepoint provider with "\-llttng-ust".
 442     - Link application with "\-ldl".
 443     - Set a LD_PRELOAD environment to preload the tracepoint provider
 444       shared object before starting the application when tracing is
 445       needed. Another way is to dlopen the tracepoint probe when needed
 446       by the application.
 447     - Example:
 448       - doc/examples/demo   demo.c  tp*.c ust_tests_demo*.h demo-trace Makefile
 449
 450   - Note about dlclose() usage: it is not safe to use dlclose on a
 451     provider shared object that is being actively used for tracing due
 452     to a lack of reference counting from lttng-ust to the used shared
 453     object.
 454   - Enable instrumentation and control tracing with the "lttng" command
 455     from lttng-tools. See lttng-tools doc/quickstart.txt.
 456   - Note for C++ support: although an application instrumented with
 457     tracepoints can be compiled with g++, tracepoint probes should be
 458     compiled with gcc (only tested with gcc so far).
 459
 460 .fi
 461
 462 .SH "USING LTTNG UST WITH DAEMONS"
 463
 464 .nf
 465 Some extra care is needed when using liblttng-ust with daemon
 466 applications that call fork(), clone(), or BSD rfork() without a
 467 following exec() family system call. The library "liblttng-ust-fork.so"
 468 needs to be preloaded for the application (launch with e.g.
 469 LD_PRELOAD=liblttng-ust-fork.so appname).
 470
 471 .fi
 472
 473 .SH "CONTEXT"
 474
 475 .PP
 476 Context information can be prepended by the tracer before each, or some,
 477 events. The following context information is supported by LTTng-UST:
 478 .PP
 479
 480 .PP
 481 .IP "vtid"
 482 Virtual thread ID: thread ID as seen from the point of view of the
 483 process namespace.
 484 .PP
 485
 486 .PP
 487 .IP "vpid"
 488 Virtual process ID: process ID as seen from the point of view of the
 489 process namespace.
 490 .PP
 491
 492 .PP
 493 .IP "ip"
 494 Instruction pointer: Enables recording of the exact location where a tracepoint
 495 was emitted. Can be used to reverse-lookup the source location that caused the
 496 event to be emitted.
 497 .PP
 498
 499 .PP
 500 .IP "procname"
 501 Thread name, as set by exec() or prctl(). It is recommended that
 502 programs set their thread name with prctl() before hitting the first
 503 tracepoint for that thread.
 504 .PP
 505
 506 .PP
 507 .IP "pthread_id"
 508 Pthread identifier. Can be used on architectures where pthread_t maps
 509 nicely to an unsigned long type.
 510 .PP
 511
 512 .SH "BASE ADDRESS STATEDUMP"
 513
 514 .PP
 515 If an application that uses liblttng-ust.so becomes part of a session,
 516 information about its currently loaded shared objects will be traced to the
 517 session at session-enable time. To record this information, the following event
 518 needs to be enabled:
 519 .PP
 520 .IP "ust_baddr_statedump:soinfo"
 521 This event is used to trace a currently loaded shared object. The base address
 522 (where the dynamic linker has placed the shared object) is recorded in the
 523 "baddr" field. The path to the shared object gets recorded in the
 524 "sopath" field (as string). The file size of the loaded object (in
 525 bytes) is recorded to the "size" field and its time of last modification
 526 (in seconds since Epoch) is recorded in the "mtime" field.
 527 .PP
 528 If the event above is enabled, a series of "ust_baddr_statedump:soinfo"
 529 events is recorded at session-enable time. It represents the state of
 530 currently loaded shared objects for the traced process. If this
 531 information gets combined with the lttng-ust-dl(3) instrumentation, all
 532 aspects of dynamic loading that are relevant for symbol and
 533 line number lookup are traced by LTTng.
 534 .PP
 535 .SH "ENVIRONMENT VARIABLES"
 536
 537 .PP
 538 .IP "LTTNG_UST_DEBUG"
 539 Activate liblttng-ust debug and error output.
 540 .PP
 541 .IP "LTTNG_UST_REGISTER_TIMEOUT"
 542 The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
 543 specify how long the applications should wait for sessiond
 544 "registration done" command before proceeding to execute the main
 545 program. The default is 3000ms (3 seconds). The timeout value is
 546 specified in milliseconds. The value 0 means "don't wait". The value
 547 \-1 means "wait forever". Setting this environment variable to 0 is
 548 recommended for applications with time constraints on the process
 549 startup time.
 550 .PP
 551 .IP "LTTNG_UST_WITHOUT_BADDR_STATEDUMP"
 552 Prevent liblttng-ust to perform a base-address statedump on session-enable.
 553 .PP
 554 .IP "LTTNG_UST_GETCPU_PLUGIN"
 555 Used by the getcpu override plugin system. The environment variable
 556 provides the path to the shared object which will act as the getcpu override
 557 plugin. An example can be found in the lttng-ust documentation under
 558 examples/getcpu-override .
 559 .PP
 560 .IP "LTTNG_UST_CLOCK_PLUGIN"
 561 Used by the clock override plugin system. The environment variable
 562 provides the path to the shared object which will act as the clock override
 563 plugin. An example can be found in the lttng-ust documentation under
 564 doc/examples/clock-override .
 565 .PP
 566
 567 .SH "SEE ALSO"
 568
 569 .PP
 570 lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3),
 571 lttng-ust-dl(3), lttng-sessiond(8)
 572 .PP
 573
 574 .SH "COMPATIBILITY"
 575
 576 .PP
 577 Older lttng-ust libraries reject more recent, and incompatible, probe
 578 providers. Newer lttng-ust libraries accept older probe providers, even
 579 though some newer features might not be available with those providers.
 580 .PP
 581
 582 .SH "BUGS"
 583
 584 .PP
 585 LTTng-UST 2.0 and 2.1 lttng-ust libraries do not check for probe
 586 provider version compatibility. This can lead to out-of-bound accesses
 587 when using a more recent probe provider with an older lttng-ust library.
 588 These error only trigger when tracing is active. This issue has been
 589 fixed in LTTng-UST 2.2.
 590
 591 If you encounter any issues or usability problem, please report it on
 592 our mailing list <lttng-dev@lists.lttng.org> to help improve this
 593 project.
 594 .SH "CREDITS"
 595
 596 liblttng-ust is distributed under the GNU Lesser General Public License
 597 version 2.1. The headers are distributed under the MIT license.
 598 .PP
 599 See http://lttng.org for more information on the LTTng project.
 600 .PP
 601 Mailing list for support and development: <lttng-dev@lists.lttng.org>.
 602 .PP
 603 You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
 604 .PP
 605 .SH "THANKS"
 606
 607 Thanks to Ericsson for funding this work, providing real-life use-cases,
 608 and testing.
 609
 610 Special thanks to Michel Dagenais and the DORSAL laboratory at
 611 Polytechnique de Montreal for the LTTng journey.
 612 .PP
 613 .SH "AUTHORS"
 614
 615 .PP
 616 liblttng-ust was originally written by Mathieu Desnoyers, with additional
 617 contributions from various other people. It is currently maintained by
 618 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.
 619 .PP