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 \author ""
  40 \end_header
  41
  42 \begin_body
  43
  44 \begin_layout Title
  45 LTTng Userspace Tracer Manual
  46 \end_layout
  47
  48 \begin_layout Author
  49 Pierre-Marc Fournier
  50 \end_layout
  51
  52 \begin_layout Section
  53 What is the LTTng Userspace Tracer?
  54 \end_layout
  55
  56 \begin_layout Subsection
  57 Overview
  58 \end_layout
  59
  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
  63  a very high rate.
  64  UST is derived from LTTng, a tracer for the Linux kernel.
  65  It has the same trace format.
  66 \end_layout
  67
  68 \begin_layout Standard
  69 Users may choose at runtime and even at trace time what instrumentation
  70  should be activated.
  71  Custom probes may be used to trace events conditionally.
  72 \end_layout
  73
  74 \begin_layout Subsection
  75 Features
  76 \end_layout
  77
  78 \begin_layout Itemize
  79 Arbitrary number of channels
  80 \end_layout
  81
  82 \begin_layout Itemize
  83 One buffer per process (multiple threads share the same buffer)
  84 \end_layout
  85
  86 \begin_layout Itemize
  87 Early process tracing (from the beginning of the main() function
  88 \end_layout
  89
  90 \begin_layout Itemize
  91 Support for custom probes
  92 \end_layout
  93
  94 \begin_layout Standard
  95 Still to implement:
  96 \end_layout
  97
  98 \begin_layout Itemize
  99 Support of dynamic instrumentation (being implemented in
 100 \end_layout
 101
 102 \begin_layout Standard
 103 Complementary systems:
 104 \end_layout
 105
 106 \begin_layout Itemize
 107 A extension to gdb tracepoints that will allow the tracing of applications
 108  with dynamic instrumentation is under development.
 109 \end_layout
 110
 111 \begin_layout Subsection
 112 Performance
 113 \end_layout
 114
 115 \begin_layout Section
 116 Instrumenting an Application
 117 \end_layout
 118
 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.
 124 \end_layout
 125
 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.
 130 \end_layout
 131
 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.
 137 \end_layout
 138
 139 \begin_layout Subsection
 140 Markers
 141 \end_layout
 142
 143 \begin_layout Standard
 144 Markers were ported from the Linux Kernel Markers implementation.
 145  Therefore, their usage is almost identical.
 146 \end_layout
 147
 148 \begin_layout Subsubsection
 149 Inserting Markers
 150 \end_layout
 151
 152 \begin_layout Standard
 153 Adding a marker is simply a matter of insert one line in the program.
 154 \end_layout
 155
 156 \begin_layout Standard
 157 \begin_inset listings
 158 inline false
 159 status open
 160
 161 \begin_layout Plain Layout
 162
 163 #include <marker.h>
 164 \end_layout
 165
 166 \begin_layout Plain Layout
 167
 168 void function()
 169 \end_layout
 170
 171 \begin_layout Plain Layout
 172
 173 {
 174 \end_layout
 175
 176 \begin_layout Plain Layout
 177
 178         int v;
 179 \end_layout
 180
 181 \begin_layout Plain Layout
 182
 183         char *st;
 184 \end_layout
 185
 186 \begin_layout Plain Layout
 187
 188 \end_layout
 189
 190 \begin_layout Plain Layout
 191
 192         /* ...
 193  set values of v and st ...
 194  */
 195 \end_layout
 196
 197 \begin_layout Plain Layout
 198
 199 \end_layout
 200
 201 \begin_layout Plain Layout
 202
 203         /* a marker: */
 204 \end_layout
 205
 206 \begin_layout Plain Layout
 207
 208         trace_mark(main, myevent,
 209 \begin_inset Quotes eld
 210 \end_inset
 211
 212 firstarg %d secondarg %s
 213 \begin_inset Quotes erd
 214 \end_inset
 215
 216 , v, st);
 217 \end_layout
 218
 219 \begin_layout Plain Layout
 220
 221 \end_layout
 222
 223 \begin_layout Plain Layout
 224
 225         /* a marker without arguments: */
 226 \end_layout
 227
 228 \begin_layout Plain Layout
 229
 230         trace_mark(main, myotherevent, MARK_NOARGS);
 231 \end_layout
 232
 233 \begin_layout Plain Layout
 234
 235 }
 236 \end_layout
 237
 238 \end_inset
 239
 240
 241 \end_layout
 242
 243 \begin_layout Standard
 244 The invocation of the trace_mark() macro requires at least 3 arguments.
 245  The first, here
 246 \begin_inset Quotes eld
 247 \end_inset
 248
 249 main
 250 \begin_inset Quotes erd
 251 \end_inset
 252
 253 , is the name of the event category.
 254  It is also the name of the channel the event will go in.
 255  The second, here
 256 \begin_inset Quotes eld
 257 \end_inset
 258
 259 myevent
 260 \begin_inset Quotes erd
 261 \end_inset
 262
 263  is the name of the event.
 264  The third is a format string that announces the names and the types of
 265  the event arguments.
 266  Its format resembles that of a printf() format string; it is described
 267  thoroughly in Appendix x.
 268 \end_layout
 269
 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.
 274 \end_layout
 275
 276 \begin_layout Subsubsection
 277 Registering the Markers
 278 \end_layout
 279
 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.
 285 \end_layout
 286
 287 \begin_layout Standard
 288 \begin_inset listings
 289 inline false
 290 status open
 291
 292 \begin_layout Plain Layout
 293
 294 MARKER_LIB;
 295 \end_layout
 296
 297 \end_inset
 298
 299
 300 \end_layout
 301
 302 \begin_layout Subsection
 303 Tracepoints
 304 \end_layout
 305
 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.
 312 \end_layout
 313
 314 \begin_layout Standard
 315 A tracepoint in the code looks like this:
 316 \end_layout
 317
 318 \begin_layout Standard
 319 \begin_inset listings
 320 inline false
 321 status open
 322
 323 \begin_layout Plain Layout
 324
 325 #include <marker.h>
 326 \end_layout
 327
 328 \begin_layout Plain Layout
 329
 330 \end_layout
 331
 332 \begin_layout Plain Layout
 333
 334 void function()
 335 \end_layout
 336
 337 \begin_layout Plain Layout
 338
 339 {
 340 \end_layout
 341
 342 \begin_layout Plain Layout
 343
 344         int v;
 345 \end_layout
 346
 347 \begin_layout Plain Layout
 348
 349         char *st;
 350 \end_layout
 351
 352 \begin_layout Plain Layout
 353
 354 \end_layout
 355
 356 \begin_layout Plain Layout
 357
 358         /* ...
 359  set values of v and st ...
 360  */
 361 \end_layout
 362
 363 \begin_layout Plain Layout
 364
 365 \end_layout
 366
 367 \begin_layout Plain Layout
 368
 369         /* a tracepoint: */
 370 \end_layout
 371
 372 \begin_layout Plain Layout
 373
 374         trace_main_myevent(v, st);
 375 \end_layout
 376
 377 \begin_layout Plain Layout
 378
 379 }
 380 \end_layout
 381
 382 \end_inset
 383
 384
 385 \end_layout
 386
 387 \begin_layout Standard
 388 \begin_inset listings
 389 inline false
 390 status open
 391
 392 \begin_layout Plain Layout
 393
 394 DEFINE_TRACE();
 395 \end_layout
 396
 397 \end_inset
 398
 399
 400 \end_layout
 401
 402 \begin_layout Standard
 403 \begin_inset listings
 404 inline false
 405 status open
 406
 407 \begin_layout Plain Layout
 408
 409 TRACEPOINT_LIB;
 410 \end_layout
 411
 412 \end_inset
 413
 414
 415 \end_layout
 416
 417 \begin_layout Subsection
 418 Compiling the Application
 419 \end_layout
 420
 421 \begin_layout Section
 422 Recording a Trace
 423 \end_layout
 424
 425 \begin_layout Subsection
 426 Basic Recording
 427 \end_layout
 428
 429 \begin_layout Subsection
 430 Early Tracing
 431 \end_layout
 432
 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.
 437 \end_layout
 438
 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.
 442 \end_layout
 443
 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.
 449  For example:
 450 \end_layout
 451
 452 \begin_layout Standard
 453 \begin_inset listings
 454 inline false
 455 status open
 456
 457 \begin_layout Plain Layout
 458
 459 $ UST_TRACE=1 UST_AUTOPROBE=1 ./prog
 460 \end_layout
 461
 462 \end_inset
 463
 464
 465 \end_layout
 466
 467 \begin_layout Standard
 468 In order for the trace to be saved, ustd must be running when the traced
 469  program is started.
 470 \end_layout
 471
 472 \begin_layout Section
 473 Viewing and Analyzing the Trace
 474 \end_layout
 475
 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.
 480 \end_layout
 481
 482 \begin_layout Section
 483 Advanced Concepts
 484 \end_layout
 485
 486 \begin_layout Subsection
 487 Using Custom Probes for Conditional Tracing
 488 \end_layout
 489
 490 \begin_layout Subsection
 491 Instrumenting Calls to Library Functions without Recompilation
 492 \end_layout
 493
 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
 497  point.
 498 \end_layout
 499
 500 \begin_layout Subsection
 501 Tracing Programs Without Linking them to the Tracing Library
 502 \end_layout
 503
 504 \begin_layout Standard
 505 Programs that were not instrumented nor linked with the tracing libraries
 506  may still be traced.
 507  In order to produce events, they must be linked to instrumented libraries
 508  or use instrumented library wrappers as described in section xx.
 509 \end_layout
 510
 511 \begin_layout Standard
 512 \begin_inset listings
 513 inline false
 514 status open
 515
 516 \begin_layout Plain Layout
 517
 518 LD_PRELOAD=...
 519  program
 520 \end_layout
 521
 522 \end_inset
 523
 524
 525 \end_layout
 526
 527 \begin_layout Section
 528 \start_of_appendix
 529 Format of Marker Format Strings
 530 \end_layout
 531
 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.
 539 \end_layout
 540
 541 \begin_layout Standard
 542 \begin_inset listings
 543 inline false
 544 status open
 545
 546 \begin_layout Plain Layout
 547
 548 \begin_inset Quotes eld
 549 \end_inset
 550
 551 field_name1 #tracetype1 %ctype1 field_name2 #tracetype2 %ctype2
 552 \begin_inset Quotes erd
 553 \end_inset
 554
 555
 556 \end_layout
 557
 558 \end_inset
 559
 560
 561 \end_layout
 562
 563 \begin_layout Description
 564 field_name: The name of the field, as it will be seen when the trace is
 565  parsed.
 566 \end_layout
 567
 568 \begin_layout Description
 569 tracetype: The type of the argument as it will be written in the trace.
 570 \end_layout
 571
 572 \begin_layout Description
 573 ctype: The C type of the argument passed to the Marker (this is very similar
 574  to the %...
 575  types in a printf() format string)
 576 \end_layout
 577
 578 \begin_layout Standard
 579 Both field_name and tracetype are optional.
 580  These are all valid format strings:
 581 \end_layout
 582
 583 \begin_layout Standard
 584 \begin_inset listings
 585 inline false
 586 status open
 587
 588 \begin_layout Plain Layout
 589
 590 \end_layout
 591
 592 \end_inset
 593
 594
 595 \end_layout
 596
 597 \begin_layout Subsection
 598 tracetype
 599 \end_layout
 600
 601 \begin_layout Standard
 602 A typical Marker format string looks like this:
 603 \end_layout
 604
 605 \begin_layout Standard
 606 The serialization format string supports the basic printf format strings.
 607 \end_layout
 608
 609 \begin_layout Standard
 610 In addition, it defines new formats that can be used to serialize more
 611 \end_layout
 612
 613 \begin_layout Standard
 614 complex/non portable data structures.
 615 \end_layout
 616
 617 \begin_layout Standard
 618 Typical use:
 619 \end_layout
 620
 621 \begin_layout Standard
 622 field_name %ctype
 623 \end_layout
 624
 625 \begin_layout Standard
 626 field_name #tracetype %ctype
 627 \end_layout
 628
 629 \begin_layout Standard
 630 field_name #tracetype %ctype1 %ctype2 ...
 631 \end_layout
 632
 633 \begin_layout Standard
 634 A conversion is performed between format string types supported by GCC and
 635 \end_layout
 636
 637 \begin_layout Standard
 638 the trace type requested.
 639  GCC type is used to perform type checking on format
 640 \end_layout
 641
 642 \begin_layout Standard
 643 strings.
 644  Trace type is used to specify the exact binary representation
 645 \end_layout
 646
 647 \begin_layout Standard
 648 in the trace.
 649  A mapping is done between one or more GCC types to one trace
 650 \end_layout
 651
 652 \begin_layout Standard
 653 type.
 654  Sign extension, if required by the conversion, is performed following
 655 \end_layout
 656
 657 \begin_layout Standard
 658 the trace type.
 659 \end_layout
 660
 661 \begin_layout Standard
 662 If a gcc format is not declared with a trace format, the gcc format is
 663 \end_layout
 664
 665 \begin_layout Standard
 666 also used as binary representation in the trace.
 667 \end_layout
 668
 669 \begin_layout Standard
 670 Strings are supported with %s.
 671 \end_layout
 672
 673 \begin_layout Standard
 674 A single tracetype (sequence) can take multiple c types as parameter.
 675 \end_layout
 676
 677 \begin_layout Standard
 678 c types:
 679 \end_layout
 680
 681 \begin_layout Standard
 682 see printf(3).
 683 \end_layout
 684
 685 \begin_layout Standard
 686 Note: to write a uint32_t in a trace, the following expression is recommended
 687 \end_layout
 688
 689 \begin_layout Standard
 690 si it can be portable:
 691 \end_layout
 692
 693 \begin_layout Standard
 694 ("#4u%lu", (unsigned long)var)
 695 \end_layout
 696
 697 \begin_layout Standard
 698 trace types:
 699 \end_layout
 700
 701 \begin_layout Standard
 702 Serialization specific formats :
 703 \end_layout
 704
 705 \begin_layout Standard
 706 Fixed size integers
 707 \end_layout
 708
 709 \begin_layout Standard
 710 #1u writes uint8_t
 711 \end_layout
 712
 713 \begin_layout Standard
 714 #2u writes uint16_t
 715 \end_layout
 716
 717 \begin_layout Standard
 718 #4u writes uint32_t
 719 \end_layout
 720
 721 \begin_layout Standard
 722 #8u writes uint64_t
 723 \end_layout
 724
 725 \begin_layout Standard
 726 #1d writes int8_t
 727 \end_layout
 728
 729 \begin_layout Standard
 730 #2d writes int16_t
 731 \end_layout
 732
 733 \begin_layout Standard
 734 #4d writes int32_t
 735 \end_layout
 736
 737 \begin_layout Standard
 738 #8d writes int64_t
 739 \end_layout
 740
 741 \begin_layout Standard
 742 i.e.:
 743 \end_layout
 744
 745 \begin_layout Standard
 746 #1u%lu #2u%lu #4d%lu #8d%lu #llu%hu #d%lu
 747 \end_layout
 748
 749 \begin_layout Standard
 750 * Attributes:
 751 \end_layout
 752
 753 \begin_layout Standard
 754 n: (for network byte order)
 755 \end_layout
 756
 757 \begin_layout Standard
 758 #ntracetype%ctype
 759 \end_layout
 760
 761 \begin_layout Standard
 762 is written in the trace in network byte order.
 763 \end_layout
 764
 765 \begin_layout Standard
 766 i.e.: #bn4u%lu, #n%lu, #b%u
 767 \end_layout
 768
 769 \begin_layout Standard
 770 TODO (eventually)
 771 \end_layout
 772
 773 \begin_layout Standard
 774 Variable length sequence
 775 \end_layout
 776
 777 \begin_layout Standard
 778 #a #tracetype1 #tracetype2 %array_ptr %elem_size %num_elems
 779 \end_layout
 780
 781 \begin_layout Standard
 782 In the trace:
 783 \end_layout
 784
 785 \begin_layout Standard
 786 #a specifies that this is a sequence
 787 \end_layout
 788
 789 \begin_layout Standard
 790 #tracetype1 is the type of elements in the sequence
 791 \end_layout
 792
 793 \begin_layout Standard
 794 #tracetype2 is the type of the element count
 795 \end_layout
 796
 797 \begin_layout Standard
 798 GCC input:
 799 \end_layout
 800
 801 \begin_layout Standard
 802 array_ptr is a pointer to an array that contains members of size
 803 \end_layout
 804
 805 \begin_layout Standard
 806 elem_size.
 807 \end_layout
 808
 809 \begin_layout Standard
 810 num_elems is the number of elements in the array.
 811 \end_layout
 812
 813 \begin_layout Standard
 814 i.e.: #a #lu #lu %p %lu %u
 815 \end_layout
 816
 817 \begin_layout Standard
 818 Callback
 819 \end_layout
 820
 821 \begin_layout Standard
 822 #k callback (taken from the probe data)
 823 \end_layout
 824
 825 \begin_layout Standard
 826 The following % arguments are exepected by the callback
 827 \end_layout
 828
 829 \begin_layout Standard
 830 i.e.: #a #lu #lu #k %p
 831 \end_layout
 832
 833 \begin_layout Standard
 834 Note: No conversion is done from floats to integers, nor from integers to
 835 \end_layout
 836
 837 \begin_layout Standard
 838 floats between c types and trace types.
 839  float conversion from double to float
 840 \end_layout
 841
 842 \begin_layout Standard
 843 or from float to double is also not supported.
 844 \end_layout
 845
 846 \end_body
 847 \end_document