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 for dynamic instrumentation
102 \begin_layout Itemize
103 Per thread or per CPU buffers
106 \begin_layout Standard
107 Complementary systems:
110 \begin_layout Itemize
111 A extension to gdb tracepoints that will allow the tracing of applications
112 with dynamic instrumentation is under development.
115 \begin_layout Subsection
119 \begin_layout Section
123 \begin_layout Section
124 Instrumenting an Application
127 \begin_layout Standard
128 In order to record a trace of events occurring in a application, the application
129 must be instrumented.
130 Instrumentation points resemble function calls.
131 When the program reaches an instrumentation point, an event is generated.
134 \begin_layout Standard
135 There are no limitations on the type of code that may be instrumented.
136 Multi-threaded programs may be instrumented without problem.
137 Signal handlers may be instrumented as well.
140 \begin_layout Standard
141 There are two APIs to instrument programs: markers and tracepoints.
142 Markers are quick to add and are usually used for temporary instrumentation.
143 Tracepoints provide a way to instrument code more cleanly and are suited
144 for permanent instrumentation.
147 \begin_layout Subsection
151 \begin_layout Standard
152 Markers were ported from the Linux Kernel Markers implementation.
153 Therefore, their usage is almost identical.
156 \begin_layout Subsubsection
160 \begin_layout Standard
161 Adding a marker is simply a matter of insert one line in the program.
164 \begin_layout Standard
165 \begin_inset listings
169 \begin_layout Plain Layout
174 \begin_layout Plain Layout
176 int main(int argc, char **argv)
179 \begin_layout Plain Layout
184 \begin_layout Plain Layout
189 \begin_layout Plain Layout
194 \begin_layout Plain Layout
198 \begin_layout Plain Layout
201 set values of v and st ...
205 \begin_layout Plain Layout
209 \begin_layout Plain Layout
214 \begin_layout Plain Layout
216 trace_mark(main, myevent,
217 \begin_inset Quotes eld
220 firstarg %d secondarg %s
221 \begin_inset Quotes erd
227 \begin_layout Plain Layout
231 \begin_layout Plain Layout
233 /* a marker without arguments: */
236 \begin_layout Plain Layout
238 trace_mark(main, myotherevent, MARK_NOARGS);
241 \begin_layout Plain Layout
245 \begin_layout Plain Layout
250 \begin_layout Plain Layout
260 \begin_layout Standard
261 The invocation of the trace_mark() macro requires at least 3 arguments.
263 \begin_inset Quotes eld
267 \begin_inset Quotes erd
270 , is the name of the event category.
271 It is also the name of the channel the event will go in.
273 \begin_inset Quotes eld
277 \begin_inset Quotes erd
280 is the name of the event.
281 The third is a format string that announces the names and the types of
283 Its format resembles that of a printf() format string; it is described
284 thoroughly in Appendix x.
287 \begin_layout Standard
288 A given Marker may appear more than once in the same program.
289 Other Markers may have the same name and a different format string, although
290 this might induce some confusion at analysis time.
293 \begin_layout Subsubsection
294 Registering the Markers
297 \begin_layout Standard
298 In order to inform to register the Markers present in the module, a macro
299 must be inserted at global scope.
300 Only one such macro is needed per exacutable or per shared object.
301 Adding it more than once, however, is harmless.
304 \begin_layout Standard
305 \begin_inset listings
309 \begin_layout Plain Layout
319 \begin_layout Subsection
323 \begin_layout Standard
324 The Tracepoints API uses the Markers, but provides a higher-level abstraction.
325 Whereas the markers API provides limited type checking, the Tracepoints
326 API provides more thorough type checking and discharges from the need to
327 insert format strings directly in the code and to have format strings appear
328 more than once if a given marker is reused.
331 \begin_layout Standard
332 A tracepoint in the code looks like this:
335 \begin_layout Standard
336 \begin_inset listings
340 \begin_layout Plain Layout
345 \begin_layout Plain Layout
349 \begin_layout Plain Layout
354 \begin_layout Plain Layout
359 \begin_layout Plain Layout
364 \begin_layout Plain Layout
369 \begin_layout Plain Layout
373 \begin_layout Plain Layout
376 set values of v and st ...
380 \begin_layout Plain Layout
384 \begin_layout Plain Layout
389 \begin_layout Plain Layout
391 trace_main_myevent(v, st);
394 \begin_layout Plain Layout
404 \begin_layout Standard
405 \begin_inset listings
409 \begin_layout Plain Layout
419 \begin_layout Standard
420 \begin_inset listings
424 \begin_layout Plain Layout
434 \begin_layout Subsection
435 Compiling the Application
438 \begin_layout Standard
440 \begin_inset Quotes eld
444 \begin_inset Quotes erd
447 directory for an example application and makefile.
450 \begin_layout Itemize
451 The compiler must have access to the include path for the libust headers.
454 \begin_layout Itemize
455 The application should be statically or dynamically linked to libust.
458 \begin_layout Section
462 \begin_layout Subsection
466 \begin_layout Subsection
470 \begin_layout Standard
471 Sometimes, an application must be traced as soon as it is started.
472 In these cases, the Basic Recording method is not satisfactory, as important
473 events may be lost before the tracing is started.
476 \begin_layout Standard
477 By using the Early Tracing method, it is guaranteed that the tracing is
478 started when the execution of the main() function of the program starts.
481 \begin_layout Standard
482 Early Tracing may be enabled by defining the UST_TRACE environment variable
483 to a non-empty value when the program starts.
484 Additionally, the UST_AUTOPROBE may be set to a non-empty value to automaticall
485 y connect all markers to the default probe.
489 \begin_layout Standard
490 \begin_inset listings
494 \begin_layout Plain Layout
496 $ UST_TRACE=1 UST_AUTOPROBE=1 ./prog
504 \begin_layout Standard
505 In order for the trace to be saved, ustd must be running when the traced
509 \begin_layout Section
510 Viewing and Analyzing the Trace
513 \begin_layout Standard
514 LTTV may be used for opening the trace.
515 If an appropriate time source was used, it may be opened concurrently with
516 other application traces and kernel traces.
519 \begin_layout Section
523 \begin_layout Subsection
524 Using Custom Probes for Conditional Tracing
527 \begin_layout Subsection
528 Instrumenting Calls to Library Functions without Recompilation
531 \begin_layout Standard
532 Calls to uninstrumented libraries may be instrumented by creating a wrapper
533 library that intercepts calls to the library, trigger an instrumentation
537 \begin_layout Subsection
538 Tracing Programs Without Linking them to the Tracing Library
541 \begin_layout Standard
542 Programs that were not instrumented nor linked with the tracing libraries
544 In order to produce events, they must be linked to instrumented libraries
545 or use instrumented library wrappers as described in section xx.
548 \begin_layout Standard
549 \begin_inset listings
553 \begin_layout Plain Layout
564 \begin_layout Section
566 Format of Marker Format Strings
569 \begin_layout Standard
570 The format of Marker format strings is inspired from printf() format strings.
571 As with printf(), it is used to indicate to the parsing function the type
572 of the arguments that are passed.
573 Additionally, format strings indicate the name of each argument and the
574 format of that argument in the trace.
575 The structure of a typical format string is the following.
578 \begin_layout Standard
579 \begin_inset listings
583 \begin_layout Plain Layout
585 \begin_inset Quotes eld
588 field_name1 #tracetype1 %ctype1 field_name2 #tracetype2 %ctype2
589 \begin_inset Quotes erd
600 \begin_layout Description
601 field_name: The name of the field, as it will be seen when the trace is
605 \begin_layout Description
606 tracetype: The type of the argument as it will be written in the trace.
609 \begin_layout Description
610 ctype: The C type of the argument passed to the Marker (this is very similar
612 types in a printf() format string)
615 \begin_layout Standard
616 Both field_name and tracetype are optional.
617 These are all valid format strings:
620 \begin_layout Standard
621 \begin_inset listings
625 \begin_layout Plain Layout
634 \begin_layout Subsection
638 \begin_layout Standard
639 A typical Marker format string looks like this:
642 \begin_layout Standard
643 The serialization format string supports the basic printf format strings.
646 \begin_layout Standard
647 In addition, it defines new formats that can be used to serialize more
650 \begin_layout Standard
651 complex/non portable data structures.
654 \begin_layout Standard
658 \begin_layout Standard
662 \begin_layout Standard
663 field_name #tracetype %ctype
666 \begin_layout Standard
667 field_name #tracetype %ctype1 %ctype2 ...
670 \begin_layout Standard
671 A conversion is performed between format string types supported by GCC and
674 \begin_layout Standard
675 the trace type requested.
676 GCC type is used to perform type checking on format
679 \begin_layout Standard
681 Trace type is used to specify the exact binary representation
684 \begin_layout Standard
686 A mapping is done between one or more GCC types to one trace
689 \begin_layout Standard
691 Sign extension, if required by the conversion, is performed following
694 \begin_layout Standard
698 \begin_layout Standard
699 If a gcc format is not declared with a trace format, the gcc format is
702 \begin_layout Standard
703 also used as binary representation in the trace.
706 \begin_layout Standard
707 Strings are supported with %s.
710 \begin_layout Standard
711 A single tracetype (sequence) can take multiple c types as parameter.
714 \begin_layout Standard
718 \begin_layout Standard
722 \begin_layout Standard
723 Note: to write a uint32_t in a trace, the following expression is recommended
726 \begin_layout Standard
727 si it can be portable:
730 \begin_layout Standard
731 ("#4u%lu", (unsigned long)var)
734 \begin_layout Standard
738 \begin_layout Standard
739 Serialization specific formats :
742 \begin_layout Standard
746 \begin_layout Standard
750 \begin_layout Standard
754 \begin_layout Standard
758 \begin_layout Standard
762 \begin_layout Standard
766 \begin_layout Standard
770 \begin_layout Standard
774 \begin_layout Standard
778 \begin_layout Standard
782 \begin_layout Standard
783 #1u%lu #2u%lu #4d%lu #8d%lu #llu%hu #d%lu
786 \begin_layout Standard
790 \begin_layout Standard
791 n: (for network byte order)
794 \begin_layout Standard
798 \begin_layout Standard
799 is written in the trace in network byte order.
802 \begin_layout Standard
803 i.e.: #bn4u%lu, #n%lu, #b%u
806 \begin_layout Standard
810 \begin_layout Standard
811 Variable length sequence
814 \begin_layout Standard
815 #a #tracetype1 #tracetype2 %array_ptr %elem_size %num_elems
818 \begin_layout Standard
822 \begin_layout Standard
823 #a specifies that this is a sequence
826 \begin_layout Standard
827 #tracetype1 is the type of elements in the sequence
830 \begin_layout Standard
831 #tracetype2 is the type of the element count
834 \begin_layout Standard
838 \begin_layout Standard
839 array_ptr is a pointer to an array that contains members of size
842 \begin_layout Standard
846 \begin_layout Standard
847 num_elems is the number of elements in the array.
850 \begin_layout Standard
851 i.e.: #a #lu #lu %p %lu %u
854 \begin_layout Standard
858 \begin_layout Standard
859 #k callback (taken from the probe data)
862 \begin_layout Standard
863 The following % arguments are exepected by the callback
866 \begin_layout Standard
867 i.e.: #a #lu #lu #k %p
870 \begin_layout Standard
871 Note: No conversion is done from floats to integers, nor from integers to
874 \begin_layout Standard
875 floats between c types and trace types.
876 float conversion from double to float
879 \begin_layout Standard
880 or from float to double is also not supported.