1 .TH "LTTNG-UST" "3" "February 16, 2012" "" ""
4 lttng-ust \(em Linux Trace Toolkit Next Generation User-Space Tracer 2.x
10 Link liblttng-ust.so with applications, following this manpage.
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.
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.
27 Here is the way to do it manually, without the lttng-gen-tp(1) helper
28 script, through an example:
31 .SH "CREATION OF TRACEPOINT PROVIDER"
35 To create a tracepoint provider, within a build tree similar to
36 examples/easy-ust installed with lttng-ust documentation, see
37 sample_component_provider.h for the general layout. You will need to
38 define TRACEPOINT_CREATE_PROBES before including your tracepoint
39 provider probe in one source file of your application. See tp.c from
40 easy-ust for an example of a tracepoint probe source file. This manpage
41 will focus on the various types that can be recorded into a trace
46 * provider name, not a variable but a string starting with a
47 * letter and containing either letters, numbers or underscores.
48 * Needs to be the same as TRACEPOINT_PROVIDER. Needs to
49 * follow the namespacing guide-lines in lttng/tracepoint.h:
51 * Must be included before include tracepoint provider
53 * ex.: project_component_event
55 * Optional company name goes here
56 * ex.: com_efficios_project_component_event
58 * In this example, "sample" is the project, and "component" is the
64 * tracepoint name, same format as sample provider. Does not
65 * need to be declared before. in this case the name is
71 * TP_ARGS macro contains the arguments passed for the tracepoint
72 * it is in the following format
73 * TP_ARGS(type1, name1, type2, name2, ... type10,
75 * where there can be from zero to ten elements.
76 * typeN is the datatype, such as int, struct or double **.
77 * name is the variable name (in "int myInt" the name would be
79 * TP_ARGS() is valid to mean no arguments
80 * TP_ARGS(void) is valid too
82 TP_ARGS(int, anint, int, netint, long *, values,
83 char *, text, size_t, textlen,
84 double, doublearg, float, floatarg),
87 * TP_FIELDS describes how to write the fields of the trace event.
88 * You can put expressions in the "argument expression" area,
89 * typically using the input arguments from TP_ARGS.
93 * ctf_integer: standard integer field.
94 * args: (type, field name, argument expression)
96 ctf_integer(int, intfield, anint)
97 ctf_integer(long, longfield, anint)
100 * ctf_integer_hex: integer field printed as hexadecimal.
101 * args: (type, field name, argument expression)
103 ctf_integer_hex(int, intfield2, anint)
106 * ctf_integer_network: integer field in network byte
107 * order. (_hex: printed as hexadecimal too)
108 * args: (type, field name, argument expression)
110 ctf_integer_network(int, netintfield, netint)
111 ctf_integer_network_hex(int, netintfieldhex, netint)
114 * ctf_array: a statically-sized array.
115 * args: (type, field name, argument expression, value)
117 ctf_array(long, arrfield1, values, 3)
120 * ctf_array_text: a statically-sized array, printed as
121 * a string. No need to be terminated by a null
123 * Behavior is undefined if "text" argument is NULL.
125 ctf_array_text(char, arrfield2, text, 10)
128 * ctf_sequence: a dynamically-sized array.
129 * args: (type, field name, argument expression,
130 * type of length expression, length expression)
131 * The "type of length expression" needs to be an
132 * unsigned type. As a reminder, "unsigned char" should
133 * be preferred to "char", since the signedness of
134 * "char" is implementation-defined.
135 * Behavior is undefined if "text" argument is NULL.
137 ctf_sequence(char, seqfield1, text,
141 * ctf_sequence_text: a dynamically-sized array, printed
142 * as string. No need to be null-terminated.
143 * Behavior is undefined if "text" argument is NULL.
145 ctf_sequence_text(char, seqfield2, text,
149 * ctf_string: null-terminated string.
150 * args: (field name, argument expression)
151 * Behavior is undefined if "text" argument is NULL.
153 ctf_string(stringfield, text)
156 * ctf_float: floating-point number.
157 * args: (type, field name, argument expression)
159 ctf_float(float, floatfield, floatarg)
160 ctf_float(double, doublefield, doublearg)
164 There can be an arbitrary number of tracepoint providers within an
165 application, but they must each have their own provider name. Duplicate
166 provider names are not allowed.
170 .SH "ASSIGNING LOGLEVEL TO EVENTS"
174 Optionally, a loglevel can be assigned to a TRACEPOINT_EVENT using the
177 TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >,
178 < event >, < loglevel_name >)
180 The first field is the provider name, the second field is the name of
181 the tracepoint, and the third field is the loglevel name. A
182 TRACEPOINT_EVENT should be declared prior to the the TRACEPOINT_LOGLEVEL
183 for a given tracepoint name. The TRACEPOINT_PROVIDER must be already
184 declared before declaring a TRACEPOINT_LOGLEVEL.
186 The loglevels go from 0 to 14. Higher numbers imply the most verbosity
187 (higher event throughput expected.
189 Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels
190 semantic. Loglevels 7 through 13 offer more fine-grained selection of
197 action must be taken immediately
209 normal, but significant, condition
212 informational message
215 debug information with system-level scope (set of programs)
217 TRACE_DEBUG_PROGRAM 8
218 debug information with program-level scope (set of processes)
220 TRACE_DEBUG_PROCESS 9
221 debug information with process-level scope (set of modules)
223 TRACE_DEBUG_MODULE 10
224 debug information with module (executable/library) scope (set of
228 debug information with compilation unit scope (set of functions)
230 TRACE_DEBUG_FUNCTION 12
231 debug information with function-level scope
234 debug information with line-level scope (TRACEPOINT_EVENT default)
237 debug-level message (trace_printf default)
239 See lttng(1) for information on how to use LTTng-UST loglevels.
243 .SH "ADDING TRACEPOINTS TO YOUR CODE"
247 Include the provider header in each C files you plan to instrument,
248 following the building/linking directives in the next section.
250 For instance, add within a function:
252 tracepoint(ust_tests_hello, tptest, i, netint, values,
253 text, strlen(text), dbl, flt);
255 As a call to the tracepoint. It will only be activated when requested by
256 lttng(1) through lttng-sessiond(8).
258 Even though LTTng-UST supports tracepoint() call site duplicates having
259 the same provider and event name, it is recommended to use a
260 provider event name pair only once within the source code to help
261 map events back to their call sites when analyzing the trace.
264 .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER"
267 There are 2 ways to compile the Tracepoint Provider with the
268 application: either statically or dynamically. Please follow
271 1.1) Compile the Tracepoint provider with the application, either
272 directly or through a static library (.a):
273 - Into exactly one object of your application: define
274 "TRACEPOINT_DEFINE" and include the tracepoint provider.
275 - Use "\-I." for the compilation unit containing the tracepoint
276 provider include (e.g. tp.c).
277 - Link application with "\-ldl".
278 - If building the provider directly into the application,
279 link the application with "\-llttng-ust".
280 - If building a static library for the provider, link the static
281 library with "\-llttng-ust".
282 - Include the tracepoint provider header into all C files using
285 - doc/examples/easy-ust/ sample.c sample_component_provider.h tp.c
287 - doc/examples/hello-static-lib/ hello.c tp.c ust_test_hello.h Makefile
289 2) Compile the Tracepoint Provider separately from the application,
290 using dynamic linking:
291 - Into exactly one object of your application: define
292 "TRACEPOINT_DEFINE" _and_ also define
293 "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint
295 - Include the tracepoint provider header into all instrumented C
296 files that use the provider.
297 - Compile the tracepoint provider with "\-I.".
298 - Link the tracepoint provider with "\-llttng-ust".
299 - Link application with "\-ldl".
300 - Set a LD_PRELOAD environment to preload the tracepoint provider
301 shared object before starting the application when tracing is
302 needed. Another way is to dlopen the tracepoint probe when needed
305 - doc/examples/demo demo.c tp*.c ust_tests_demo*.h demo-trace Makefile
307 - Note about dlclose() usage: it is not safe to use dlclose on a
308 provider shared object that is being actively used for tracing due
309 to a lack of reference counting from lttng-ust to the used shared
311 - Enable instrumentation and control tracing with the "lttng" command
312 from lttng-tools. See lttng-tools doc/quickstart.txt.
313 - Note for C++ support: although an application instrumented with
314 tracepoints can be compiled with g++, tracepoint probes should be
315 compiled with gcc (only tested with gcc so far).
319 .SH "USING LTTNG UST WITH DAEMONS"
322 Some extra care is needed when using liblttng-ust with daemon
323 applications that call fork(), clone(), or BSD rfork() without a
324 following exec() family system call. The library "liblttng-ust-fork.so"
325 needs to be preloaded for the application (launch with e.g.
326 LD_PRELOAD=liblttng-ust-fork.so appname).
333 Context information can be prepended by the tracer before each, or some,
334 events. The following context information is supported by LTTng-UST:
339 Virtual thread ID: thread ID as seen from the point of view of the
345 Virtual process ID: process ID as seen from the point of view of the
351 Instruction pointer: Enables recording of the exact location where a tracepoint
352 was emitted. Can be used to reverse-lookup the source location that caused the
358 Thread name, as set by exec() or prctl(). It is recommended that
359 programs set their thread name with prctl() before hitting the first
360 tracepoint for that thread.
365 Pthread identifier. Can be used on architectures where pthread_t maps
366 nicely to an unsigned long type.
369 .SH "BASE ADDRESS STATEDUMP"
372 If an application that uses liblttng-ust.so becomes part of a session,
373 information about its currently loaded shared objects will be traced to the
374 session at session-enable time. To record this information, the following event
377 .IP "ust_baddr_statedump:soinfo"
378 This event is used to trace a currently loaded shared object. The base address
379 (where the dynamic linker has placed the shared object) is recorded in the
380 "baddr" field. The path to the shared object gets recorded in the
381 "sopath" field (as string). The file size of the loaded object (in
382 bytes) is recorded to the "size" field and its time of last modification
383 (in seconds since Epoch) is recorded in the "mtime" field.
385 If the event above is enabled, a series of "ust_baddr_statedump:soinfo"
386 events is recorded at session-enable time. It represents the state of
387 currently loaded shared objects for the traced process. If this
388 information gets combined with the lttng-ust-dl(3) instrumentation, all
389 aspects of dynamic loading that are relevant for symbol and
390 line number lookup are traced by LTTng.
392 .SH "ENVIRONMENT VARIABLES"
395 .IP "LTTNG_UST_DEBUG"
396 Activate liblttng-ust debug output.
398 .IP "LTTNG_UST_REGISTER_TIMEOUT"
399 The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
400 specify how long the applications should wait for sessiond
401 "registration done" command before proceeding to execute the main
402 program. The default is 3000ms (3 seconds). The timeout value is
403 specified in milliseconds. The value 0 means "don't wait". The value
404 \-1 means "wait forever". Setting this environment variable to 0 is
405 recommended for applications with time constraints on the process
408 .IP "LTTNG_UST_WITHOUT_BADDR_STATEDUMP"
409 Prevent liblttng-ust to perform a base-address statedump on session-enable.
415 lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3),
416 lttng-ust-dl(3), lttng-sessiond(8)
422 Older lttng-ust libraries reject more recent, and incompatible, probe
423 providers. Newer lttng-ust libraries accept older probe providers, even
424 though some newer features might not be available with those providers.
430 LTTng-UST 2.0 and 2.1 lttng-ust libraries do not check for probe
431 provider version compatibility. This can lead to out-of-bound accesses
432 when using a more recent probe provider with an older lttng-ust library.
433 These error only trigger when tracing is active. This issue has been
434 fixed in LTTng-UST 2.2.
436 If you encounter any issues or usability problem, please report it on
437 our mailing list <lttng-dev@lists.lttng.org> to help improve this
441 liblttng-ust is distributed under the GNU Lesser General Public License
442 version 2.1. The headers are distributed under the MIT license.
444 See http://lttng.org for more information on the LTTng project.
446 Mailing list for support and development: <lttng-dev@lists.lttng.org>.
448 You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
452 Thanks to Ericsson for funding this work, providing real-life use-cases,
455 Special thanks to Michel Dagenais and the DORSAL laboratory at
456 Polytechnique de Montreal for the LTTng journey.
461 liblttng-ust was originally written by Mathieu Desnoyers, with additional
462 contributions from various other people. It is currently maintained by
463 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.