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
   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                  */
 120                 ctf_array_text(char, arrfield2, text, 10)
 121
 122                 /*
 123                  * ctf_sequence: a dynamically-sized array.
 124                  * args: (type, field name, argument expression,
 125                  *      type of length expression, length expression)
 126                  */
 127                 ctf_sequence(char, seqfield1, text,
 128                              size_t, textlen)
 129
 130                 /*
 131                  * ctf_sequence_text: a dynamically-sized array, printed
 132                  * as string. No need to be null-terminated.
 133                  */
 134                 ctf_sequence_text(char, seqfield2, text,
 135                              size_t, textlen)
 136
 137                 /*
 138                  * ctf_string: null-terminated string.
 139                  * args: (field name, argument expression)
 140                  */
 141                 ctf_string(stringfield, text)
 142
 143                 /*
 144                  * ctf_float: floating-point number.
 145                  * args: (type, field name, argument expression)
 146                  */
 147                 ctf_float(float, floatfield, floatarg)
 148                 ctf_float(double, doublefield, doublearg)
 149         )
 150 )
 151
 152 There can be an arbitrary number of tracepoint providers within an
 153 application, but they must each have their own provider name. Duplicate
 154 provider names are not allowed.
 155
 156 .fi
 157
 158 .SH "ASSIGNING LOGLEVEL TO EVENTS"
 159
 160 .nf
 161
 162 Optionally, a loglevel can be assigned to a TRACEPOINT_EVENT using the
 163 following construct:
 164
 165         TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >,
 166                 < event >, < loglevel_name >)
 167
 168  The first field is the provider name, the second field is the name of
 169 the tracepoint, and the third field is the loglevel name.  A
 170 TRACEPOINT_EVENT should be declared prior to the the TRACEPOINT_LOGLEVEL
 171 for a given tracepoint name. The TRACEPOINT_PROVIDER must be already
 172 declared before declaring a TRACEPOINT_LOGLEVEL.
 173
 174 The loglevels go from 0 to 14. Higher numbers imply the most verbosity
 175 (higher event throughput expected.
 176
 177 Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels
 178 semantic. Loglevels 7 through 13 offer more fine-grained selection of
 179 debug information.
 180
 181    TRACE_EMERG           0
 182    system is unusable
 183
 184    TRACE_ALERT           1
 185    action must be taken immediately
 186
 187    TRACE_CRIT            2
 188    critical conditions
 189
 190    TRACE_ERR             3
 191    error conditions
 192
 193    TRACE_WARNING         4
 194    warning conditions
 195
 196    TRACE_NOTICE          5
 197    normal, but significant, condition
 198
 199    TRACE_INFO            6
 200    informational message
 201
 202    TRACE_DEBUG_SYSTEM    7
 203    debug information with system-level scope (set of programs)
 204
 205    TRACE_DEBUG_PROGRAM   8
 206    debug information with program-level scope (set of processes)
 207
 208    TRACE_DEBUG_PROCESS   9
 209    debug information with process-level scope (set of modules)
 210
 211    TRACE_DEBUG_MODULE    10
 212    debug information with module (executable/library) scope (set of
 213    units)
 214
 215    TRACE_DEBUG_UNIT      11
 216    debug information with compilation unit scope (set of functions)
 217
 218    TRACE_DEBUG_FUNCTION  12
 219    debug information with function-level scope
 220
 221    TRACE_DEBUG_LINE      13
 222    debug information with line-level scope (TRACEPOINT_EVENT default)
 223
 224    TRACE_DEBUG           14
 225    debug-level message (trace_printf default)
 226
 227 See lttng(1) for information on how to use LTTng-UST loglevels.
 228
 229 .fi
 230
 231 .SH "ADDING TRACEPOINTS TO YOUR CODE"
 232
 233 .nf
 234
 235 Include the provider header in each C files you plan to instrument,
 236 following the building/linking directives in the next section.
 237
 238 For instance, add within a function:
 239
 240                 tracepoint(ust_tests_hello, tptest, i, netint, values,
 241                         text, strlen(text), dbl, flt);
 242
 243 As a call to the tracepoint. It will only be activated when requested by
 244 lttng(1) through lttng-sessiond(8).
 245
 246 Even though LTTng-UST supports tracepoint() call site duplicates having
 247 the same provider and event name, it is recommended to use a
 248 provider event name pair only once within the source code to help
 249 mapping events back to their call sites when analyzing the trace.
 250 .fi
 251
 252 .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER"
 253
 254 .nf
 255 There are 2 ways to compile the Tracepoint Provider with the
 256 application: either statically or dynamically. Please follow
 257 carefully:
 258
 259   1.1) Compile the Tracepoint provider with the application, either
 260        directly or through a static library (.a):
 261     - Into exactly one object of your application: define
 262       "TRACEPOINT_DEFINE" and include the tracepoint provider.
 263     - Use "\-I." for the compilation unit containing the tracepoint
 264       provider include (e.g. tp.c).
 265     - Link application with "\-ldl".
 266     - If building the provider directly into the application,
 267       link the application with "\-llttng-ust".
 268     - If building a static library for the provider, link the static
 269       library with "\-llttng-ust".
 270     - Include the tracepoint provider header into all C files using
 271       the provider.
 272     - Example:
 273       - tests/hello/  hello.c tp.c ust_tests_hello.h Makefile.example
 274
 275   2) Compile the Tracepoint Provider separately from the application,
 276      using dynamic linking:
 277     - Into exactly one object of your application: define
 278       "TRACEPOINT_DEFINE" _and_ also define
 279       "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint
 280       provider header.
 281     - Include the tracepoint provider header into all instrumented C
 282       files that use the provider.
 283     - Compile the tracepoint provider with "\-I.".
 284     - Link the tracepoint provider with "\-llttng-ust".
 285     - Link application with "\-ldl".
 286     - Set a LD_PRELOAD environment to preload the tracepoint provider
 287       shared object before starting the application when tracing is
 288       needed. Another way is to dlopen the tracepoint probe when needed
 289       by the application.
 290     - Example:
 291       - tests/demo/   demo.c  tp*.c ust_tests_demo*.h demo-trace
 292
 293   - Note about dlclose() usage: it is not safe to use dlclose on a
 294     provider shared object that is being actively used for tracing due
 295     to a lack of reference counting from lttng-ust to the used shared
 296     object.
 297   - Enable instrumentation and control tracing with the "lttng" command
 298     from lttng-tools. See lttng-tools doc/quickstart.txt.
 299   - Note for C++ support: although an application instrumented with
 300     tracepoints can be compiled with g++, tracepoint probes should be
 301     compiled with gcc (only tested with gcc so far).
 302
 303 .fi
 304
 305 .SH "USING LTTNG UST WITH DAEMONS"
 306
 307 .nf
 308 Some extra care is needed when using liblttng-ust with daemon
 309 applications that call fork(), clone(), or BSD rfork() without a
 310 following exec() family system call. The library "liblttng-ust-fork.so"
 311 needs to be preloaded for the application (launch with e.g.
 312 LD_PRELOAD=liblttng-ust-fork.so appname).
 313
 314 .fi
 315
 316 .SH "CONTEXT"
 317
 318 .PP
 319 Context information can be prepended by the tracer before each, or some,
 320 events. The following context information is supported by LTTng-UST:
 321 .PP
 322
 323 .PP
 324 .IP "vtid"
 325 Virtual thread ID: thread ID as seen from the point of view of the
 326 process namespace.
 327 .PP
 328
 329 .PP
 330 .IP "vpid"
 331 Virtual process ID: process ID as seen from the point of view of the
 332 process namespace.
 333 .PP
 334
 335 .PP
 336 .IP "procname"
 337 Thread name, as set by exec() or prctl(). It is recommended that
 338 programs set their thread name with prctl() before hitting the first
 339 tracepoint for that thread.
 340 .PP
 341
 342 .PP
 343 .IP "pthread_id"
 344 Pthread identifier. Can be used on architectures where pthread_t maps
 345 nicely to an unsigned long type.
 346 .PP
 347
 348 .SH "ENVIRONMENT VARIABLES"
 349
 350 .PP
 351 .IP "LTTNG_UST_DEBUG"
 352 Activate liblttng-ust debug output.
 353 .PP
 354 .IP "LTTNG_UST_REGISTER_TIMEOUT"
 355 The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
 356 specify how long the applications should wait for sessiond
 357 "registration done" command before proceeding to execute the main
 358 program. The default is 3000ms (3 seconds). The timeout value is
 359 specified in milliseconds. The value 0 means "don't wait". The value
 360 \-1 means "wait forever". Setting this environment variable to 0 is
 361 recommended for applications with time constraints on the process
 362 startup time.
 363 .PP
 364
 365 .SH "SEE ALSO"
 366
 367 .PP
 368 lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-sessiond(8)
 369 .PP
 370
 371 .SH "COMPATIBILITY"
 372
 373 .PP
 374 Older lttng-ust libraries reject more recent, and incompatible, probe
 375 providers. Newer lttng-ust librairies accept older probe providers, even
 376 though some newer features might not be available with those providers.
 377 .PP
 378
 379 .SH "BUGS"
 380
 381 .PP
 382 LTTng-UST 2.0 and 2.1 lttng-ust libraries do not check for probe
 383 provider version compatibility. This can lead to out-of-bound accesses
 384 when using a more recent probe provider with an older lttng-ust library.
 385 These error only trigger when tracing is active. This issue has been
 386 fixed in LTTng-UST 2.2.
 387
 388 If you encounter any issues or usability problem, please report it on
 389 our mailing list <lttng-dev@lists.lttng.org> to help improve this
 390 project.
 391 .SH "CREDITS"
 392
 393 liblttng-ust is distributed under the GNU Lesser General Public License
 394 version 2.1. The headers are distributed under the MIT license.
 395 .PP
 396 See http://lttng.org for more information on the LTTng project.
 397 .PP
 398 Mailing list for support and development: <lttng-dev@lists.lttng.org>.
 399 .PP
 400 You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
 401 .PP
 402 .SH "THANKS"
 403
 404 Thanks to Ericsson for funding this work, providing real-life use-cases,
 405 and testing.
 406
 407 Special thanks to Michel Dagenais and the DORSAL laboratory at
 408 Polytechnique de Montreal for the LTTng journey.
 409 .PP
 410 .SH "AUTHORS"
 411
 412 .PP
 413 liblttng-ust was originally written by Mathieu Desnoyers, with additional
 414 contributions from various other people. It is currently maintained by
 415 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.
 416 .PP