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 "ADDING TRACEPOINTS TO YOUR CODE"
 154
 155 .nf
 156
 157 Include the provider header in each C files you plan to instrument,
 158 following the building/linking directives in the next section.
 159
 160 For instance, add within a function:
 161
 162                 tracepoint(ust_tests_hello, tptest, i, netint, values,
 163                         text, strlen(text), dbl, flt);
 164
 165 As a call to the tracepoint. It will only be activated when requested by
 166 lttng(1) through lttng-sessiond(8).
 167
 168 .fi
 169
 170 .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER"
 171
 172 .nf
 173 There are 2 ways to compile the Tracepoint Provider with the
 174 application: either statically or dynamically. Please follow
 175 carefully:
 176
 177   1.1) Compile the Tracepoint provider with the application, either
 178        directly or through a static library (.a):
 179     - Into exactly one object of your application: define
 180       "TRACEPOINT_DEFINE" and include the tracepoint provider.
 181     - Use "-I." for the compilation unit containing the tracepoint
 182       provider include (e.g. tp.c).
 183     - Link application with "-ldl".
 184     - If building the provider directly into the application,
 185       link the application with "-llttng-ust".
 186     - If building a static library for the provider, link the static
 187       library with "-lllttng-ust".
 188     - Include the tracepoint provider header into all C files using
 189       the provider.
 190     - Example:
 191         tests/hello/  hello.c tp.c ust_tests_hello.h Makefile.example
 192
 193   2) Compile the Tracepoint Provider separately from the application,
 194      using dynamic linking:
 195     - Into exactly one object of your application: define
 196       "TRACEPOINT_DEFINE" _and_ also define
 197       "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint
 198       provider header.
 199     - Include the tracepoint provider header into all instrumented C
 200       files that use the provider.
 201     - Compile the tracepoint provider with "-I.".
 202     - Link the tracepoint provider with "-llttng-ust".
 203     - Link application with "-ldl".
 204     - Set a LD_PRELOAD environment to preload the tracepoint provider
 205       shared object before starting the application when tracing is
 206       needed.
 207     - Example:
 208       - tests/demo/   demo.c  tp*.c ust_tests_demo*.h demo-trace
 209
 210   - Note about dlopen() usage: due to locking side-effects due to the
 211     way libc lazily resolves Thread-Local Storage (TLS) symbols when a
 212     library is dlopen'd, linking the tracepoint probe or liblttng-ust
 213     with dlopen() is discouraged. They should be linked with the
 214     application using "-llibname" or loaded with LD_PRELOAD.
 215   - Enable instrumentation and control tracing with the "lttng" command
 216     from lttng-tools. See lttng-tools doc/quickstart.txt.
 217
 218 .fi
 219
 220 .SH "ENVIRONMENT VARIABLES"
 221
 222 .PP
 223 .IP "LTTNG_UST_DEBUG"
 224 Activate liblttng-ust debug output.
 225 .PP
 226 .IP "LTTNG_UST_REGISTER_TIMEOUT"
 227 The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
 228 specify how long the applications should wait for sessiond
 229 "registration done" command before proceeding to execute the main
 230 program. The default is 3000ms (3 seconds). The timeout value is
 231 specified in milliseconds. The value 0 means "don't wait". The value
 232 -1 means "wait forever". Setting this environment variable to 0 is
 233 recommended for applications with time constraints on the process
 234 startup time.
 235 .PP
 236
 237 .SH "SEE ALSO"
 238
 239 .PP
 240 lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-sessiond(8)
 241 .PP
 242 .SH "BUGS"
 243
 244 .PP
 245 No knows bugs at this point.
 246
 247 If you encounter any issues or usability problem, please report it on
 248 our mailing list <lttng-dev@lists.lttng.org> to help improve this
 249 project.
 250 .SH "CREDITS"
 251
 252 liblttng-ust is distributed under the GNU Lesser General Public License
 253 version 2.1. The headers are distributed under the MIT license.
 254 .PP
 255 See http://lttng.org for more information on the LTTng project.
 256 .PP
 257 Mailing list for support and development: <lttng-dev@lists.lttng.org>.
 258 .PP
 259 You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
 260 .PP
 261 .SH "THANKS"
 262
 263 Thanks to Ericsson for funding this work, providing real-life use-cases,
 264 and testing.
 265
 266 Special thanks to Michel Dagenais and the DORSAL laboratory at
 267 Polytechnique de Montreal for the LTTng journey.
 268 .PP
 269 .SH "AUTHORS"
 270
 271 .PP
 272 liblttng-ust was originally written by Mathieu Desnoyers, with additional
 273 contributions from various other people. It is currently maintained by
 274 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.
 275 .PP