trunk/masters-pmf/3rd_gen_viewer/3rd_gen_viewer_arch.lyx

   1 #LyX 1.5.5 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 276
   3 \begin_document
   4 \begin_header
   5 \textclass article
   6 \language english
   7 \inputencoding auto
   8 \font_roman default
   9 \font_sans default
  10 \font_typewriter default
  11 \font_default_family default
  12 \font_sc false
  13 \font_osf false
  14 \font_sf_scale 100
  15 \font_tt_scale 100
  16 \graphics default
  17 \paperfontsize default
  18 \spacing single
  19 \papersize default
  20 \use_geometry false
  21 \use_amsmath 1
  22 \use_esint 1
  23 \cite_engine basic
  24 \use_bibtopic false
  25 \paperorientation portrait
  26 \secnumdepth 3
  27 \tocdepth 3
  28 \paragraph_separation skip
  29 \defskip medskip
  30 \quotes_language english
  31 \papercolumns 1
  32 \papersides 1
  33 \paperpagestyle default
  34 \tracking_changes false
  35 \output_changes false
  36 \author ""
  37 \author ""
  38 \end_header
  39
  40 \begin_body
  41
  42 \begin_layout Title
  43 A Set of APIs for a Third-Generation Trace Viewer
  44 \end_layout
  45
  46 \begin_layout Author
  47 \noindent
  48 Pierre-Marc Fournier, Michel Dagenais, Mathieu Desnoyers
  49 \newline
  50
  51 \family typewriter
  52 \size footnotesize
  53 <pierre-marc.fournier _at_ polymtl.ca>
  54 \family default
  55 \size default
  56
  57 \newline
  58
  59 \newline
  60 CASI Lab
  61 \newline
  62 École Polytechnique de Montréal
  63 \newline
  64
  65 \newline
  66 WORK IN PROGRESS
  67 \end_layout
  68
  69 \begin_layout Section
  70 Introduction
  71 \end_layout
  72
  73 \begin_layout Standard
  74 This document proposes some APIs for a trace viewing and analysis infrastructure.
  75 \end_layout
  76
  77 \begin_layout Standard
  78 Design choices were made based on the experience acquired by the design,
  79  development and use of two previous generations of trace viewers, respectively
  80  the Trace Visualizer from the Linux Trace Toolkit and its successor, the
  81  LTTV from the LTTng tracing toolkit.
  82 \end_layout
  83
  84 \begin_layout Section
  85 Goals
  86 \end_layout
  87
  88 \begin_layout Itemize
  89 Provide an infrastructure for fast, interactive visualization and analysis
  90  of huge traces (>10 GB) on standard workstations
  91 \begin_inset Foot
  92 status open
  93
  94 \begin_layout Standard
  95 Efficiency is of great importance.
  96  It is tempting to think that as computers get faster, it will be possible
  97  to run more complex analyses on traces in a shorter time.
  98  In fact, the size of the traces grows as computers get more powerful, because
  99  they do more operations than before in the same amount of time and therefore
 100  generate more events.
 101  The current tendency to parallelize systems is another factor that results
 102  in bigger traces.
 103 \end_layout
 104
 105 \end_inset
 106
 107
 108 \end_layout
 109
 110 \begin_layout Itemize
 111 Support live trace processing
 112 \end_layout
 113
 114 \begin_layout Itemize
 115 Allow merging of traces of different formats
 116 \end_layout
 117
 118 \begin_layout Standard
 119 \begin_inset Note Note
 120 status open
 121
 122 \begin_layout Itemize
 123 Design the viewer in such a way that it can run in parallel on multi-core
 124  systems
 125 \begin_inset Note Greyedout
 126 status open
 127
 128 \begin_layout Standard
 129 (Is it worth it? Beware of complex locking issues)
 130 \end_layout
 131
 132 \end_inset
 133
 134 ; No, we don't.
 135 \end_layout
 136
 137 \end_inset
 138
 139
 140 \end_layout
 141
 142 \begin_layout Itemize
 143 Design with both command line utilities (C language) and graphical interfaces
 144  (Java and others) in mind, sharing code and standardizing interfaces as
 145  much as possible
 146 \end_layout
 147
 148 \begin_deeper
 149 \begin_layout Standard
 150 Both command-line interfaces and graphical interfaces have an important
 151  role to play in trace analysis.
 152  While graphical interfaces allow for complex views, command-line utilities
 153  can be used quickly in more environments; they can also be more convenient
 154  in some circumstances.
 155  A good design should be such that they can share code and APIs.
 156 \end_layout
 157
 158 \end_deeper
 159 \begin_layout Section
 160 General aspects
 161 \end_layout
 162
 163 \begin_layout Itemize
 164 All data structures must be accessed through API methods, in order to allow
 165  for internal change without breaking compatibility.
 166 \end_layout
 167
 168 \begin_layout Section
 169 Controlling the tracing of a system
 170 \end_layout
 171
 172 \begin_layout Subsection
 173 Overview
 174 \end_layout
 175
 176 \begin_layout Standard
 177 The goal of this API is to provide a portable way of controlling tracing
 178  of heterogenous systems.
 179 \end_layout
 180
 181 \begin_layout Standard
 182 It should enable to do the following actions.
 183 \end_layout
 184
 185 \begin_layout Itemize
 186 Set the parameters of a trace (channels, buffering, destination of data
 187  (file, network, process)...)
 188 \end_layout
 189
 190 \begin_layout Itemize
 191 Control the recording of events (start, stop, pause the trace)
 192 \end_layout
 193
 194 \begin_layout Itemize
 195 Create tracepoints (on dynamic tracers) and control which tracepoints are
 196  activated (some may be at trace level, others might only permit system
 197  level)
 198 \end_layout
 199
 200 \begin_layout Subsection
 201 Trace control API
 202 \end_layout
 203
 204 \begin_layout Itemize
 205 List the static tracepoints available on a system
 206 \end_layout
 207
 208 \begin_deeper
 209 \begin_layout Standard
 210 These may be static tracepoints (active or inactive) or dynamic tracepoints
 211  (active or proposed).
 212 \end_layout
 213
 214 \end_deeper
 215 \begin_layout Itemize
 216 Add a new dynamic tracepoint
 217 \end_layout
 218
 219 \begin_layout Itemize
 220 Activate a tracepoint
 221 \end_layout
 222
 223 \begin_layout Itemize
 224 Deactivate a tracepoint
 225 \end_layout
 226
 227 \begin_layout Itemize
 228 List available probes
 229 \end_layout
 230
 231 \begin_layout Itemize
 232 Connect a probe to a tracepoint
 233 \end_layout
 234
 235 \begin_layout Itemize
 236 Start tracing
 237 \end_layout
 238
 239 \begin_layout Itemize
 240 Stop tracing
 241 \end_layout
 242
 243 \begin_layout Itemize
 244 \begin_inset Note Greyedout
 245 status open
 246
 247 \begin_layout Standard
 248 others missing...
 249 \end_layout
 250
 251 \end_inset
 252
 253
 254 \end_layout
 255
 256 \begin_layout Section
 257 Reading traces
 258 \end_layout
 259
 260 \begin_layout Subsection
 261 Overview
 262 \end_layout
 263
 264 \begin_layout Subsubsection
 265 Timestamps
 266 \end_layout
 267
 268 \begin_layout Standard
 269 Timestamps, at the framework level, should be in an architecture-independent
 270  format.
 271  One possibility would be to have them stored in seconds (with decimals).
 272  Offsetting, if necessary, could be handled by the traceset (trace merging)
 273  level.
 274  An uncertainty value should accompany the timestamp.
 275  Timestamps in cycles should be available if they are provided by the tracer.
 276 \end_layout
 277
 278 \begin_layout Subsection
 279 Low-level trace reading API
 280 \end_layout
 281
 282 \begin_layout Standard
 283 The goal of this API is to provide a uniform way for the framework to access
 284  the events recorded in a trace, in an encoding-independant way.
 285 \end_layout
 286
 287 \begin_layout Subsubsection
 288 Factory methods
 289 \end_layout
 290
 291 \begin_layout Itemize
 292 void get_supported_formats(void)
 293 \end_layout
 294
 295 \begin_deeper
 296 \begin_layout Standard
 297 Arguments: none
 298 \end_layout
 299
 300 \begin_layout Standard
 301 Return:
 302 \end_layout
 303
 304 \begin_layout Itemize
 305 a list of supported formats
 306 \end_layout
 307
 308 \end_deeper
 309 \begin_layout Itemize
 310 open_trace()
 311 \end_layout
 312
 313 \begin_deeper
 314 \begin_layout Standard
 315 Arguments:
 316 \end_layout
 317
 318 \begin_layout Itemize
 319 trace URL
 320 \end_layout
 321
 322 \begin_deeper
 323 \begin_layout Itemize
 324 local file name
 325 \end_layout
 326
 327 \begin_layout Itemize
 328 other special url to establish a network connection
 329 \end_layout
 330
 331 \begin_layout Itemize
 332 etc...
 333 \end_layout
 334
 335 \end_deeper
 336 \begin_layout Itemize
 337 trace format (optional, for cases where auto detection would not work or
 338  be ambiguous)
 339 \end_layout
 340
 341 \begin_layout Standard
 342 Return:
 343 \end_layout
 344
 345 \begin_layout Itemize
 346 a trace handle
 347 \end_layout
 348
 349 \end_deeper
 350 \begin_layout Subsubsection
 351 Trace methods
 352 \end_layout
 353
 354 \begin_layout Itemize
 355 bool close(struct trace *tr)
 356 \end_layout
 357
 358 \begin_layout Itemize
 359 struct event *current_event(struct trace *)
 360 \end_layout
 361
 362 \begin_deeper
 363 \begin_layout Standard
 364 Arguments: none
 365 \end_layout
 366
 367 \begin_layout Standard
 368 Return:
 369 \end_layout
 370
 371 \begin_layout Itemize
 372 the event currently pointed by the position pointer
 373 \end_layout
 374
 375 \end_deeper
 376 \begin_layout Itemize
 377 bool advance(struct trace *tr)
 378 \end_layout
 379
 380 \begin_deeper
 381 \begin_layout Standard
 382 Advance the position pointer to the next event in the trace.
 383 \end_layout
 384
 385 \begin_layout Standard
 386 Arguments: none
 387 \end_layout
 388
 389 \begin_layout Standard
 390 Return values:
 391 \end_layout
 392
 393 \begin_layout Itemize
 394 The result:
 395 \end_layout
 396
 397 \begin_deeper
 398 \begin_layout Itemize
 399 Success
 400 \end_layout
 401
 402 \begin_layout Itemize
 403 Final end of trace (end of a non-live trace or of a completed live trace)
 404 \end_layout
 405
 406 \begin_layout Itemize
 407 No more events for now (end of a still running live trace)
 408 \end_layout
 409
 410 \end_deeper
 411 \end_deeper
 412 \begin_layout Itemize
 413 bool seek_time(struct trace *tr, struct trace_cursor *cur)
 414 \end_layout
 415
 416 \begin_deeper
 417 \begin_layout Standard
 418 Arguments:
 419 \end_layout
 420
 421 \begin_layout Itemize
 422 The time to seek to
 423 \end_layout
 424
 425 \begin_layout Standard
 426 Return: none
 427 \end_layout
 428
 429 \end_deeper
 430 \begin_layout Itemize
 431 struct trace_cursor *trace_new_cursor_beginning(struct trace *tr)
 432 \end_layout
 433
 434 \begin_deeper
 435 \begin_layout Standard
 436 Return a new cursor associated to the trace, positioned at its beginning
 437 \end_layout
 438
 439 \end_deeper
 440 \begin_layout Itemize
 441 struct trace_cursor *trace_cursor_copy(struct trace_cursor *cur)
 442 \end_layout
 443
 444 \begin_layout Itemize
 445 void trace_cursor_destroy(struct trace_cursor_destroy *)
 446 \end_layout
 447
 448 \begin_layout Itemize
 449 struct trace_time get_time_start(struct trace *tr)
 450 \end_layout
 451
 452 \begin_deeper
 453 \begin_layout Standard
 454 Arguments: none
 455 \end_layout
 456
 457 \begin_layout Standard
 458 Return:
 459 \end_layout
 460
 461 \begin_layout Itemize
 462 the timestamp of the first event in the trace
 463 \end_layout
 464
 465 \end_deeper
 466 \begin_layout Itemize
 467 struct trace_time get_time_end(struct trace *tr)
 468 \end_layout
 469
 470 \begin_deeper
 471 \begin_layout Standard
 472 Arguments: none
 473 \end_layout
 474
 475 \begin_layout Standard
 476 Return:
 477 \end_layout
 478
 479 \begin_layout Itemize
 480 the timestamp of the last event in the trace
 481 \end_layout
 482
 483 \end_deeper
 484 \begin_layout Itemize
 485 register_callback_new_event(struct trace *tr, struct trace_time after, void
 486  (*cb)(void))
 487 \end_layout
 488
 489 \begin_deeper
 490 \begin_layout Standard
 491 Register a callback that is called when a new event becomes available in
 492  a live trace.
 493  It is also called when the live trace ends.
 494 \end_layout
 495
 496 \begin_layout Standard
 497 Arguments:
 498 \end_layout
 499
 500 \begin_layout Itemize
 501 after (timestamp) : call only if the event occurent later than
 502 \emph on
 503 after
 504 \end_layout
 505
 506 \begin_layout Itemize
 507 cb: the callback function
 508 \begin_inset Note Note
 509 status open
 510
 511 \begin_layout Standard
 512 specify its args and return val
 513 \end_layout
 514
 515 \end_inset
 516
 517
 518 \end_layout
 519
 520 \begin_layout Standard
 521 Return:
 522 \end_layout
 523
 524 \begin_layout Itemize
 525 Result (success or failure)
 526 \end_layout
 527
 528 \end_deeper
 529 \begin_layout Subsection
 530 High-level trace reading API
 531 \end_layout
 532
 533 \begin_layout Standard
 534 The goal of this API is to provide a uniform way for analyses and views
 535  to obtain trace events from a traceset (merge of many traces or a single
 536  trace), regardless of the system they were recorded on and of the tracer
 537  used.
 538 \end_layout
 539
 540 \begin_layout Itemize
 541 Request a range of events
 542 \end_layout
 543
 544 \begin_deeper
 545 \begin_layout Standard
 546 Arguments:
 547 \end_layout
 548
 549 \begin_layout Itemize
 550 (implicitly) the traceset
 551 \end_layout
 552
 553 \begin_layout Itemize
 554 start timestamp
 555 \end_layout
 556
 557 \begin_layout Itemize
 558 stop timestamp (special value for infinity, for live traces)
 559 \end_layout
 560
 561 \begin_layout Itemize
 562 list of event types and callbacks
 563 \end_layout
 564
 565 \begin_layout Itemize
 566 filter with complex expressions
 567 \end_layout
 568
 569 \begin_layout Itemize
 570 private pointer to be passed to the callbacks
 571 \end_layout
 572
 573 \begin_layout Standard
 574 Return:
 575 \end_layout
 576
 577 \begin_layout Itemize
 578 handle to the request for cancelling it
 579 \end_layout
 580
 581 \end_deeper
 582 \begin_layout Itemize
 583 Cancel a request
 584 \end_layout
 585
 586 \begin_deeper
 587 \begin_layout Standard
 588 Arguments:
 589 \end_layout
 590
 591 \begin_layout Itemize
 592 the handle to the request
 593 \end_layout
 594
 595 \end_deeper
 596 \begin_layout Subsection
 597 State management
 598 \end_layout
 599
 600 \begin_layout Subsubsection
 601 State accessing API
 602 \end_layout
 603
 604 \begin_layout Itemize
 605 Request the values of a given set of state variables at a point in time
 606 \end_layout
 607
 608 \begin_deeper
 609 \begin_layout Standard
 610 Arguments:
 611 \end_layout
 612
 613 \begin_layout Itemize
 614 the list of state variables
 615 \end_layout
 616
 617 \begin_layout Itemize
 618 the timestamp
 619 \end_layout
 620
 621 \end_deeper
 622 \begin_layout Itemize
 623 Request all the states changes of a given set of state variables between
 624  two time indexes
 625 \end_layout
 626
 627 \begin_deeper
 628 \begin_layout Standard
 629 Arguments:
 630 \end_layout
 631
 632 \begin_layout Itemize
 633 the list of state variables
 634 \end_layout
 635
 636 \begin_layout Itemize
 637 timestamp 1
 638 \end_layout
 639
 640 \begin_layout Itemize
 641 timestamp 2
 642 \end_layout
 643
 644 \end_deeper
 645 \begin_layout Subsubsection
 646 State setting API
 647 \end_layout
 648
 649 \begin_layout Section
 650 Describing event types
 651 \end_layout
 652
 653 \begin_layout Subsection
 654 Overview
 655 \end_layout
 656
 657 \begin_layout Standard
 658 Because tracepoints may be created dynamically, information about the descriptio
 659 n of events is just as dynamic.
 660  In this context, one simple way to communicate the event description informatio
 661 n to upper layers would be to send them as events, as it is done in recent
 662  versions of LTTV.
 663  The core events used to describe other events are the only ones whose descripti
 664 on is hardcoded in the framework.
 665 \end_layout
 666
 667 \begin_layout Standard
 668 These event-type-describing events could then be received and interpreted
 669  by a module, the Event Description Service, which would be a client to
 670  the high-level tracing API at the same level as normal views and analyses.
 671  It would store the information and allow the other views and analyses to
 672  access it via this API.
 673 \end_layout
 674
 675 \begin_layout Subsection
 676 Events-describing events
 677 \end_layout
 678
 679 \begin_layout Itemize
 680 Event type declaration event
 681 \end_layout
 682
 683 \begin_deeper
 684 \begin_layout Standard
 685 Announce the existence of an event type
 686 \end_layout
 687
 688 \begin_layout Itemize
 689 event type name
 690 \end_layout
 691
 692 \end_deeper
 693 \begin_layout Itemize
 694 Argument declaration event
 695 \end_layout
 696
 697 \begin_deeper
 698 \begin_layout Standard
 699 Announce the existence of an event argument
 700 \end_layout
 701
 702 \begin_layout Itemize
 703 event type name
 704 \end_layout
 705
 706 \begin_layout Itemize
 707 name
 708 \end_layout
 709
 710 \begin_layout Itemize
 711 type
 712 \end_layout
 713
 714 \end_deeper
 715 \begin_layout Itemize
 716 Event destruction
 717 \end_layout
 718
 719 \begin_deeper
 720 \begin_layout Standard
 721 Announce that an event type ceased to exist
 722 \end_layout
 723
 724 \begin_layout Itemize
 725 event type name
 726 \end_layout
 727
 728 \end_deeper
 729 \begin_layout Subsection
 730 Event type description API
 731 \end_layout
 732
 733 \begin_layout Itemize
 734 Get the list of all the event types
 735 \end_layout
 736
 737 \begin_layout Itemize
 738 Find an event type by name
 739 \end_layout
 740
 741 \begin_layout Itemize
 742 Get the number of arguments of an event
 743 \end_layout
 744
 745 \begin_layout Itemize
 746 Get the list of arguments of an event
 747 \end_layout
 748
 749 \begin_layout Itemize
 750 Find an argument by name
 751 \end_layout
 752
 753 \begin_layout Itemize
 754 Get the type of an argument of an event type
 755 \end_layout
 756
 757 \begin_layout Itemize
 758 Get a string representation of an argument of any type, given an event that
 759  contains it an instance of it
 760 \end_layout
 761
 762 \begin_layout Itemize
 763 Get an integer representation of an integer argument, a floating-point represent
 764 ation of a floating-point argument
 765 \end_layout
 766
 767 \begin_layout Itemize
 768 Functions for accessing other types
 769 \end_layout
 770
 771 \begin_layout Section
 772 Inspecting events
 773 \end_layout
 774
 775 \begin_layout Subsection
 776 Overview
 777 \end_layout
 778
 779 \begin_layout Standard
 780 Events contain the following information.
 781 \end_layout
 782
 783 \begin_layout Itemize
 784 Timestamp
 785 \end_layout
 786
 787 \begin_layout Itemize
 788 Event type identifier
 789 \end_layout
 790
 791 \begin_deeper
 792 \begin_layout Standard
 793 Two possibilities:
 794 \end_layout
 795
 796 \begin_layout Itemize
 797 an event id (integer)
 798 \end_layout
 799
 800 \begin_layout Itemize
 801 an event name (string)
 802 \end_layout
 803
 804 \end_deeper
 805 \begin_layout Itemize
 806 The name of the machine it occured on
 807 \end_layout
 808
 809 \begin_layout Subsection
 810 Event inspecting API
 811 \end_layout
 812
 813 \begin_layout Itemize
 814 get the event type identifier
 815 \end_layout
 816
 817 \begin_layout Itemize
 818 get timestamp
 819 \end_layout
 820
 821 \begin_layout Itemize
 822 get the name of the machine on which the event occured
 823 \end_layout
 824
 825 \begin_layout Itemize
 826 get information on the type of tracing technology that was used
 827 \end_layout
 828
 829 \begin_layout Itemize
 830 get the corresponding tracepoint (machine/tracing technology/name/location
 831  in code(if available))
 832 \end_layout
 833
 834 \end_body
 835 \end_document