doc/manual.lyx

   1 #LyX 1.6.1 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 345
   3 \begin_document
   4 \begin_header
   5 \textclass article
   6 \use_default_options true
   7 \language english
   8 \inputencoding auto
   9 \font_roman default
  10 \font_sans default
  11 \font_typewriter default
  12 \font_default_family default
  13 \font_sc false
  14 \font_osf false
  15 \font_sf_scale 100
  16 \font_tt_scale 100
  17
  18 \graphics default
  19 \paperfontsize default
  20 \use_hyperref false
  21 \papersize default
  22 \use_geometry false
  23 \use_amsmath 1
  24 \use_esint 1
  25 \cite_engine basic
  26 \use_bibtopic false
  27 \paperorientation portrait
  28 \secnumdepth 3
  29 \tocdepth 3
  30 \paragraph_separation indent
  31 \defskip medskip
  32 \quotes_language english
  33 \papercolumns 1
  34 \papersides 1
  35 \paperpagestyle default
  36 \tracking_changes false
  37 \output_changes false
  38 \author ""
  39 \end_header
  40
  41 \begin_body
  42
  43 \begin_layout Title
  44 LTTng Userspace Tracer Manual
  45 \end_layout
  46
  47 \begin_layout Author
  48 Pierre-Marc Fournier
  49 \end_layout
  50
  51 \begin_layout Section
  52 What is the LTTng Userspace Tracer?
  53 \end_layout
  54
  55 \begin_layout Subsection
  56 Overview
  57 \end_layout
  58
  59 \begin_layout Subsection
  60 Features
  61 \end_layout
  62
  63 \begin_layout Itemize
  64 Arbitrary number of channels
  65 \end_layout
  66
  67 \begin_layout Itemize
  68 One buffer per process (multiple threads share the same buffer)
  69 \end_layout
  70
  71 \begin_layout Itemize
  72 Early process tracing (from the beginning of the main() function
  73 \end_layout
  74
  75 \begin_layout Standard
  76 Still to implement:
  77 \end_layout
  78
  79 \begin_layout Subsection
  80 Performance
  81 \end_layout
  82
  83 \begin_layout Section
  84 Instrumenting an Application
  85 \end_layout
  86
  87 \begin_layout Standard
  88 In order to record a trace of events occurring in a application, the application
  89  must be instrumented.
  90  Instrumentation points resemble function calls and
  91 \end_layout
  92
  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.
  97 \end_layout
  98
  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.
 104 \end_layout
 105
 106 \begin_layout Subsection
 107 Markers
 108 \end_layout
 109
 110 \begin_layout Subsubsection
 111 Inserting Markers
 112 \end_layout
 113
 114 \begin_layout Standard
 115 Adding a marker is simply a matter of insert one line in the program.
 116 \end_layout
 117
 118 \begin_layout Standard
 119 \begin_inset listings
 120 inline false
 121 status open
 122
 123 \begin_layout Plain Layout
 124
 125 #include <marker.h>
 126 \end_layout
 127
 128 \begin_layout Plain Layout
 129
 130 void function()
 131 \end_layout
 132
 133 \begin_layout Plain Layout
 134
 135 {
 136 \end_layout
 137
 138 \begin_layout Plain Layout
 139
 140         int v;
 141 \end_layout
 142
 143 \begin_layout Plain Layout
 144
 145         char *st;
 146 \end_layout
 147
 148 \begin_layout Plain Layout
 149
 150 \end_layout
 151
 152 \begin_layout Plain Layout
 153
 154         /* ...
 155  set values of v and st ...
 156  */
 157 \end_layout
 158
 159 \begin_layout Plain Layout
 160
 161 \end_layout
 162
 163 \begin_layout Plain Layout
 164
 165         /* a marker: */
 166 \end_layout
 167
 168 \begin_layout Plain Layout
 169
 170         trace_mark(main, myevent,
 171 \begin_inset Quotes eld
 172 \end_inset
 173
 174 firstarg %d secondarg %s
 175 \begin_inset Quotes erd
 176 \end_inset
 177
 178 , v, st);
 179 \end_layout
 180
 181 \begin_layout Plain Layout
 182
 183 \end_layout
 184
 185 \begin_layout Plain Layout
 186
 187         /* a marker without arguments: */
 188 \end_layout
 189
 190 \begin_layout Plain Layout
 191
 192         trace_mark(main, myotherevent, MARK_NOARGS);
 193 \end_layout
 194
 195 \begin_layout Plain Layout
 196
 197 }
 198 \end_layout
 199
 200 \end_inset
 201
 202
 203 \end_layout
 204
 205 \begin_layout Standard
 206 The invocation of the trace_mark() macro requires at least 3 arguments.
 207  The first, here
 208 \begin_inset Quotes eld
 209 \end_inset
 210
 211 main
 212 \begin_inset Quotes erd
 213 \end_inset
 214
 215 , is the name of the event category.
 216  It is also the name of the channel the event will go in.
 217  The second, here
 218 \begin_inset Quotes eld
 219 \end_inset
 220
 221 myevent
 222 \begin_inset Quotes erd
 223 \end_inset
 224
 225  is the name of the event.
 226  The third is a format string that announces the names and the types of
 227  the event arguments.
 228  Its format resembles that of a printf() format string; it is described
 229  thoroughly in Appendix x.
 230 \end_layout
 231
 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.
 236 \end_layout
 237
 238 \begin_layout Subsubsection
 239 Registering the Markers
 240 \end_layout
 241
 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.
 247 \end_layout
 248
 249 \begin_layout Standard
 250 \begin_inset listings
 251 inline false
 252 status open
 253
 254 \begin_layout Plain Layout
 255
 256 MARKER_LIB;
 257 \end_layout
 258
 259 \end_inset
 260
 261
 262 \end_layout
 263
 264 \begin_layout Subsection
 265 Tracepoints
 266 \end_layout
 267
 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.
 274 \end_layout
 275
 276 \begin_layout Standard
 277 A tracepoint in the code looks like this:
 278 \end_layout
 279
 280 \begin_layout Standard
 281 \begin_inset listings
 282 inline false
 283 status open
 284
 285 \begin_layout Plain Layout
 286
 287 #include <marker.h>
 288 \end_layout
 289
 290 \begin_layout Plain Layout
 291
 292 \end_layout
 293
 294 \begin_layout Plain Layout
 295
 296 void function()
 297 \end_layout
 298
 299 \begin_layout Plain Layout
 300
 301 {
 302 \end_layout
 303
 304 \begin_layout Plain Layout
 305
 306         int v;
 307 \end_layout
 308
 309 \begin_layout Plain Layout
 310
 311         char *st;
 312 \end_layout
 313
 314 \begin_layout Plain Layout
 315
 316 \end_layout
 317
 318 \begin_layout Plain Layout
 319
 320         /* ...
 321  set values of v and st ...
 322  */
 323 \end_layout
 324
 325 \begin_layout Plain Layout
 326
 327 \end_layout
 328
 329 \begin_layout Plain Layout
 330
 331         /* a tracepoint: */
 332 \end_layout
 333
 334 \begin_layout Plain Layout
 335
 336         trace_main_myevent(v, st);
 337 \end_layout
 338
 339 \begin_layout Plain Layout
 340
 341 }
 342 \end_layout
 343
 344 \end_inset
 345
 346
 347 \end_layout
 348
 349 \begin_layout Standard
 350 \begin_inset listings
 351 inline false
 352 status open
 353
 354 \begin_layout Plain Layout
 355
 356 DEFINE_TRACE();
 357 \end_layout
 358
 359 \end_inset
 360
 361
 362 \end_layout
 363
 364 \begin_layout Standard
 365 \begin_inset listings
 366 inline false
 367 status open
 368
 369 \begin_layout Plain Layout
 370
 371 TRACEPOINT_LIB;
 372 \end_layout
 373
 374 \end_inset
 375
 376
 377 \end_layout
 378
 379 \begin_layout Subsection
 380 Compiling the Application
 381 \end_layout
 382
 383 \begin_layout Section
 384 Recording a Trace
 385 \end_layout
 386
 387 \begin_layout Subsection
 388 Basic Recording
 389 \end_layout
 390
 391 \begin_layout Subsection
 392 Early Tracing
 393 \end_layout
 394
 395 \begin_layout Section
 396 Viewing and Analyzing the Trace
 397 \end_layout
 398
 399 \begin_layout Section
 400 Advanced Concepts
 401 \end_layout
 402
 403 \begin_layout Subsection
 404 Using Custom Probes
 405 \end_layout
 406
 407 \begin_layout Subsection
 408 Instrumenting Calls to Library Functions without Recompilation
 409 \end_layout
 410
 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
 414  point.
 415 \end_layout
 416
 417 \begin_layout Subsection
 418 Tracing Programs Without Linking them to the Tracing Library
 419 \end_layout
 420
 421 \begin_layout Standard
 422 Programs that were not instrumented nor linked with the tracing libraries
 423  may still be traced.
 424  In order to produce events, they must be linked to instrumented libraries
 425  or use instrumented library wrappers as described in section xx.
 426 \end_layout
 427
 428 \begin_layout Standard
 429 \begin_inset listings
 430 inline false
 431 status open
 432
 433 \begin_layout Plain Layout
 434
 435 LD_PRELOAD=...
 436  program
 437 \end_layout
 438
 439 \end_inset
 440
 441
 442 \end_layout
 443
 444 \begin_layout Section
 445 \start_of_appendix
 446 Format of Marker Format Strings
 447 \end_layout
 448
 449 \end_body
 450 \end_document