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
44 LTTng Userspace Tracer Manual
52 What is the LTTng Userspace Tracer?
55 \begin_layout Subsection
59 \begin_layout Subsection
64 Arbitrary number of channels
68 One buffer per process (multiple threads share the same buffer)
72 Early process tracing (from the beginning of the main() function
75 \begin_layout Standard
79 \begin_layout Subsection
84 Instrumenting an Application
87 \begin_layout Standard
88 In order to record a trace of events occurring in a application, the application
90 Instrumentation points resemble function calls and
93 \begin_layout Standard
94 There are no limitations on the type of code that may be instrumented.
95 Multi-threaded programs may be instrumented without problem.
96 Signal handler may be instrumented as well.
99 \begin_layout Standard
100 There are two APIs to instrument programs: markers and tracepoints.
101 Markers are quick to add and are usually used for temporary instrumentation.
102 Tracepoints provide a way to instrument code more cleanly and are suited
103 for permanent instrumentation.
106 \begin_layout Subsection
110 \begin_layout Subsubsection
114 \begin_layout Standard
115 Adding a marker is simply a matter of insert one line in the program.
118 \begin_layout Standard
119 \begin_inset listings
123 \begin_layout Plain Layout
128 \begin_layout Plain Layout
133 \begin_layout Plain Layout
138 \begin_layout Plain Layout
143 \begin_layout Plain Layout
148 \begin_layout Plain Layout
152 \begin_layout Plain Layout
155 set values of v and st ...
159 \begin_layout Plain Layout
163 \begin_layout Plain Layout
168 \begin_layout Plain Layout
170 trace_mark(main, myevent,
171 \begin_inset Quotes eld
174 firstarg %d secondarg %s
175 \begin_inset Quotes erd
181 \begin_layout Plain Layout
185 \begin_layout Plain Layout
187 /* a marker without arguments: */
190 \begin_layout Plain Layout
192 trace_mark(main, myotherevent, MARK_NOARGS);
195 \begin_layout Plain Layout
205 \begin_layout Standard
206 The invocation of the trace_mark() macro requires at least 3 arguments.
208 \begin_inset Quotes eld
212 \begin_inset Quotes erd
215 , is the name of the event category.
216 It is also the name of the channel the event will go in.
218 \begin_inset Quotes eld
222 \begin_inset Quotes erd
225 is the name of the event.
226 The third is a format string that announces the names and the types of
228 Its format resembles that of a printf() format string; it is described
229 thoroughly in Appendix x.
232 \begin_layout Standard
233 A given Marker may appear more than once in the same program.
234 Other Markers may have the same name and a different format string, although
235 this might induce some confusion at analysis time.
238 \begin_layout Subsubsection
239 Registering the Markers
242 \begin_layout Standard
243 In order to inform to register the Markers present in the module, a macro
244 must be inserted at global scope.
245 Only one such macro is needed per exacutable or per shared object.
246 Adding it more than once, however, is harmless.
249 \begin_layout Standard
250 \begin_inset listings
254 \begin_layout Plain Layout
264 \begin_layout Subsection
268 \begin_layout Standard
269 The Tracepoints API uses the Markers, but provides a higher-level abstraction.
270 Whereas the markers API provides limited type checking, the Tracepoints
271 API provides more thorough type checking and discharges from the need to
272 insert format strings directly in the code and to have format strings appear
273 more than once if a given marker is reused.
276 \begin_layout Standard
277 A tracepoint in the code looks like this:
280 \begin_layout Standard
281 \begin_inset listings
285 \begin_layout Plain Layout
290 \begin_layout Plain Layout
294 \begin_layout Plain Layout
299 \begin_layout Plain Layout
304 \begin_layout Plain Layout
309 \begin_layout Plain Layout
314 \begin_layout Plain Layout
318 \begin_layout Plain Layout
321 set values of v and st ...
325 \begin_layout Plain Layout
329 \begin_layout Plain Layout
334 \begin_layout Plain Layout
336 trace_main_myevent(v, st);
339 \begin_layout Plain Layout
349 \begin_layout Standard
350 \begin_inset listings
354 \begin_layout Plain Layout
364 \begin_layout Standard
365 \begin_inset listings
369 \begin_layout Plain Layout
379 \begin_layout Subsection
380 Compiling the Application
383 \begin_layout Section
387 \begin_layout Subsection
391 \begin_layout Subsection
395 \begin_layout Section
396 Viewing and Analyzing the Trace
399 \begin_layout Section
403 \begin_layout Subsection
407 \begin_layout Subsection
408 Instrumenting Calls to Library Functions without Recompilation
411 \begin_layout Standard
412 Calls to uninstrumented libraries may be instrumented by creating a wrapper
413 library that intercepts calls to the library, trigger an instrumentation
417 \begin_layout Subsection
418 Tracing Programs Without Linking them to the Tracing Library
421 \begin_layout Standard
422 Programs that were not instrumented nor linked with the tracing libraries
424 In order to produce events, they must be linked to instrumented libraries
425 or use instrumented library wrappers as described in section xx.
428 \begin_layout Standard
429 \begin_inset listings
433 \begin_layout Plain Layout
444 \begin_layout Section
446 Format of Marker Format Strings