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 | ||
641c659a MD |
20 | .SH "USAGE WITH TRACEF" |
21 | .PP | |
22 | The simplest way to add instrumentation to your code is by far the | |
fc0ec7f9 | 23 | tracef() API. To do it, in a nutshell: |
641c659a MD |
24 | |
25 | 1) #include <lttng/tracef.h> | |
26 | ||
27 | 2) /* in your code, use like a printf */ | |
28 | tracef("my message, this integer %d", 1234); | |
29 | ||
30 | 3) Link your program against liblttng-ust.so. | |
31 | ||
67ada458 MD |
32 | 4) Enable UST events when tracing with the following sequence of commands |
33 | from lttng-tools: | |
641c659a | 34 | |
aacb3774 | 35 | lttng create |
67ada458 | 36 | lttng enable-event -u -a |
aacb3774 | 37 | lttng start |
641c659a | 38 | [... run your program ...] |
aacb3774 MD |
39 | lttng stop |
40 | lttng view | |
641c659a MD |
41 | |
42 | That's it! | |
43 | ||
44 | If you want to have more flexibility and control on the event names, | |
45 | payload typing, etc, you can continue reading on and use the tracepoints | |
46 | below. "tracef()" is there for quick and dirty ad hoc instrumentation, | |
47 | whereas tracepoint.h is meant for thorough instrumentation of a code | |
48 | base to be integrated with an upstream project. | |
49 | .PP | |
50 | ||
e729155f MD |
51 | .SH "USAGE WITH TRACELOG" |
52 | .PP | |
53 | If you want to migrate existing logging (info, errors, ...) | |
54 | to LTTng UST, you can use the tracelog() interface. | |
55 | To do it, in a nutshell: | |
56 | ||
57 | 1) #include <lttng/tracelog.h> | |
58 | ||
59 | 2) /* in your code, use like a printf, with extra loglevel info. */ | |
c4d667ed | 60 | tracelog(TRACE_INFO, "Message with integer %d", 1234); |
e729155f MD |
61 | |
62 | 3) Link your program against liblttng-ust.so. | |
63 | ||
64 | 4) Enable UST events when tracing with the following sequence of commands | |
65 | from lttng-tools: | |
66 | ||
67 | lttng create | |
68 | lttng enable-event -u "lttng_ust_tracelog:*" | |
69 | lttng start | |
70 | [... run your program ...] | |
71 | lttng stop | |
72 | lttng view | |
73 | ||
74 | That's it! | |
75 | ||
76 | You can replace the enable-event line above with a selection of | |
77 | loglevels, e.g.: | |
78 | ||
c4d667ed | 79 | lttng enable-event -u -a --loglevel TRACE_INFO |
e729155f | 80 | |
c4d667ed MD |
81 | Which will gather all events from TRACE_INFO and more important |
82 | loglevels. | |
e729155f MD |
83 | |
84 | .PP | |
85 | ||
641c659a | 86 | .SH "USAGE WITH TRACEPOINT" |
eba411c6 MD |
87 | .PP |
88 | The simple way to generate the lttng-ust tracepoint probes is to use the | |
89 | lttng-gen-tp(1) tool. See the lttng-gen-tp(1) manpage for explanation. | |
90 | .PP | |
91 | ||
92 | .PP | |
93 | Here is the way to do it manually, without the lttng-gen-tp(1) helper | |
94 | script, through an example: | |
95 | .PP | |
96 | ||
97 | .SH "CREATION OF TRACEPOINT PROVIDER" | |
98 | ||
99 | .nf | |
100 | ||
101 | To create a tracepoint provider, within a build tree similar to | |
dfc45f18 MD |
102 | examples/easy-ust installed with lttng-ust documentation, see |
103 | sample_component_provider.h for the general layout. You will need to | |
104 | define TRACEPOINT_CREATE_PROBES before including your tracepoint | |
105 | provider probe in one source file of your application. See tp.c from | |
106 | easy-ust for an example of a tracepoint probe source file. This manpage | |
107 | will focus on the various types that can be recorded into a trace | |
108 | event: | |
eba411c6 MD |
109 | |
110 | TRACEPOINT_EVENT( | |
111 | /* | |
112 | * provider name, not a variable but a string starting with a | |
a106a9f8 | 113 | * letter and containing either letters, numbers or underscores. |
eba411c6 MD |
114 | * Needs to be the same as TRACEPOINT_PROVIDER. Needs to |
115 | * follow the namespacing guide-lines in lttng/tracepoint.h: | |
a106a9f8 JG |
116 | * |
117 | * Must be included before include tracepoint provider | |
eba411c6 MD |
118 | * ex.: project_event |
119 | * ex.: project_component_event | |
120 | * | |
121 | * Optional company name goes here | |
122 | * ex.: com_efficios_project_component_event | |
123 | * | |
124 | * In this example, "sample" is the project, and "component" is the | |
125 | * component. | |
126 | */ | |
127 | sample_component, | |
128 | ||
129 | /* | |
04fc40ad MD |
130 | * tracepoint name, characters permitted follow the same |
131 | * constraints as the provider name. The name of this example | |
132 | * event is "sample_event". | |
eba411c6 | 133 | */ |
04fc40ad | 134 | sample_event, |
eba411c6 MD |
135 | |
136 | /* | |
a106a9f8 | 137 | * TP_ARGS macro contains the arguments passed for the tracepoint |
eba411c6 MD |
138 | * it is in the following format |
139 | * TP_ARGS(type1, name1, type2, name2, ... type10, | |
140 | name10) | |
a106a9f8 JG |
141 | * where there can be from zero to ten elements. |
142 | * typeN is the datatype, such as int, struct or double **. | |
eba411c6 | 143 | * name is the variable name (in "int myInt" the name would be |
a106a9f8 | 144 | * myint) |
eba411c6 MD |
145 | * TP_ARGS() is valid to mean no arguments |
146 | * TP_ARGS(void) is valid too | |
147 | */ | |
148 | TP_ARGS(int, anint, int, netint, long *, values, | |
149 | char *, text, size_t, textlen, | |
150 | double, doublearg, float, floatarg), | |
151 | ||
152 | /* | |
a106a9f8 | 153 | * TP_FIELDS describes how to write the fields of the trace event. |
eba411c6 MD |
154 | * You can put expressions in the "argument expression" area, |
155 | * typically using the input arguments from TP_ARGS. | |
156 | */ | |
157 | TP_FIELDS( | |
158 | /* | |
159 | * ctf_integer: standard integer field. | |
160 | * args: (type, field name, argument expression) | |
161 | */ | |
162 | ctf_integer(int, intfield, anint) | |
163 | ctf_integer(long, longfield, anint) | |
164 | ||
165 | /* | |
166 | * ctf_integer_hex: integer field printed as hexadecimal. | |
167 | * args: (type, field name, argument expression) | |
168 | */ | |
169 | ctf_integer_hex(int, intfield2, anint) | |
170 | ||
171 | /* | |
172 | * ctf_integer_network: integer field in network byte | |
173 | * order. (_hex: printed as hexadecimal too) | |
174 | * args: (type, field name, argument expression) | |
175 | */ | |
176 | ctf_integer_network(int, netintfield, netint) | |
177 | ctf_integer_network_hex(int, netintfieldhex, netint) | |
178 | ||
179 | /* | |
180 | * ctf_array: a statically-sized array. | |
181 | * args: (type, field name, argument expression, value) | |
a106a9f8 | 182 | */ |
eba411c6 MD |
183 | ctf_array(long, arrfield1, values, 3) |
184 | ||
185 | /* | |
186 | * ctf_array_text: a statically-sized array, printed as | |
187 | * a string. No need to be terminated by a null | |
188 | * character. | |
2f65f1f5 | 189 | * Behavior is undefined if "text" argument is NULL. |
a106a9f8 | 190 | */ |
eba411c6 MD |
191 | ctf_array_text(char, arrfield2, text, 10) |
192 | ||
193 | /* | |
194 | * ctf_sequence: a dynamically-sized array. | |
195 | * args: (type, field name, argument expression, | |
196 | * type of length expression, length expression) | |
efbad5cc MD |
197 | * The "type of length expression" needs to be an |
198 | * unsigned type. As a reminder, "unsigned char" should | |
199 | * be preferred to "char", since the signedness of | |
200 | * "char" is implementation-defined. | |
2f65f1f5 | 201 | * Behavior is undefined if "text" argument is NULL. |
a106a9f8 | 202 | */ |
eba411c6 MD |
203 | ctf_sequence(char, seqfield1, text, |
204 | size_t, textlen) | |
205 | ||
206 | /* | |
207 | * ctf_sequence_text: a dynamically-sized array, printed | |
208 | * as string. No need to be null-terminated. | |
2f65f1f5 | 209 | * Behavior is undefined if "text" argument is NULL. |
eba411c6 MD |
210 | */ |
211 | ctf_sequence_text(char, seqfield2, text, | |
212 | size_t, textlen) | |
213 | ||
214 | /* | |
215 | * ctf_string: null-terminated string. | |
216 | * args: (field name, argument expression) | |
2f65f1f5 | 217 | * Behavior is undefined if "text" argument is NULL. |
eba411c6 MD |
218 | */ |
219 | ctf_string(stringfield, text) | |
220 | ||
221 | /* | |
222 | * ctf_float: floating-point number. | |
223 | * args: (type, field name, argument expression) | |
224 | */ | |
225 | ctf_float(float, floatfield, floatarg) | |
226 | ctf_float(double, doublefield, doublearg) | |
c785c634 MD |
227 | |
228 | /* | |
229 | * ctf_enum: a field using a previously declared | |
230 | * enumeration args: (provider, enum name, container | |
231 | * type, field name, argument expression). The | |
232 | * enumeration itself and its values must have been | |
233 | * defined previously with the TRACEPOINT_ENUM macro, | |
234 | * described below. | |
235 | */ | |
236 | ctf_enum(sample_component, enumeration_name, int, | |
237 | enumfield, enumarg) | |
eba411c6 MD |
238 | ) |
239 | ) | |
7d381d6e MD |
240 | |
241 | There can be an arbitrary number of tracepoint providers within an | |
242 | application, but they must each have their own provider name. Duplicate | |
243 | provider names are not allowed. | |
244 | ||
c785c634 MD |
245 | The CTF specification also supports enumerations that can be declared |
246 | inside a tracepoint provider and used as fields in the tracepoint. This | |
247 | shows how to specify enumerations and what they can be used for: | |
248 | ||
249 | The enumeration is a mapping between an integer, or a range of integers, and a | |
250 | string. It can be used to have a more compact trace in cases where the possible | |
251 | values for a field are limited: | |
252 | ||
253 | TRACEPOINT_ENUM( | |
254 | /* | |
255 | * The provider name, as described in the TRACEPOINT_EVENT macro. | |
256 | */ | |
257 | sample_component, | |
258 | ||
259 | /* | |
260 | * The name of this enumeration, that will be used when using this | |
261 | * global type in tracepoint fields. | |
262 | */ | |
263 | enumeration_name, | |
264 | ||
265 | /* | |
266 | * TP_ENUM_VALUES describe the values of this enumeration and what they | |
267 | * map to. | |
268 | */ | |
269 | TP_ENUM_VALUES( | |
270 | /* | |
271 | * Maps an integer with this string value. By default, enumerations | |
272 | * start at 0 and increment 1 for each entry. | |
273 | */ | |
274 | ctf_enum_value(string_value) | |
275 | ||
276 | /* | |
277 | * Maps the string value to integers in the range 'start' to 'end' | |
278 | * inclusively. If 'start' == 'end', then the string is mapped to | |
279 | * a specific value. | |
280 | * Enumeration ranges may overlap, but the behavior is | |
281 | * implementation-defined, each trace reader will handle overlapping | |
282 | * as it wishes. | |
283 | */ | |
284 | ctf_enum_range(start, end, string_value) | |
285 | ) | |
286 | ) | |
287 | ||
eba411c6 MD |
288 | .fi |
289 | ||
5883c06f MD |
290 | .SH "ASSIGNING LOGLEVEL TO EVENTS" |
291 | ||
292 | .nf | |
293 | ||
294 | Optionally, a loglevel can be assigned to a TRACEPOINT_EVENT using the | |
295 | following construct: | |
296 | ||
297 | TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >, | |
298 | < event >, < loglevel_name >) | |
299 | ||
7c501923 | 300 | The first field is the provider name, the second field is the name of |
5883c06f MD |
301 | the tracepoint, and the third field is the loglevel name. A |
302 | TRACEPOINT_EVENT should be declared prior to the the TRACEPOINT_LOGLEVEL | |
303 | for a given tracepoint name. The TRACEPOINT_PROVIDER must be already | |
304 | declared before declaring a TRACEPOINT_LOGLEVEL. | |
305 | ||
306 | The loglevels go from 0 to 14. Higher numbers imply the most verbosity | |
307 | (higher event throughput expected. | |
a106a9f8 | 308 | |
5883c06f MD |
309 | Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels |
310 | semantic. Loglevels 7 through 13 offer more fine-grained selection of | |
311 | debug information. | |
a106a9f8 | 312 | |
5883c06f MD |
313 | TRACE_EMERG 0 |
314 | system is unusable | |
a106a9f8 | 315 | |
5883c06f MD |
316 | TRACE_ALERT 1 |
317 | action must be taken immediately | |
a106a9f8 | 318 | |
5883c06f MD |
319 | TRACE_CRIT 2 |
320 | critical conditions | |
a106a9f8 | 321 | |
5883c06f MD |
322 | TRACE_ERR 3 |
323 | error conditions | |
a106a9f8 | 324 | |
5883c06f MD |
325 | TRACE_WARNING 4 |
326 | warning conditions | |
a106a9f8 | 327 | |
5883c06f MD |
328 | TRACE_NOTICE 5 |
329 | normal, but significant, condition | |
a106a9f8 | 330 | |
5883c06f MD |
331 | TRACE_INFO 6 |
332 | informational message | |
a106a9f8 | 333 | |
5883c06f MD |
334 | TRACE_DEBUG_SYSTEM 7 |
335 | debug information with system-level scope (set of programs) | |
a106a9f8 | 336 | |
5883c06f MD |
337 | TRACE_DEBUG_PROGRAM 8 |
338 | debug information with program-level scope (set of processes) | |
a106a9f8 | 339 | |
5883c06f MD |
340 | TRACE_DEBUG_PROCESS 9 |
341 | debug information with process-level scope (set of modules) | |
a106a9f8 | 342 | |
5883c06f MD |
343 | TRACE_DEBUG_MODULE 10 |
344 | debug information with module (executable/library) scope (set of | |
345 | units) | |
a106a9f8 | 346 | |
5883c06f MD |
347 | TRACE_DEBUG_UNIT 11 |
348 | debug information with compilation unit scope (set of functions) | |
a106a9f8 | 349 | |
5883c06f MD |
350 | TRACE_DEBUG_FUNCTION 12 |
351 | debug information with function-level scope | |
a106a9f8 | 352 | |
5883c06f MD |
353 | TRACE_DEBUG_LINE 13 |
354 | debug information with line-level scope (TRACEPOINT_EVENT default) | |
a106a9f8 | 355 | |
5883c06f | 356 | TRACE_DEBUG 14 |
1e3b0059 | 357 | debug-level message |
5883c06f MD |
358 | |
359 | See lttng(1) for information on how to use LTTng-UST loglevels. | |
360 | ||
361 | .fi | |
362 | ||
eba411c6 MD |
363 | .SH "ADDING TRACEPOINTS TO YOUR CODE" |
364 | ||
365 | .nf | |
366 | ||
367 | Include the provider header in each C files you plan to instrument, | |
368 | following the building/linking directives in the next section. | |
369 | ||
370 | For instance, add within a function: | |
371 | ||
372 | tracepoint(ust_tests_hello, tptest, i, netint, values, | |
373 | text, strlen(text), dbl, flt); | |
374 | ||
375 | As a call to the tracepoint. It will only be activated when requested by | |
376 | lttng(1) through lttng-sessiond(8). | |
377 | ||
d646ca64 MD |
378 | Even though LTTng-UST supports tracepoint() call site duplicates having |
379 | the same provider and event name, it is recommended to use a | |
380 | provider event name pair only once within the source code to help | |
7c501923 | 381 | map events back to their call sites when analyzing the trace. |
8da6d0c8 DS |
382 | |
383 | Sometimes arguments to the probe are expensive to compute (e.g. | |
384 | take call stack). To avoid the computation when the tracepoint is | |
385 | disabled one can use more 'low level' tracepoint_enabled() and | |
386 | do_tracepoint() macros as following: | |
387 | ||
388 | if (tracepoint_enabled(ust_tests_hello, tptest)) { | |
389 | /* prepare arguments */ | |
390 | do_tracepoint(ust_tests_hello, tptest, i, netint, values, | |
391 | text, strlen(text), dbl, flt); | |
392 | } | |
393 | ||
394 | Here do_tracepoint() doesn't contain check if the tracepoint is enabled. | |
395 | Using tracepoint() in such scenario is dangerous since it also contains | |
396 | enabled check and thus race condition is possible in the following code | |
397 | if the tracepoint has been enabled after check in tracepoint_enabled() | |
398 | but before tracepoint(): | |
399 | ||
400 | if (tracepoint_enabled(provider, name)) { /* tracepoint is disabled */ | |
401 | prepare(args); | |
402 | } | |
403 | /* tracepoint is enabled by 'lttng' tool */ | |
404 | tracepoint(provider, name, args); /* args wasn't prepared properly */ | |
405 | ||
406 | Note also that neither tracepoint_enabled() nor do_tracepoint() have | |
407 | STAP_PROBEV() call so if you need it you should emit this call yourself. | |
408 | ||
eba411c6 MD |
409 | .fi |
410 | ||
411 | .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER" | |
412 | ||
413 | .nf | |
414 | There are 2 ways to compile the Tracepoint Provider with the | |
415 | application: either statically or dynamically. Please follow | |
416 | carefully: | |
417 | ||
30b4246f PP |
418 | 1) Compile the Tracepoint Provider with the application, either |
419 | directly or through a static library (.a): | |
420 | - Into exactly one object of your application, define | |
eba411c6 | 421 | "TRACEPOINT_DEFINE" and include the tracepoint provider. |
9b6435af | 422 | - Use "\-I." for the compilation unit containing the tracepoint |
30b4246f PP |
423 | provider include (e.g., tp.c). |
424 | - Link the application with "\-llttng-ust" and "\-ldl". | |
eba411c6 MD |
425 | - Include the tracepoint provider header into all C files using |
426 | the provider. | |
a106a9f8 JG |
427 | - Examples: |
428 | - doc/examples/easy-ust/ sample.c sample_component_provider.h tp.c | |
429 | Makefile | |
430 | - doc/examples/hello-static-lib/ hello.c tp.c ust_test_hello.h Makefile | |
eba411c6 MD |
431 | |
432 | 2) Compile the Tracepoint Provider separately from the application, | |
433 | using dynamic linking: | |
434 | - Into exactly one object of your application: define | |
435 | "TRACEPOINT_DEFINE" _and_ also define | |
436 | "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint | |
437 | provider header. | |
438 | - Include the tracepoint provider header into all instrumented C | |
439 | files that use the provider. | |
9b6435af AM |
440 | - Compile the tracepoint provider with "\-I.". |
441 | - Link the tracepoint provider with "\-llttng-ust". | |
442 | - Link application with "\-ldl". | |
eba411c6 MD |
443 | - Set a LD_PRELOAD environment to preload the tracepoint provider |
444 | shared object before starting the application when tracing is | |
13fb2d2c JG |
445 | needed. Another way is to dlopen the tracepoint probe when needed |
446 | by the application. | |
eba411c6 | 447 | - Example: |
a106a9f8 | 448 | - doc/examples/demo demo.c tp*.c ust_tests_demo*.h demo-trace Makefile |
eba411c6 | 449 | |
13fb2d2c JG |
450 | - Note about dlclose() usage: it is not safe to use dlclose on a |
451 | provider shared object that is being actively used for tracing due | |
452 | to a lack of reference counting from lttng-ust to the used shared | |
453 | object. | |
eba411c6 MD |
454 | - Enable instrumentation and control tracing with the "lttng" command |
455 | from lttng-tools. See lttng-tools doc/quickstart.txt. | |
2bda849d MD |
456 | - Note for C++ support: although an application instrumented with |
457 | tracepoints can be compiled with g++, tracepoint probes should be | |
458 | compiled with gcc (only tested with gcc so far). | |
eba411c6 MD |
459 | |
460 | .fi | |
461 | ||
0a7c55a5 MD |
462 | .SH "USING LTTNG UST WITH DAEMONS" |
463 | ||
464 | .nf | |
465 | Some extra care is needed when using liblttng-ust with daemon | |
466 | applications that call fork(), clone(), or BSD rfork() without a | |
467 | following exec() family system call. The library "liblttng-ust-fork.so" | |
468 | needs to be preloaded for the application (launch with e.g. | |
469 | LD_PRELOAD=liblttng-ust-fork.so appname). | |
470 | ||
471 | .fi | |
472 | ||
94c9c48d MD |
473 | .SH "CONTEXT" |
474 | ||
475 | .PP | |
476 | Context information can be prepended by the tracer before each, or some, | |
477 | events. The following context information is supported by LTTng-UST: | |
478 | .PP | |
479 | ||
480 | .PP | |
481 | .IP "vtid" | |
482 | Virtual thread ID: thread ID as seen from the point of view of the | |
483 | process namespace. | |
484 | .PP | |
485 | ||
486 | .PP | |
487 | .IP "vpid" | |
488 | Virtual process ID: process ID as seen from the point of view of the | |
489 | process namespace. | |
490 | .PP | |
491 | ||
f6df8626 PW |
492 | .PP |
493 | .IP "ip" | |
494 | Instruction pointer: Enables recording of the exact location where a tracepoint | |
495 | was emitted. Can be used to reverse-lookup the source location that caused the | |
496 | event to be emitted. | |
497 | .PP | |
498 | ||
94c9c48d MD |
499 | .PP |
500 | .IP "procname" | |
501 | Thread name, as set by exec() or prctl(). It is recommended that | |
502 | programs set their thread name with prctl() before hitting the first | |
503 | tracepoint for that thread. | |
504 | .PP | |
505 | ||
506 | .PP | |
507 | .IP "pthread_id" | |
508 | Pthread identifier. Can be used on architectures where pthread_t maps | |
509 | nicely to an unsigned long type. | |
510 | .PP | |
511 | ||
ce46717a | 512 | .SH "BASE ADDRESS STATEDUMP" |
f6df8626 PW |
513 | |
514 | .PP | |
515 | If an application that uses liblttng-ust.so becomes part of a session, | |
516 | information about its currently loaded shared objects will be traced to the | |
517 | session at session-enable time. To record this information, the following event | |
518 | needs to be enabled: | |
519 | .PP | |
520 | .IP "ust_baddr_statedump:soinfo" | |
521 | This event is used to trace a currently loaded shared object. The base address | |
522 | (where the dynamic linker has placed the shared object) is recorded in the | |
6d262185 MD |
523 | "baddr" field. The path to the shared object gets recorded in the |
524 | "sopath" field (as string). The file size of the loaded object (in | |
525 | bytes) is recorded to the "size" field and its time of last modification | |
526 | (in seconds since Epoch) is recorded in the "mtime" field. | |
f6df8626 | 527 | .PP |
6d262185 MD |
528 | If the event above is enabled, a series of "ust_baddr_statedump:soinfo" |
529 | events is recorded at session-enable time. It represents the state of | |
530 | currently loaded shared objects for the traced process. If this | |
531 | information gets combined with the lttng-ust-dl(3) instrumentation, all | |
532 | aspects of dynamic loading that are relevant for symbol and | |
533 | line number lookup are traced by LTTng. | |
f6df8626 | 534 | .PP |
eba411c6 MD |
535 | .SH "ENVIRONMENT VARIABLES" |
536 | ||
537 | .PP | |
538 | .IP "LTTNG_UST_DEBUG" | |
d14c063a | 539 | Activate liblttng-ust debug and error output. |
eba411c6 MD |
540 | .PP |
541 | .IP "LTTNG_UST_REGISTER_TIMEOUT" | |
542 | The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to | |
543 | specify how long the applications should wait for sessiond | |
544 | "registration done" command before proceeding to execute the main | |
545 | program. The default is 3000ms (3 seconds). The timeout value is | |
546 | specified in milliseconds. The value 0 means "don't wait". The value | |
9b6435af | 547 | \-1 means "wait forever". Setting this environment variable to 0 is |
eba411c6 MD |
548 | recommended for applications with time constraints on the process |
549 | startup time. | |
550 | .PP | |
ce46717a PW |
551 | .IP "LTTNG_UST_WITHOUT_BADDR_STATEDUMP" |
552 | Prevent liblttng-ust to perform a base-address statedump on session-enable. | |
f6df8626 | 553 | .PP |
8538d08b JR |
554 | .IP "LTTNG_UST_GETCPU_PLUGIN" |
555 | Used by the getcpu override plugin system. The environment variable | |
556 | provides the path to the shared object which will act as the getcpu override | |
557 | plugin. An example can be found in the lttng-ust documentation under | |
558 | examples/getcpu-override . | |
559 | .PP | |
9493af14 JR |
560 | .IP "LTTNG_UST_CLOCK_PLUGIN" |
561 | Used by the clock override plugin system. The environment variable | |
562 | provides the path to the shared object wich will act as the clock override | |
563 | plugin. An example can be found in the lttng-ust documentation under | |
564 | doc/examples/clock-override . | |
565 | .PP | |
eba411c6 MD |
566 | |
567 | .SH "SEE ALSO" | |
568 | ||
569 | .PP | |
d1eaa4d7 | 570 | lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3), |
f6df8626 | 571 | lttng-ust-dl(3), lttng-sessiond(8) |
eba411c6 | 572 | .PP |
ff42aeef MD |
573 | |
574 | .SH "COMPATIBILITY" | |
575 | ||
576 | .PP | |
577 | Older lttng-ust libraries reject more recent, and incompatible, probe | |
cf949d07 | 578 | providers. Newer lttng-ust libraries accept older probe providers, even |
ff42aeef MD |
579 | though some newer features might not be available with those providers. |
580 | .PP | |
581 | ||
eba411c6 MD |
582 | .SH "BUGS" |
583 | ||
584 | .PP | |
ff42aeef MD |
585 | LTTng-UST 2.0 and 2.1 lttng-ust libraries do not check for probe |
586 | provider version compatibility. This can lead to out-of-bound accesses | |
587 | when using a more recent probe provider with an older lttng-ust library. | |
588 | These error only trigger when tracing is active. This issue has been | |
589 | fixed in LTTng-UST 2.2. | |
eba411c6 MD |
590 | |
591 | If you encounter any issues or usability problem, please report it on | |
592 | our mailing list <lttng-dev@lists.lttng.org> to help improve this | |
593 | project. | |
594 | .SH "CREDITS" | |
595 | ||
596 | liblttng-ust is distributed under the GNU Lesser General Public License | |
597 | version 2.1. The headers are distributed under the MIT license. | |
598 | .PP | |
599 | See http://lttng.org for more information on the LTTng project. | |
600 | .PP | |
601 | Mailing list for support and development: <lttng-dev@lists.lttng.org>. | |
602 | .PP | |
603 | You can find us on IRC server irc.oftc.net (OFTC) in #lttng. | |
604 | .PP | |
605 | .SH "THANKS" | |
606 | ||
607 | Thanks to Ericsson for funding this work, providing real-life use-cases, | |
608 | and testing. | |
609 | ||
610 | Special thanks to Michel Dagenais and the DORSAL laboratory at | |
611 | Polytechnique de Montreal for the LTTng journey. | |
612 | .PP | |
613 | .SH "AUTHORS" | |
614 | ||
615 | .PP | |
616 | liblttng-ust was originally written by Mathieu Desnoyers, with additional | |
617 | contributions from various other people. It is currently maintained by | |
618 | Mathieu Desnoyers <mathieu.desnoyers@efficios.com>. | |
619 | .PP |