1fde1b39 |
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 |
6e3755ba |
292 | void get_supported_formats(void) |
1fde1b39 |
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 |
6e3755ba |
355 | bool close(struct trace *tr) |
1fde1b39 |
356 | \end_layout |
357 | |
358 | \begin_layout Itemize |
6e3755ba |
359 | struct event *current_event(struct trace *) |
1fde1b39 |
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 |
6e3755ba |
377 | bool advance(struct trace *tr) |
1fde1b39 |
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 |
6e3755ba |
413 | bool seek_time(struct trace *tr, struct trace_cursor *cur) |
1fde1b39 |
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 |
6e3755ba |
431 | struct trace_cursor *trace_new_cursor_beginning(struct trace *tr) |
1fde1b39 |
432 | \end_layout |
433 | |
6e3755ba |
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 |
1fde1b39 |
440 | \begin_layout Itemize |
6e3755ba |
441 | struct trace_cursor *trace_cursor_copy(struct trace_cursor *cur) |
1fde1b39 |
442 | \end_layout |
443 | |
444 | \begin_layout Itemize |
6e3755ba |
445 | void trace_cursor_destroy(struct trace_cursor_destroy *) |
1fde1b39 |
446 | \end_layout |
447 | |
448 | \begin_layout Itemize |
6e3755ba |
449 | struct trace_time get_time_start(struct trace *tr) |
1fde1b39 |
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 |
6e3755ba |
467 | struct trace_time get_time_end(struct trace *tr) |
1fde1b39 |
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 |
6e3755ba |
485 | register_callback_new_event(struct trace *tr, struct trace_time after, void |
486 | (*cb)(void)) |
1fde1b39 |
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 |
6e3755ba |
507 | cb: the callback function |
1fde1b39 |
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 |