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