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