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