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
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, 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:
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:
47 * Must be included before include tracepoint provider
49 * ex.: project_component_event
51 * Optional company name goes here
52 * ex.: com_efficios_project_component_event
54 * In this example, "sample" is the project, and "component" is the
60 * tracepoint name, same format as sample provider. Does not
61 * need to be declared before. in this case the name is
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,
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
75 * TP_ARGS() is valid to mean no arguments
76 * TP_ARGS(void) is valid too
78 TP_ARGS(int, anint, int, netint, long *, values,
79 char *, text, size_t, textlen,
80 double, doublearg, float, floatarg),
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.
89 * ctf_integer: standard integer field.
90 * args: (type, field name, argument expression)
92 ctf_integer(int, intfield, anint)
93 ctf_integer(long, longfield, anint)
96 * ctf_integer_hex: integer field printed as hexadecimal.
97 * args: (type, field name, argument expression)
99 ctf_integer_hex(int, intfield2, anint)
102 * ctf_integer_network: integer field in network byte
103 * order. (_hex: printed as hexadecimal too)
104 * args: (type, field name, argument expression)
106 ctf_integer_network(int, netintfield, netint)
107 ctf_integer_network_hex(int, netintfieldhex, netint)
110 * ctf_array: a statically-sized array.
111 * args: (type, field name, argument expression, value)
113 ctf_array(long, arrfield1, values, 3)
116 * ctf_array_text: a statically-sized array, printed as
117 * a string. No need to be terminated by a null
119 * Behavior is undefined if "text" argument is NULL.
121 ctf_array_text(char, arrfield2, text, 10)
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.
133 ctf_sequence(char, seqfield1, text,
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.
141 ctf_sequence_text(char, seqfield2, text,
145 * ctf_string: null-terminated string.
146 * args: (field name, argument expression)
147 * Behavior is undefined if "text" argument is NULL.
149 ctf_string(stringfield, text)
152 * ctf_float: floating-point number.
153 * args: (type, field name, argument expression)
155 ctf_float(float, floatfield, floatarg)
156 ctf_float(double, doublefield, doublearg)
161 .SH "ASSIGNING LOGLEVEL TO EVENTS"
165 Optionally, a loglevel can be assigned to a TRACEPOINT_EVENT using the
168 TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >,
169 < event >, < loglevel_name >)
171 The first field is the provider name, the second field is the name of
172 the tracepoint, and the third field is the loglevel name. A
173 TRACEPOINT_EVENT should be declared prior to the the TRACEPOINT_LOGLEVEL
174 for a given tracepoint name. The TRACEPOINT_PROVIDER must be already
175 declared before declaring a TRACEPOINT_LOGLEVEL.
177 The loglevels go from 0 to 14. Higher numbers imply the most verbosity
178 (higher event throughput expected.
180 Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels
181 semantic. Loglevels 7 through 13 offer more fine-grained selection of
188 action must be taken immediately
200 normal, but significant, condition
203 informational message
206 debug information with system-level scope (set of programs)
208 TRACE_DEBUG_PROGRAM 8
209 debug information with program-level scope (set of processes)
211 TRACE_DEBUG_PROCESS 9
212 debug information with process-level scope (set of modules)
214 TRACE_DEBUG_MODULE 10
215 debug information with module (executable/library) scope (set of
219 debug information with compilation unit scope (set of functions)
221 TRACE_DEBUG_FUNCTION 12
222 debug information with function-level scope
225 debug information with line-level scope (TRACEPOINT_EVENT default)
228 debug-level message (trace_printf default)
230 See lttng(1) for information on how to use LTTng-UST loglevels.
234 .SH "ADDING TRACEPOINTS TO YOUR CODE"
238 Include the provider header in each C files you plan to instrument,
239 following the building/linking directives in the next section.
241 For instance, add within a function:
243 tracepoint(ust_tests_hello, tptest, i, netint, values,
244 text, strlen(text), dbl, flt);
246 As a call to the tracepoint. It will only be activated when requested by
247 lttng(1) through lttng-sessiond(8).
249 Even though LTTng-UST supports tracepoint() call site duplicates having
250 the same provider and event name, it is recommended to use a
251 provider event name pair only once within the source code to help
252 mapping events back to their call sites when analyzing the trace.
255 .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER"
258 There are 2 ways to compile the Tracepoint Provider with the
259 application: either statically or dynamically. Please follow
262 1.1) Compile the Tracepoint provider with the application, either
263 directly or through a static library (.a):
264 - Into exactly one object of your application: define
265 "TRACEPOINT_DEFINE" and include the tracepoint provider.
266 - Use "\-I." for the compilation unit containing the tracepoint
267 provider include (e.g. tp.c).
268 - Link application with "\-ldl".
269 - If building the provider directly into the application,
270 link the application with "\-llttng-ust".
271 - If building a static library for the provider, link the static
272 library with "\-llttng-ust".
273 - Include the tracepoint provider header into all C files using
276 - doc/examples/easy-ust/ sample.c sample_component_provider.h tp.c
278 - doc/examples/hello-static-lib/ hello.c tp.c ust_test_hello.h Makefile
280 2) Compile the Tracepoint Provider separately from the application,
281 using dynamic linking:
282 - Into exactly one object of your application: define
283 "TRACEPOINT_DEFINE" _and_ also define
284 "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint
286 - Include the tracepoint provider header into all instrumented C
287 files that use the provider.
288 - Compile the tracepoint provider with "\-I.".
289 - Link the tracepoint provider with "\-llttng-ust".
290 - Link application with "\-ldl".
291 - Set a LD_PRELOAD environment to preload the tracepoint provider
292 shared object before starting the application when tracing is
293 needed. Another way is to dlopen the tracepoint probe when needed
296 - doc/examples/demo demo.c tp*.c ust_tests_demo*.h demo-trace Makefile
298 - Note about dlclose() usage: it is not safe to use dlclose on a
299 provider shared object that is being actively used for tracing due
300 to a lack of reference counting from lttng-ust to the used shared
302 - Enable instrumentation and control tracing with the "lttng" command
303 from lttng-tools. See lttng-tools doc/quickstart.txt.
304 - Note for C++ support: although an application instrumented with
305 tracepoints can be compiled with g++, tracepoint probes should be
306 compiled with gcc (only tested with gcc so far).
310 .SH "USING LTTNG UST WITH DAEMONS"
313 Some extra care is needed when using liblttng-ust with daemon
314 applications that call fork(), clone(), or BSD rfork() without a
315 following exec() family system call. The library "liblttng-ust-fork.so"
316 needs to be preloaded for the application (launch with e.g.
317 LD_PRELOAD=liblttng-ust-fork.so appname).
324 Context information can be prepended by the tracer before each, or some,
325 events. The following context information is supported by LTTng-UST:
330 Virtual thread ID: thread ID as seen from the point of view of the
336 Virtual process ID: process ID as seen from the point of view of the
342 Thread name, as set by exec() or prctl(). It is recommended that
343 programs set their thread name with prctl() before hitting the first
344 tracepoint for that thread.
349 Pthread identifier. Can be used on architectures where pthread_t maps
350 nicely to an unsigned long type.
353 .SH "ENVIRONMENT VARIABLES"
356 .IP "LTTNG_UST_DEBUG"
357 Activate liblttng-ust debug output.
359 .IP "LTTNG_UST_REGISTER_TIMEOUT"
360 The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
361 specify how long the applications should wait for sessiond
362 "registration done" command before proceeding to execute the main
363 program. The default is 3000ms (3 seconds). The timeout value is
364 specified in milliseconds. The value 0 means "don't wait". The value
365 \-1 means "wait forever". Setting this environment variable to 0 is
366 recommended for applications with time constraints on the process
373 lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3),
380 Older lttng-ust libraries reject more recent, and incompatible, probe
381 providers. Newer lttng-ust librairies accept older probe providers, even
382 though some newer features might not be available with those providers.
388 LTTng-UST 2.0 and 2.1 lttng-ust libraries do not check for probe
389 provider version compatibility. This can lead to out-of-bound accesses
390 when using a more recent probe provider with an older lttng-ust library.
391 These error only trigger when tracing is active. This issue has been
392 fixed in LTTng-UST 2.2.
394 If you encounter any issues or usability problem, please report it on
395 our mailing list <lttng-dev@lists.lttng.org> to help improve this
399 liblttng-ust is distributed under the GNU Lesser General Public License
400 version 2.1. The headers are distributed under the MIT license.
402 See http://lttng.org for more information on the LTTng project.
404 Mailing list for support and development: <lttng-dev@lists.lttng.org>.
406 You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
410 Thanks to Ericsson for funding this work, providing real-life use-cases,
413 Special thanks to Michel Dagenais and the DORSAL laboratory at
414 Polytechnique de Montreal for the LTTng journey.
419 liblttng-ust was originally written by Mathieu Desnoyers, with additional
420 contributions from various other people. It is currently maintained by
421 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.