1 #LyX 1.6.1 created this file. For more info see http://www.lyx.org/
6 \use_default_options true
11 \font_typewriter default
12 \font_default_family default
19 \paperfontsize default
27 \paperorientation portrait
30 \paragraph_separation indent
32 \quotes_language english
35 \paperpagestyle default
36 \tracking_changes false
45 LTTng Userspace Tracer Manual
53 What is the LTTng Userspace Tracer?
56 \begin_layout Subsection
60 \begin_layout Standard
61 The LTTng Userspace Tracer (UST) is a tracing system for userspace applications.
62 It is designed to trace efficiently applications that produce events at
64 UST is derived from LTTng, a tracer for the Linux kernel.
65 It has the same trace format.
68 \begin_layout Standard
69 Users may choose at runtime and even at trace time what instrumentation
71 Custom probes may be used to trace events conditionally.
74 \begin_layout Subsection
79 Arbitrary number of channels
83 One buffer per process (multiple threads share the same buffer)
87 Early process tracing (from the beginning of the main() function
91 Support for custom probes
94 \begin_layout Standard
99 Support of dynamic instrumentation (being implemented in
102 \begin_layout Standard
103 Complementary systems:
106 \begin_layout Itemize
107 A extension to gdb tracepoints that will allow the tracing of applications
108 with dynamic instrumentation is under development.
111 \begin_layout Subsection
115 \begin_layout Section
116 Instrumenting an Application
119 \begin_layout Standard
120 In order to record a trace of events occurring in a application, the application
121 must be instrumented.
122 Instrumentation points resemble function calls.
123 When the program reaches an instrumentation point, an event is generated.
126 \begin_layout Standard
127 There are no limitations on the type of code that may be instrumented.
128 Multi-threaded programs may be instrumented without problem.
129 Signal handler may be instrumented as well.
132 \begin_layout Standard
133 There are two APIs to instrument programs: markers and tracepoints.
134 Markers are quick to add and are usually used for temporary instrumentation.
135 Tracepoints provide a way to instrument code more cleanly and are suited
136 for permanent instrumentation.
139 \begin_layout Subsection
143 \begin_layout Standard
144 Markers were ported from the Linux Kernel Markers implementation.
145 Therefore, their usage is almost identical.
148 \begin_layout Subsubsection
152 \begin_layout Standard
153 Adding a marker is simply a matter of insert one line in the program.
156 \begin_layout Standard
157 \begin_inset listings
161 \begin_layout Plain Layout
166 \begin_layout Plain Layout
171 \begin_layout Plain Layout
176 \begin_layout Plain Layout
181 \begin_layout Plain Layout
186 \begin_layout Plain Layout
190 \begin_layout Plain Layout
193 set values of v and st ...
197 \begin_layout Plain Layout
201 \begin_layout Plain Layout
206 \begin_layout Plain Layout
208 trace_mark(main, myevent,
209 \begin_inset Quotes eld
212 firstarg %d secondarg %s
213 \begin_inset Quotes erd
219 \begin_layout Plain Layout
223 \begin_layout Plain Layout
225 /* a marker without arguments: */
228 \begin_layout Plain Layout
230 trace_mark(main, myotherevent, MARK_NOARGS);
233 \begin_layout Plain Layout
243 \begin_layout Standard
244 The invocation of the trace_mark() macro requires at least 3 arguments.
246 \begin_inset Quotes eld
250 \begin_inset Quotes erd
253 , is the name of the event category.
254 It is also the name of the channel the event will go in.
256 \begin_inset Quotes eld
260 \begin_inset Quotes erd
263 is the name of the event.
264 The third is a format string that announces the names and the types of
266 Its format resembles that of a printf() format string; it is described
267 thoroughly in Appendix x.
270 \begin_layout Standard
271 A given Marker may appear more than once in the same program.
272 Other Markers may have the same name and a different format string, although
273 this might induce some confusion at analysis time.
276 \begin_layout Subsubsection
277 Registering the Markers
280 \begin_layout Standard
281 In order to inform to register the Markers present in the module, a macro
282 must be inserted at global scope.
283 Only one such macro is needed per exacutable or per shared object.
284 Adding it more than once, however, is harmless.
287 \begin_layout Standard
288 \begin_inset listings
292 \begin_layout Plain Layout
302 \begin_layout Subsection
306 \begin_layout Standard
307 The Tracepoints API uses the Markers, but provides a higher-level abstraction.
308 Whereas the markers API provides limited type checking, the Tracepoints
309 API provides more thorough type checking and discharges from the need to
310 insert format strings directly in the code and to have format strings appear
311 more than once if a given marker is reused.
314 \begin_layout Standard
315 A tracepoint in the code looks like this:
318 \begin_layout Standard
319 \begin_inset listings
323 \begin_layout Plain Layout
328 \begin_layout Plain Layout
332 \begin_layout Plain Layout
337 \begin_layout Plain Layout
342 \begin_layout Plain Layout
347 \begin_layout Plain Layout
352 \begin_layout Plain Layout
356 \begin_layout Plain Layout
359 set values of v and st ...
363 \begin_layout Plain Layout
367 \begin_layout Plain Layout
372 \begin_layout Plain Layout
374 trace_main_myevent(v, st);
377 \begin_layout Plain Layout
387 \begin_layout Standard
388 \begin_inset listings
392 \begin_layout Plain Layout
402 \begin_layout Standard
403 \begin_inset listings
407 \begin_layout Plain Layout
417 \begin_layout Subsection
418 Compiling the Application
421 \begin_layout Section
425 \begin_layout Subsection
429 \begin_layout Subsection
433 \begin_layout Standard
434 Sometimes, an application must be traced as soon as it is started.
435 In these cases, the Basic Recording method is not satisfactory, as important
436 events may be lost before the tracing is started.
439 \begin_layout Standard
440 By using the Early Tracing method, it is guaranteed that the tracing is
441 started when the execution of the main() function of the program starts.
444 \begin_layout Standard
445 Early Tracing may be enabled by defining the UST_TRACE environment variable
446 to a non-empty value when the program starts.
447 Additionally, the UST_AUTOPROBE may be set to a non-empty value to automaticall
448 y connect all markers to the default probe.
452 \begin_layout Standard
453 \begin_inset listings
457 \begin_layout Plain Layout
459 $ UST_TRACE=1 UST_AUTOPROBE=1 ./prog
467 \begin_layout Standard
468 In order for the trace to be saved, ustd must be running when the traced
472 \begin_layout Section
473 Viewing and Analyzing the Trace
476 \begin_layout Standard
477 LTTV may be used for opening the trace.
478 If an appropriate time source was used, it may be opened concurrently with
479 other application traces and kernel traces.
482 \begin_layout Section
486 \begin_layout Subsection
487 Using Custom Probes for Conditional Tracing
490 \begin_layout Subsection
491 Instrumenting Calls to Library Functions without Recompilation
494 \begin_layout Standard
495 Calls to uninstrumented libraries may be instrumented by creating a wrapper
496 library that intercepts calls to the library, trigger an instrumentation
500 \begin_layout Subsection
501 Tracing Programs Without Linking them to the Tracing Library
504 \begin_layout Standard
505 Programs that were not instrumented nor linked with the tracing libraries
507 In order to produce events, they must be linked to instrumented libraries
508 or use instrumented library wrappers as described in section xx.
511 \begin_layout Standard
512 \begin_inset listings
516 \begin_layout Plain Layout
527 \begin_layout Section
529 Format of Marker Format Strings
532 \begin_layout Standard
533 The format of Marker format strings is inspired from printf() format strings.
534 As with printf(), it is used to indicate to the parsing function the type
535 of the arguments that are passed.
536 Additionally, format strings indicate the name of each argument and the
537 format of that argument in the trace.
538 The structure of a typical format string is the following.
541 \begin_layout Standard
542 \begin_inset listings
546 \begin_layout Plain Layout
548 \begin_inset Quotes eld
551 field_name1 #tracetype1 %ctype1 field_name2 #tracetype2 %ctype2
552 \begin_inset Quotes erd
563 \begin_layout Description
564 field_name: The name of the field, as it will be seen when the trace is
568 \begin_layout Description
569 tracetype: The type of the argument as it will be written in the trace.
572 \begin_layout Description
573 ctype: The C type of the argument passed to the Marker (this is very similar
575 types in a printf() format string)
578 \begin_layout Standard
579 Both field_name and tracetype are optional.
580 These are all valid format strings:
583 \begin_layout Standard
584 \begin_inset listings
588 \begin_layout Plain Layout
597 \begin_layout Subsection
601 \begin_layout Standard
602 A typical Marker format string looks like this:
605 \begin_layout Standard
606 The serialization format string supports the basic printf format strings.
609 \begin_layout Standard
610 In addition, it defines new formats that can be used to serialize more
613 \begin_layout Standard
614 complex/non portable data structures.
617 \begin_layout Standard
621 \begin_layout Standard
625 \begin_layout Standard
626 field_name #tracetype %ctype
629 \begin_layout Standard
630 field_name #tracetype %ctype1 %ctype2 ...
633 \begin_layout Standard
634 A conversion is performed between format string types supported by GCC and
637 \begin_layout Standard
638 the trace type requested.
639 GCC type is used to perform type checking on format
642 \begin_layout Standard
644 Trace type is used to specify the exact binary representation
647 \begin_layout Standard
649 A mapping is done between one or more GCC types to one trace
652 \begin_layout Standard
654 Sign extension, if required by the conversion, is performed following
657 \begin_layout Standard
661 \begin_layout Standard
662 If a gcc format is not declared with a trace format, the gcc format is
665 \begin_layout Standard
666 also used as binary representation in the trace.
669 \begin_layout Standard
670 Strings are supported with %s.
673 \begin_layout Standard
674 A single tracetype (sequence) can take multiple c types as parameter.
677 \begin_layout Standard
681 \begin_layout Standard
685 \begin_layout Standard
686 Note: to write a uint32_t in a trace, the following expression is recommended
689 \begin_layout Standard
690 si it can be portable:
693 \begin_layout Standard
694 ("#4u%lu", (unsigned long)var)
697 \begin_layout Standard
701 \begin_layout Standard
702 Serialization specific formats :
705 \begin_layout Standard
709 \begin_layout Standard
713 \begin_layout Standard
717 \begin_layout Standard
721 \begin_layout Standard
725 \begin_layout Standard
729 \begin_layout Standard
733 \begin_layout Standard
737 \begin_layout Standard
741 \begin_layout Standard
745 \begin_layout Standard
746 #1u%lu #2u%lu #4d%lu #8d%lu #llu%hu #d%lu
749 \begin_layout Standard
753 \begin_layout Standard
754 n: (for network byte order)
757 \begin_layout Standard
761 \begin_layout Standard
762 is written in the trace in network byte order.
765 \begin_layout Standard
766 i.e.: #bn4u%lu, #n%lu, #b%u
769 \begin_layout Standard
773 \begin_layout Standard
774 Variable length sequence
777 \begin_layout Standard
778 #a #tracetype1 #tracetype2 %array_ptr %elem_size %num_elems
781 \begin_layout Standard
785 \begin_layout Standard
786 #a specifies that this is a sequence
789 \begin_layout Standard
790 #tracetype1 is the type of elements in the sequence
793 \begin_layout Standard
794 #tracetype2 is the type of the element count
797 \begin_layout Standard
801 \begin_layout Standard
802 array_ptr is a pointer to an array that contains members of size
805 \begin_layout Standard
809 \begin_layout Standard
810 num_elems is the number of elements in the array.
813 \begin_layout Standard
814 i.e.: #a #lu #lu %p %lu %u
817 \begin_layout Standard
821 \begin_layout Standard
822 #k callback (taken from the probe data)
825 \begin_layout Standard
826 The following % arguments are exepected by the callback
829 \begin_layout Standard
830 i.e.: #a #lu #lu #k %p
833 \begin_layout Standard
834 Note: No conversion is done from floats to integers, nor from integers to
837 \begin_layout Standard
838 floats between c types and trace types.
839 float conversion from double to float
842 \begin_layout Standard
843 or from float to double is also not supported.