1 #LyX 1.5.5 created this file. For more info see http://www.lyx.org/
10 \font_typewriter default
11 \font_default_family default
17 \paperfontsize default
25 \paperorientation portrait
28 \paragraph_separation skip
30 \quotes_language english
33 \paperpagestyle default
34 \tracking_changes false
43 A Set of APIs for a Third-Generation Trace Viewer
48 Pierre-Marc Fournier, Michel Dagenais, Mathieu Desnoyers
53 <pierre-marc.fournier _at_ polymtl.ca>
62 École Polytechnique de Montréal
73 \begin_layout Standard
74 This document proposes some APIs for a trace viewing and analysis infrastructure.
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.
89 Provide an infrastructure for fast, interactive visualization and analysis
90 of huge traces (>10 GB) on standard workstations
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
110 \begin_layout Itemize
111 Support live trace processing
114 \begin_layout Itemize
115 Allow merging of traces of different formats
118 \begin_layout Standard
119 \begin_inset Note Note
122 \begin_layout Itemize
123 Design the viewer in such a way that it can run in parallel on multi-core
125 \begin_inset Note Greyedout
128 \begin_layout Standard
129 (Is it worth it? Beware of complex locking issues)
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
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.
159 \begin_layout Section
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.
168 \begin_layout Section
169 Controlling the tracing of a system
172 \begin_layout Subsection
176 \begin_layout Standard
177 The goal of this API is to provide a portable way of controlling tracing
178 of heterogenous systems.
181 \begin_layout Standard
182 It should enable to do the following actions.
185 \begin_layout Itemize
186 Set the parameters of a trace (channels, buffering, destination of data
187 (file, network, process)...)
190 \begin_layout Itemize
191 Control the recording of events (start, stop, pause the trace)
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
200 \begin_layout Subsection
204 \begin_layout Itemize
205 List the static tracepoints available on a system
209 \begin_layout Standard
210 These may be static tracepoints (active or inactive) or dynamic tracepoints
211 (active or proposed).
215 \begin_layout Itemize
216 Add a new dynamic tracepoint
219 \begin_layout Itemize
220 Activate a tracepoint
223 \begin_layout Itemize
224 Deactivate a tracepoint
227 \begin_layout Itemize
228 List available probes
231 \begin_layout Itemize
232 Connect a probe to a tracepoint
235 \begin_layout Itemize
239 \begin_layout Itemize
243 \begin_layout Itemize
244 \begin_inset Note Greyedout
247 \begin_layout Standard
256 \begin_layout Section
260 \begin_layout Subsection
264 \begin_layout Subsubsection
268 \begin_layout Standard
269 Timestamps, at the framework level, should be in an architecture-independent
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)
274 An uncertainty value should accompany the timestamp.
275 Timestamps in cycles should be available if they are provided by the tracer.
278 \begin_layout Subsection
279 Low-level trace reading API
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.
287 \begin_layout Subsubsection
291 \begin_layout Itemize
292 get_supported_formats()
296 \begin_layout Standard
300 \begin_layout Standard
304 \begin_layout Itemize
305 a list of supported formats
309 \begin_layout Itemize
314 \begin_layout Standard
318 \begin_layout Itemize
323 \begin_layout Itemize
327 \begin_layout Itemize
328 other special url to establish a network connection
331 \begin_layout Itemize
336 \begin_layout Itemize
337 trace format (optional, for cases where auto detection would not work or
341 \begin_layout Standard
345 \begin_layout Itemize
350 \begin_layout Subsubsection
354 \begin_layout Itemize
358 \begin_layout Itemize
363 \begin_layout Standard
367 \begin_layout Standard
371 \begin_layout Itemize
372 the event currently pointed by the position pointer
376 \begin_layout Itemize
381 \begin_layout Standard
382 Advance the position pointer to the next event in the trace.
385 \begin_layout Standard
389 \begin_layout Standard
393 \begin_layout Itemize
398 \begin_layout Itemize
402 \begin_layout Itemize
403 Final end of trace (end of a non-live trace or of a completed live trace)
406 \begin_layout Itemize
407 No more events for now (end of a still running live trace)
412 \begin_layout Itemize
417 \begin_layout Standard
421 \begin_layout Itemize
425 \begin_layout Standard
430 \begin_layout Itemize
431 get_position_handle()
434 \begin_layout Itemize
435 seek_to_position_handle()
438 \begin_layout Itemize
439 destroy_position_handle()
442 \begin_layout Itemize
447 \begin_layout Standard
451 \begin_layout Standard
455 \begin_layout Itemize
456 the timestamp of the first event in the trace
460 \begin_layout Itemize
465 \begin_layout Standard
469 \begin_layout Standard
473 \begin_layout Itemize
474 the timestamp of the last event in the trace
478 \begin_layout Itemize
479 register_callback_new_event()
483 \begin_layout Standard
484 Register a callback that is called when a new event becomes available in
486 It is also called when the live trace ends.
489 \begin_layout Standard
493 \begin_layout Itemize
494 after (timestamp) : call only if the event occurent later than
499 \begin_layout Itemize
500 the callback function
501 \begin_inset Note Note
504 \begin_layout Standard
505 specify its args and return val
513 \begin_layout Standard
517 \begin_layout Itemize
518 Result (success or failure)
522 \begin_layout Subsection
523 High-level trace reading API
526 \begin_layout Standard
527 The goal of this API is to provide a uniform way for analyses and views
528 to obtain trace events from a traceset (merge of many traces or a single
529 trace), regardless of the system they were recorded on and of the tracer
533 \begin_layout Itemize
534 Request a range of events
538 \begin_layout Standard
542 \begin_layout Itemize
543 (implicitly) the traceset
546 \begin_layout Itemize
550 \begin_layout Itemize
551 stop timestamp (special value for infinity, for live traces)
554 \begin_layout Itemize
555 list of event types and callbacks
558 \begin_layout Itemize
559 filter with complex expressions
562 \begin_layout Itemize
563 private pointer to be passed to the callbacks
566 \begin_layout Standard
570 \begin_layout Itemize
571 handle to the request for cancelling it
575 \begin_layout Itemize
580 \begin_layout Standard
584 \begin_layout Itemize
585 the handle to the request
589 \begin_layout Subsection
593 \begin_layout Subsubsection
597 \begin_layout Itemize
598 Request the values of a given set of state variables at a point in time
602 \begin_layout Standard
606 \begin_layout Itemize
607 the list of state variables
610 \begin_layout Itemize
615 \begin_layout Itemize
616 Request all the states changes of a given set of state variables between
621 \begin_layout Standard
625 \begin_layout Itemize
626 the list of state variables
629 \begin_layout Itemize
633 \begin_layout Itemize
638 \begin_layout Subsubsection
642 \begin_layout Section
643 Describing event types
646 \begin_layout Subsection
650 \begin_layout Standard
651 Because tracepoints may be created dynamically, information about the descriptio
652 n of events is just as dynamic.
653 In this context, one simple way to communicate the event description informatio
654 n to upper layers would be to send them as events, as it is done in recent
656 The core events used to describe other events are the only ones whose descripti
657 on is hardcoded in the framework.
660 \begin_layout Standard
661 These event-type-describing events could then be received and interpreted
662 by a module, the Event Description Service, which would be a client to
663 the high-level tracing API at the same level as normal views and analyses.
664 It would store the information and allow the other views and analyses to
665 access it via this API.
668 \begin_layout Subsection
669 Events-describing events
672 \begin_layout Itemize
673 Event type declaration event
677 \begin_layout Standard
678 Announce the existence of an event type
681 \begin_layout Itemize
686 \begin_layout Itemize
687 Argument declaration event
691 \begin_layout Standard
692 Announce the existence of an event argument
695 \begin_layout Itemize
699 \begin_layout Itemize
703 \begin_layout Itemize
708 \begin_layout Itemize
713 \begin_layout Standard
714 Announce that an event type ceased to exist
717 \begin_layout Itemize
722 \begin_layout Subsection
723 Event type description API
726 \begin_layout Itemize
727 Get the list of all the event types
730 \begin_layout Itemize
731 Find an event type by name
734 \begin_layout Itemize
735 Get the number of arguments of an event
738 \begin_layout Itemize
739 Get the list of arguments of an event
742 \begin_layout Itemize
743 Find an argument by name
746 \begin_layout Itemize
747 Get the type of an argument of an event type
750 \begin_layout Itemize
751 Get a string representation of an argument of any type, given an event that
752 contains it an instance of it
755 \begin_layout Itemize
756 Get an integer representation of an integer argument, a floating-point represent
757 ation of a floating-point argument
760 \begin_layout Itemize
761 Functions for accessing other types
764 \begin_layout Section
768 \begin_layout Subsection
772 \begin_layout Standard
773 Events contain the following information.
776 \begin_layout Itemize
780 \begin_layout Itemize
781 Event type identifier
785 \begin_layout Standard
789 \begin_layout Itemize
790 an event id (integer)
793 \begin_layout Itemize
794 an event name (string)
798 \begin_layout Itemize
799 The name of the machine it occured on
802 \begin_layout Subsection
806 \begin_layout Itemize
807 get the event type identifier
810 \begin_layout Itemize
814 \begin_layout Itemize
815 get the name of the machine on which the event occured
818 \begin_layout Itemize
819 get information on the type of tracing technology that was used
822 \begin_layout Itemize
823 get the corresponding tracepoint (machine/tracing technology/name/location
824 in code(if available))