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