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