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