Commit | Line | Data |
---|---|---|
eba411c6 MD |
1 | .TH "LTTNG-UST" "3" "February 16, 2012" "" "" |
2 | ||
3 | .SH "NAME" | |
77ca1460 | 4 | lttng-ust \(em Linux Trace Toolkit Next Generation User-Space Tracer 2.x |
eba411c6 MD |
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 | |
7c501923 | 15 | LTTng-UST, the Linux Trace Toolkit Next Generation Userspace Tracer, is a |
eba411c6 MD |
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 | |
dfc45f18 MD |
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 | |
42 | event: | |
eba411c6 MD |
43 | |
44 | TRACEPOINT_EVENT( | |
45 | /* | |
46 | * provider name, not a variable but a string starting with a | |
a106a9f8 | 47 | * letter and containing either letters, numbers or underscores. |
eba411c6 MD |
48 | * Needs to be the same as TRACEPOINT_PROVIDER. Needs to |
49 | * follow the namespacing guide-lines in lttng/tracepoint.h: | |
a106a9f8 JG |
50 | * |
51 | * Must be included before include tracepoint provider | |
eba411c6 MD |
52 | * ex.: project_event |
53 | * ex.: project_component_event | |
54 | * | |
55 | * Optional company name goes here | |
56 | * ex.: com_efficios_project_component_event | |
57 | * | |
58 | * In this example, "sample" is the project, and "component" is the | |
59 | * component. | |
60 | */ | |
61 | sample_component, | |
62 | ||
63 | /* | |
64 | * tracepoint name, same format as sample provider. Does not | |
65 | * need to be declared before. in this case the name is | |
a106a9f8 | 66 | * "message" |
eba411c6 MD |
67 | */ |
68 | message, | |
69 | ||
70 | /* | |
a106a9f8 | 71 | * TP_ARGS macro contains the arguments passed for the tracepoint |
eba411c6 MD |
72 | * it is in the following format |
73 | * TP_ARGS(type1, name1, type2, name2, ... type10, | |
74 | name10) | |
a106a9f8 JG |
75 | * where there can be from zero to ten elements. |
76 | * typeN is the datatype, such as int, struct or double **. | |
eba411c6 | 77 | * name is the variable name (in "int myInt" the name would be |
a106a9f8 | 78 | * myint) |
eba411c6 MD |
79 | * TP_ARGS() is valid to mean no arguments |
80 | * TP_ARGS(void) is valid too | |
81 | */ | |
82 | TP_ARGS(int, anint, int, netint, long *, values, | |
83 | char *, text, size_t, textlen, | |
84 | double, doublearg, float, floatarg), | |
85 | ||
86 | /* | |
a106a9f8 | 87 | * TP_FIELDS describes how to write the fields of the trace event. |
eba411c6 MD |
88 | * You can put expressions in the "argument expression" area, |
89 | * typically using the input arguments from TP_ARGS. | |
90 | */ | |
91 | TP_FIELDS( | |
92 | /* | |
93 | * ctf_integer: standard integer field. | |
94 | * args: (type, field name, argument expression) | |
95 | */ | |
96 | ctf_integer(int, intfield, anint) | |
97 | ctf_integer(long, longfield, anint) | |
98 | ||
99 | /* | |
100 | * ctf_integer_hex: integer field printed as hexadecimal. | |
101 | * args: (type, field name, argument expression) | |
102 | */ | |
103 | ctf_integer_hex(int, intfield2, anint) | |
104 | ||
105 | /* | |
106 | * ctf_integer_network: integer field in network byte | |
107 | * order. (_hex: printed as hexadecimal too) | |
108 | * args: (type, field name, argument expression) | |
109 | */ | |
110 | ctf_integer_network(int, netintfield, netint) | |
111 | ctf_integer_network_hex(int, netintfieldhex, netint) | |
112 | ||
113 | /* | |
114 | * ctf_array: a statically-sized array. | |
115 | * args: (type, field name, argument expression, value) | |
a106a9f8 | 116 | */ |
eba411c6 MD |
117 | ctf_array(long, arrfield1, values, 3) |
118 | ||
119 | /* | |
120 | * ctf_array_text: a statically-sized array, printed as | |
121 | * a string. No need to be terminated by a null | |
122 | * character. | |
2f65f1f5 | 123 | * Behavior is undefined if "text" argument is NULL. |
a106a9f8 | 124 | */ |
eba411c6 MD |
125 | ctf_array_text(char, arrfield2, text, 10) |
126 | ||
127 | /* | |
128 | * ctf_sequence: a dynamically-sized array. | |
129 | * args: (type, field name, argument expression, | |
130 | * type of length expression, length expression) | |
efbad5cc MD |
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. | |
2f65f1f5 | 135 | * Behavior is undefined if "text" argument is NULL. |
a106a9f8 | 136 | */ |
eba411c6 MD |
137 | ctf_sequence(char, seqfield1, text, |
138 | size_t, textlen) | |
139 | ||
140 | /* | |
141 | * ctf_sequence_text: a dynamically-sized array, printed | |
142 | * as string. No need to be null-terminated. | |
2f65f1f5 | 143 | * Behavior is undefined if "text" argument is NULL. |
eba411c6 MD |
144 | */ |
145 | ctf_sequence_text(char, seqfield2, text, | |
146 | size_t, textlen) | |
147 | ||
148 | /* | |
149 | * ctf_string: null-terminated string. | |
150 | * args: (field name, argument expression) | |
2f65f1f5 | 151 | * Behavior is undefined if "text" argument is NULL. |
eba411c6 MD |
152 | */ |
153 | ctf_string(stringfield, text) | |
154 | ||
155 | /* | |
156 | * ctf_float: floating-point number. | |
157 | * args: (type, field name, argument expression) | |
158 | */ | |
159 | ctf_float(float, floatfield, floatarg) | |
160 | ctf_float(double, doublefield, doublearg) | |
161 | ) | |
162 | ) | |
7d381d6e MD |
163 | |
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. | |
167 | ||
eba411c6 MD |
168 | .fi |
169 | ||
5883c06f MD |
170 | .SH "ASSIGNING LOGLEVEL TO EVENTS" |
171 | ||
172 | .nf | |
173 | ||
174 | Optionally, a loglevel can be assigned to a TRACEPOINT_EVENT using the | |
175 | following construct: | |
176 | ||
177 | TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >, | |
178 | < event >, < loglevel_name >) | |
179 | ||
7c501923 | 180 | The first field is the provider name, the second field is the name of |
5883c06f MD |
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. | |
185 | ||
186 | The loglevels go from 0 to 14. Higher numbers imply the most verbosity | |
187 | (higher event throughput expected. | |
a106a9f8 | 188 | |
5883c06f MD |
189 | Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels |
190 | semantic. Loglevels 7 through 13 offer more fine-grained selection of | |
191 | debug information. | |
a106a9f8 | 192 | |
5883c06f MD |
193 | TRACE_EMERG 0 |
194 | system is unusable | |
a106a9f8 | 195 | |
5883c06f MD |
196 | TRACE_ALERT 1 |
197 | action must be taken immediately | |
a106a9f8 | 198 | |
5883c06f MD |
199 | TRACE_CRIT 2 |
200 | critical conditions | |
a106a9f8 | 201 | |
5883c06f MD |
202 | TRACE_ERR 3 |
203 | error conditions | |
a106a9f8 | 204 | |
5883c06f MD |
205 | TRACE_WARNING 4 |
206 | warning conditions | |
a106a9f8 | 207 | |
5883c06f MD |
208 | TRACE_NOTICE 5 |
209 | normal, but significant, condition | |
a106a9f8 | 210 | |
5883c06f MD |
211 | TRACE_INFO 6 |
212 | informational message | |
a106a9f8 | 213 | |
5883c06f MD |
214 | TRACE_DEBUG_SYSTEM 7 |
215 | debug information with system-level scope (set of programs) | |
a106a9f8 | 216 | |
5883c06f MD |
217 | TRACE_DEBUG_PROGRAM 8 |
218 | debug information with program-level scope (set of processes) | |
a106a9f8 | 219 | |
5883c06f MD |
220 | TRACE_DEBUG_PROCESS 9 |
221 | debug information with process-level scope (set of modules) | |
a106a9f8 | 222 | |
5883c06f MD |
223 | TRACE_DEBUG_MODULE 10 |
224 | debug information with module (executable/library) scope (set of | |
225 | units) | |
a106a9f8 | 226 | |
5883c06f MD |
227 | TRACE_DEBUG_UNIT 11 |
228 | debug information with compilation unit scope (set of functions) | |
a106a9f8 | 229 | |
5883c06f MD |
230 | TRACE_DEBUG_FUNCTION 12 |
231 | debug information with function-level scope | |
a106a9f8 | 232 | |
5883c06f MD |
233 | TRACE_DEBUG_LINE 13 |
234 | debug information with line-level scope (TRACEPOINT_EVENT default) | |
a106a9f8 | 235 | |
5883c06f MD |
236 | TRACE_DEBUG 14 |
237 | debug-level message (trace_printf default) | |
238 | ||
239 | See lttng(1) for information on how to use LTTng-UST loglevels. | |
240 | ||
241 | .fi | |
242 | ||
eba411c6 MD |
243 | .SH "ADDING TRACEPOINTS TO YOUR CODE" |
244 | ||
245 | .nf | |
246 | ||
247 | Include the provider header in each C files you plan to instrument, | |
248 | following the building/linking directives in the next section. | |
249 | ||
250 | For instance, add within a function: | |
251 | ||
252 | tracepoint(ust_tests_hello, tptest, i, netint, values, | |
253 | text, strlen(text), dbl, flt); | |
254 | ||
255 | As a call to the tracepoint. It will only be activated when requested by | |
256 | lttng(1) through lttng-sessiond(8). | |
257 | ||
d646ca64 MD |
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 | |
7c501923 | 261 | map events back to their call sites when analyzing the trace. |
eba411c6 MD |
262 | .fi |
263 | ||
264 | .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER" | |
265 | ||
266 | .nf | |
267 | There are 2 ways to compile the Tracepoint Provider with the | |
268 | application: either statically or dynamically. Please follow | |
269 | carefully: | |
270 | ||
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. | |
9b6435af | 275 | - Use "\-I." for the compilation unit containing the tracepoint |
eba411c6 | 276 | provider include (e.g. tp.c). |
9b6435af | 277 | - Link application with "\-ldl". |
eba411c6 | 278 | - If building the provider directly into the application, |
9b6435af | 279 | link the application with "\-llttng-ust". |
eba411c6 | 280 | - If building a static library for the provider, link the static |
38f5f440 | 281 | library with "\-llttng-ust". |
eba411c6 MD |
282 | - Include the tracepoint provider header into all C files using |
283 | the provider. | |
a106a9f8 JG |
284 | - Examples: |
285 | - doc/examples/easy-ust/ sample.c sample_component_provider.h tp.c | |
286 | Makefile | |
287 | - doc/examples/hello-static-lib/ hello.c tp.c ust_test_hello.h Makefile | |
eba411c6 MD |
288 | |
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 | |
294 | provider header. | |
295 | - Include the tracepoint provider header into all instrumented C | |
296 | files that use the provider. | |
9b6435af AM |
297 | - Compile the tracepoint provider with "\-I.". |
298 | - Link the tracepoint provider with "\-llttng-ust". | |
299 | - Link application with "\-ldl". | |
eba411c6 MD |
300 | - Set a LD_PRELOAD environment to preload the tracepoint provider |
301 | shared object before starting the application when tracing is | |
13fb2d2c JG |
302 | needed. Another way is to dlopen the tracepoint probe when needed |
303 | by the application. | |
eba411c6 | 304 | - Example: |
a106a9f8 | 305 | - doc/examples/demo demo.c tp*.c ust_tests_demo*.h demo-trace Makefile |
eba411c6 | 306 | |
13fb2d2c JG |
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 | |
310 | object. | |
eba411c6 MD |
311 | - Enable instrumentation and control tracing with the "lttng" command |
312 | from lttng-tools. See lttng-tools doc/quickstart.txt. | |
2bda849d MD |
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). | |
eba411c6 MD |
316 | |
317 | .fi | |
318 | ||
0a7c55a5 MD |
319 | .SH "USING LTTNG UST WITH DAEMONS" |
320 | ||
321 | .nf | |
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). | |
327 | ||
328 | .fi | |
329 | ||
94c9c48d MD |
330 | .SH "CONTEXT" |
331 | ||
332 | .PP | |
333 | Context information can be prepended by the tracer before each, or some, | |
334 | events. The following context information is supported by LTTng-UST: | |
335 | .PP | |
336 | ||
337 | .PP | |
338 | .IP "vtid" | |
339 | Virtual thread ID: thread ID as seen from the point of view of the | |
340 | process namespace. | |
341 | .PP | |
342 | ||
343 | .PP | |
344 | .IP "vpid" | |
345 | Virtual process ID: process ID as seen from the point of view of the | |
346 | process namespace. | |
347 | .PP | |
348 | ||
f6df8626 PW |
349 | .PP |
350 | .IP "ip" | |
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 | |
353 | event to be emitted. | |
354 | .PP | |
355 | ||
94c9c48d MD |
356 | .PP |
357 | .IP "procname" | |
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. | |
361 | .PP | |
362 | ||
363 | .PP | |
364 | .IP "pthread_id" | |
365 | Pthread identifier. Can be used on architectures where pthread_t maps | |
366 | nicely to an unsigned long type. | |
367 | .PP | |
368 | ||
b11abb67 | 369 | .SH "BASE ADDRESS STATEDUMP (Experimental feature)" |
f6df8626 PW |
370 | |
371 | .PP | |
b11abb67 PW |
372 | Warning: This is an experimental feature known to cause deadlocks when the |
373 | traced application uses fork, clone or daemon. Only use it for debugging and | |
374 | testing. Do NOT use it in production. | |
375 | ||
f6df8626 PW |
376 | If an application that uses liblttng-ust.so becomes part of a session, |
377 | information about its currently loaded shared objects will be traced to the | |
378 | session at session-enable time. To record this information, the following event | |
379 | needs to be enabled: | |
380 | .PP | |
381 | .IP "ust_baddr_statedump:soinfo" | |
382 | This event is used to trace a currently loaded shared object. The base address | |
383 | (where the dynamic linker has placed the shared object) is recorded in the | |
6d262185 MD |
384 | "baddr" field. The path to the shared object gets recorded in the |
385 | "sopath" field (as string). The file size of the loaded object (in | |
386 | bytes) is recorded to the "size" field and its time of last modification | |
387 | (in seconds since Epoch) is recorded in the "mtime" field. | |
f6df8626 | 388 | .PP |
6d262185 MD |
389 | If the event above is enabled, a series of "ust_baddr_statedump:soinfo" |
390 | events is recorded at session-enable time. It represents the state of | |
391 | currently loaded shared objects for the traced process. If this | |
392 | information gets combined with the lttng-ust-dl(3) instrumentation, all | |
393 | aspects of dynamic loading that are relevant for symbol and | |
394 | line number lookup are traced by LTTng. | |
f6df8626 | 395 | .PP |
eba411c6 MD |
396 | .SH "ENVIRONMENT VARIABLES" |
397 | ||
398 | .PP | |
399 | .IP "LTTNG_UST_DEBUG" | |
400 | Activate liblttng-ust debug output. | |
401 | .PP | |
402 | .IP "LTTNG_UST_REGISTER_TIMEOUT" | |
403 | The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to | |
404 | specify how long the applications should wait for sessiond | |
405 | "registration done" command before proceeding to execute the main | |
406 | program. The default is 3000ms (3 seconds). The timeout value is | |
407 | specified in milliseconds. The value 0 means "don't wait". The value | |
9b6435af | 408 | \-1 means "wait forever". Setting this environment variable to 0 is |
eba411c6 MD |
409 | recommended for applications with time constraints on the process |
410 | startup time. | |
411 | .PP | |
b11abb67 PW |
412 | .IP "LTTNG_UST_WITH_EXPERIMENTAL_BADDR_STATEDUMP" |
413 | Experimentally allow liblttng-ust to perform a base-address statedump on session-enable. | |
f6df8626 | 414 | .PP |
eba411c6 MD |
415 | |
416 | .SH "SEE ALSO" | |
417 | ||
418 | .PP | |
d1eaa4d7 | 419 | lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3), |
f6df8626 | 420 | lttng-ust-dl(3), lttng-sessiond(8) |
eba411c6 | 421 | .PP |
ff42aeef MD |
422 | |
423 | .SH "COMPATIBILITY" | |
424 | ||
425 | .PP | |
426 | Older lttng-ust libraries reject more recent, and incompatible, probe | |
cf949d07 | 427 | providers. Newer lttng-ust libraries accept older probe providers, even |
ff42aeef MD |
428 | though some newer features might not be available with those providers. |
429 | .PP | |
430 | ||
eba411c6 MD |
431 | .SH "BUGS" |
432 | ||
433 | .PP | |
ff42aeef MD |
434 | LTTng-UST 2.0 and 2.1 lttng-ust libraries do not check for probe |
435 | provider version compatibility. This can lead to out-of-bound accesses | |
436 | when using a more recent probe provider with an older lttng-ust library. | |
437 | These error only trigger when tracing is active. This issue has been | |
438 | fixed in LTTng-UST 2.2. | |
eba411c6 MD |
439 | |
440 | If you encounter any issues or usability problem, please report it on | |
441 | our mailing list <lttng-dev@lists.lttng.org> to help improve this | |
442 | project. | |
443 | .SH "CREDITS" | |
444 | ||
445 | liblttng-ust is distributed under the GNU Lesser General Public License | |
446 | version 2.1. The headers are distributed under the MIT license. | |
447 | .PP | |
448 | See http://lttng.org for more information on the LTTng project. | |
449 | .PP | |
450 | Mailing list for support and development: <lttng-dev@lists.lttng.org>. | |
451 | .PP | |
452 | You can find us on IRC server irc.oftc.net (OFTC) in #lttng. | |
453 | .PP | |
454 | .SH "THANKS" | |
455 | ||
456 | Thanks to Ericsson for funding this work, providing real-life use-cases, | |
457 | and testing. | |
458 | ||
459 | Special thanks to Michel Dagenais and the DORSAL laboratory at | |
460 | Polytechnique de Montreal for the LTTng journey. | |
461 | .PP | |
462 | .SH "AUTHORS" | |
463 | ||
464 | .PP | |
465 | liblttng-ust was originally written by Mathieu Desnoyers, with additional | |
466 | contributions from various other people. It is currently maintained by | |
467 | Mathieu Desnoyers <mathieu.desnoyers@efficios.com>. | |
468 | .PP |