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 Allow efficient manipulation of traces that are larger than the system memory
114 \begin_layout Itemize
115 Support processing of live traces
118 \begin_layout Itemize
119 Allow merging of traces of different formats
122 \begin_layout Itemize
123 Design with both command line utilities (C language) and graphical interfaces
124 (Java and others) in mind, sharing code and standardizing interfaces as
129 \begin_layout Standard
130 Both command-line interfaces and graphical interfaces have an important
131 role to play in trace analysis.
132 While graphical interfaces allow for complex views, command-line utilities
133 can be used quickly in more environments; they can also be more convenient
134 in some circumstances.
135 A good design should be such that they can share code and APIs.
139 \begin_layout Section
143 \begin_layout Itemize
144 All data structures must be accessed through API methods, in order to allow
145 for internal change without breaking compatibility.
148 \begin_layout Itemize
149 The APIs in this document are described as C functions and datatypes.
150 When an operation applies to an abstraction that could be an object in
151 an object-oriented language, it is specified as the first argument of the
155 \begin_layout Subsection
159 \begin_layout Standard
160 The framework needs to represent points in the time line and time ranges.
161 This is done by two data structures, respectively:
164 \begin_layout Itemize
168 \begin_layout Itemize
169 struct trace_time_range
172 \begin_layout Standard
173 The preferred representation for times is seconds.
176 \begin_layout Standard
177 Ranges are a span between two points in time.
178 They are represented as these two points.
179 One or both of them can have the special value
186 \begin_layout Standard
187 Each time is accompanied by an uncertainty value.
190 \begin_layout Section
191 Low level reading of traces
194 \begin_layout Subsection
198 \begin_layout Standard
199 This API presents a uniform way of accessing traces at a low level, that
200 is to access randomly the events of the trace in an physical-encoding-independa
204 \begin_layout Standard
205 \begin_inset Note Note
208 \begin_layout Subsubsection
212 \begin_layout Standard
213 Timestamps, at the framework level, should be in an architecture-independent
215 One possibility would be to have them stored in seconds (with decimals).
216 Offsetting, if necessary, could be handled by the traceset (trace merging)
218 An uncertainty value should accompany the timestamp.
219 Timestamps in cycles should be available if they are provided by the tracer.
227 \begin_layout Standard
228 \begin_inset Note Note
231 \begin_layout Subsubsection
235 \begin_layout Itemize
236 void get_supported_formats(void)
240 \begin_layout Standard
244 \begin_layout Standard
248 \begin_layout Itemize
249 a list of supported formats
253 \begin_layout Itemize
258 \begin_layout Standard
262 \begin_layout Itemize
267 \begin_layout Itemize
271 \begin_layout Itemize
272 other special url to establish a network connection
275 \begin_layout Itemize
280 \begin_layout Itemize
281 trace format (optional, for cases where auto detection would not work or
285 \begin_layout Standard
289 \begin_layout Itemize
298 \begin_layout Subsection
299 Methods of the Low Level Trace Reading API
302 \begin_layout Itemize
303 void close(struct trace *tr)
307 \begin_layout Standard
308 Close the trace and unallocate all resources associated to this struct trace
309 including the handle.
310 After this call, tr is invalid and its memory is freed.
314 \begin_layout Itemize
315 struct event *current_event(struct trace *, struct cursor *cur)
319 \begin_layout Standard
323 \begin_layout Standard
327 \begin_layout Itemize
328 the event currently pointed by the position pointer
331 \begin_layout Itemize
332 NULL, if current_event is called on a new cursor that is positioned before
333 the beginning of the trace
337 \begin_layout Itemize
338 int advance(struct trace *tr, struct trace_cursor *cur)
342 \begin_layout Standard
343 Advance the cursor to the next event in the trace.
346 \begin_layout Standard
350 \begin_layout Itemize
354 \begin_layout Itemize
355 cur: the cursor that should be advanced
358 \begin_layout Standard
362 \begin_layout Itemize
367 \begin_layout Itemize
368 Success (TRACE_ADVANCE_OK)
371 \begin_layout Itemize
372 The cursor was not advanced because the end of trace is reached (end of
373 a non-live trace or of a completed live trace) (TRACE_ADVANCE_END)
376 \begin_layout Itemize
377 The cursor was not advanced because no new events are available at this
378 time (with a live trace that is still running) (TRACE_ADVANCE_TRY_AGAIN)
383 \begin_layout Itemize
384 int seek_time(struct trace *tr, struct trace_cursor *cur, struct trace_time
389 \begin_layout Standard
393 \begin_layout Itemize
394 tr: the trace that should be seeked
397 \begin_layout Itemize
398 cur: the cursor to seek
401 \begin_layout Itemize
402 time: the time to seek to
405 \begin_layout Standard
409 \begin_layout Itemize
413 \begin_layout Itemize
414 != 0: time out of range
418 \begin_layout Itemize
419 struct trace_cursor *trace_new_cursor(struct trace *tr)
423 \begin_layout Standard
424 Return a new cursor associated to the trace.
425 The position of this new cursor is just before the first event, therefore
426 advance() must be called before reading the first event.
430 \begin_layout Itemize
431 struct trace_cursor *trace_cursor_copy(struct trace_cursor *cur)
435 \begin_layout Standard
439 \begin_layout Standard
443 \begin_layout Itemize
444 cur: the cursor to copy
447 \begin_layout Standard
451 \begin_layout Itemize
452 a new cursor that is at the same location as cur
456 \begin_layout Itemize
457 void trace_cursor_destroy(struct trace_cursor *cur)
461 \begin_layout Standard
462 Free all resources associated to a cursor.
463 After this call, cur is invalid.
466 \begin_layout Standard
470 \begin_layout Itemize
471 cur: the cursor to destroy
475 \begin_layout Itemize
476 struct trace_time get_time_start(struct trace *tr)
480 \begin_layout Standard
484 \begin_layout Itemize
488 \begin_layout Standard
492 \begin_layout Itemize
493 the timestamp of the first event in the trace
497 \begin_layout Itemize
498 struct trace_time get_time_end(struct trace *tr)
502 \begin_layout Standard
506 \begin_layout Standard
510 \begin_layout Itemize
511 the timestamp of the last event in the trace
515 \begin_layout Itemize
516 register_callback_new_event(struct trace *tr, struct trace_time after, void
517 (*cb)(struct trace *))
521 \begin_layout Standard
522 Register a callback that is called when a new event becomes available in
524 It is also called when the live trace ends.
527 \begin_layout Standard
531 \begin_layout Itemize
532 after (timestamp) : call only if the timestamp of the event is later than
538 \begin_layout Itemize
539 cb: the callback function
540 \begin_inset Note Note
543 \begin_layout Standard
544 specify its args and return val
552 \begin_layout Standard
556 \begin_layout Itemize
557 Result (success or failure)
561 \begin_layout Section
562 High level reading of traces
565 \begin_layout Standard
566 When reading/analyzing/viewing several traces of heterogenous types, these
567 traces are read by translator modules, which export the Low Level Trace
569 The traceset service then uses this API to read each of these traces individual
571 It may apply timestamp offsetting or other synchronization techniques.
572 To allow views and analyses to access events, it in turn exports the High
573 Level Trace Reading API.
576 \begin_layout Standard
577 The goal of this API is to provide a uniform way for analyses and views
578 to obtain large sets of trace events from a traceset (merge of many traces
582 \begin_layout Subsection
583 Methods of the high-level trace reading API
586 \begin_layout Itemize
587 struct request_handle *traceset_new_event_request(struct traceset *tr, struct
588 trace_time t1, struct trace_time t2, struct event_filter *filter, void
589 (*cb)(void *data, ), void *data)
593 \begin_layout Standard
594 Request a range of events
597 \begin_layout Standard
601 \begin_layout Itemize
605 \begin_layout Itemize
609 \begin_layout Itemize
610 t2: stop timestamp (special value for infinity, for live traces)
613 \begin_layout Itemize
614 filter: filter with complex expressions
617 \begin_layout Itemize
618 data: private pointer to be passed to the callback
621 \begin_layout Standard
625 \begin_layout Itemize
626 handle to the request for cancelling it
630 \begin_layout Itemize
631 void event_request_cancel(struct request_handle *req)
635 \begin_layout Standard
639 \begin_layout Standard
643 \begin_layout Itemize
644 req: the handle to the request
648 \begin_layout Subsection
652 \begin_layout Standard
653 States are key/value pairs associated with a time range.
654 Keys can be (and generally are) duplicated as long as they do not apply
655 to overlapping ranges.
658 \begin_layout Standard
659 Keys are character strings.
662 \begin_layout Standard
663 Values may be of various types:
666 \begin_layout Itemize
670 \begin_layout Itemize
674 \begin_layout Itemize
678 \begin_layout Itemize
679 blob (binary block of arbitrary length)
682 \begin_layout Itemize
686 \begin_layout Itemize
690 \begin_layout Standard
691 The state information must be persistent between executions of the framework.
694 \begin_layout Standard
695 It is possible to assign a state to the range -infinity..infinity to indicate
696 that it is global to the trace.
699 \begin_layout Standard
700 The key names should be hierarchical.
703 \begin_layout Subsubsection
707 \begin_layout Itemize
708 struct state_value *state_get_value_at_time(char *key, struct trace_time
713 \begin_layout Standard
714 Request the value of a given key at a point in time
717 \begin_layout Standard
721 \begin_layout Itemize
722 var: the state variables (string)
725 \begin_layout Itemize
729 \begin_layout Standard
733 \begin_layout Itemize
738 \begin_layout Itemize
739 struct state_value_range **state_get_values_in_range(char *key, struct state_val
740 ue *val, struct trace_time_range range)
744 \begin_layout Standard
745 Request all the states changes of a given set of state variables between
749 \begin_layout Standard
753 \begin_layout Itemize
757 \begin_layout Itemize
758 range: the time range
762 \begin_layout Itemize
763 Other functions for getting values for a set of keys at once?
766 \begin_layout Subsubsection
770 \begin_layout Itemize
771 set a particular state
774 \begin_layout Itemize
778 \begin_layout Section
779 Describing event types
782 \begin_layout Subsection
786 \begin_layout Standard
787 Because tracepoints may be created dynamically, information about the descriptio
788 n of events is just as dynamic.
789 In this context, one simple way to communicate the event description informatio
790 n to upper layers would be to send them as events, as it is done in recent
792 The core events used to describe other events are the only ones whose descripti
793 on is hardcoded in the framework.
796 \begin_layout Standard
797 These event-type-describing events could then be received and interpreted
798 by the Event Description Service, which would be a client to the high-level
799 tracing API at the same level as normal views and analyses.
800 It would store the information and allow the other views and analyses to
801 access it via this API.
804 \begin_layout Standard
805 Each event has a timestamp, a name and arguments of various types.
806 The framework should support the following types:
809 \begin_layout Itemize
813 \begin_layout Itemize
817 \begin_layout Itemize
821 \begin_layout Itemize
825 \begin_layout Itemize
829 \begin_layout Subsection
830 Events-describing events
833 \begin_layout Itemize
834 Event type declaration event
838 \begin_layout Standard
839 Announce the existence of an event type
842 \begin_layout Itemize
847 \begin_layout Itemize
848 Argument declaration event
852 \begin_layout Standard
853 Announce the existence of an event argument
856 \begin_layout Itemize
860 \begin_layout Itemize
864 \begin_layout Itemize
869 \begin_layout Itemize
874 \begin_layout Standard
875 Announce that an event type ceased to exist
878 \begin_layout Itemize
883 \begin_layout Subsection
884 Event type description API
887 \begin_layout Standard
888 The event type description service provides the following functions.
891 \begin_layout Itemize
892 GArray<struct event_type *> *traceset_get_all_event_types(struct traceset
897 \begin_layout Standard
898 Get the list of all the event types
901 \begin_layout Standard
905 \begin_layout Itemize
906 ts: the traceset of which we want the event types
909 \begin_layout Standard
913 \begin_layout Itemize
914 A GArray of of struct event_type.
915 The GArray must be gfree()'d by the caller when it is done reading it.
919 \begin_layout Itemize
920 struct event_type *traceset_get_event_type_by_name(struct traceset *ts,
925 \begin_layout Standard
926 Find an event type by name
929 \begin_layout Standard
933 \begin_layout Itemize
934 ts: the traceset of which we want the event type
937 \begin_layout Itemize
938 name: the name of the of the event type we are looking for
941 \begin_layout Standard
945 \begin_layout Itemize
946 A pointer to the event type (must not be free'd) or NULL if not found
950 \begin_layout Itemize
951 GArray<struct event arg *> *event_type_get_all_args(struct event_type *evtype)
955 \begin_layout Standard
956 Get the list of arguments of an event
959 \begin_layout Standard
963 \begin_layout Itemize
964 eventype: the event type of which we want the arguments
967 \begin_layout Standard
971 \begin_layout Itemize
972 A GArray of struct event_args.
973 The GArray must be gfree()'d by the caller when it is done reading it.
977 \begin_layout Itemize
978 struct event_arg *event_type_get_arg_by_name(struct event_type *evtype)
982 \begin_layout Standard
983 Find an argument by name
987 \begin_layout Itemize
988 Functions for accessing struct event_arg fields
991 \begin_layout Section
995 \begin_layout Subsection
999 \begin_layout Standard
1000 Events contain the following information.
1003 \begin_layout Itemize
1007 \begin_layout Itemize
1008 Event type identifier - an event id (integer) - hidden to the API users,
1009 manipulated as pointers/references to struct event_type
1012 \begin_layout Itemize
1013 A reference to the trace it was in
1016 \begin_layout Subsection
1017 Event inspecting API
1020 \begin_layout Itemize
1021 struct event_type *event_get_type(struct traceset *ts, struct event *ev)
1025 \begin_layout Standard
1026 get the event type corresponding to an event
1029 \begin_layout Standard
1033 \begin_layout Itemize
1037 \begin_layout Itemize
1041 \begin_layout Standard
1045 \begin_layout Itemize
1046 The event type or NULL if no information
1050 \begin_layout Itemize
1051 struct trace_time event_get_time(struct event *ev)
1055 \begin_layout Standard
1060 \begin_layout Itemize
1061 struct trace *event_get_trace(struct event *ev)
1064 \begin_layout Itemize
1065 get the name of the machine on which the event occured or other location
1069 \begin_layout Itemize
1070 get information on the type of tracing technology that was used
1073 \begin_layout Itemize
1074 get the corresponding tracepoint (machine/tracing technology/name/location
1075 in code(if available))
1078 \begin_layout Itemize
1079 uint32 event_read_arg_uint32(struct event *ev, struct event_arg *arg)
1082 \begin_layout Itemize
1083 int32 event_read_arg_int32(struct event *ev, struct event_arg *arg)
1086 \begin_layout Itemize
1087 uint64 event_read_arg_uint64(struct event *ev, struct event_arg *arg)
1090 \begin_layout Itemize
1091 int64 event_read_arg_int64(struct event *ev, struct event_arg *arg)
1094 \begin_layout Itemize
1095 float32 event_read_arg_float32(struct event *ev, struct event_arg *arg)
1098 \begin_layout Itemize
1099 float64 event_read_arg_float64(struct event *ev, struct event_arg *arg)
1102 \begin_layout Section
1106 \begin_layout Standard
1107 A filtering API is proposed.
1110 \begin_layout Section
1111 Controlling the tracing of a system
1114 \begin_layout Subsection
1118 \begin_layout Standard
1119 The goal of this API is to provide a portable way of controlling tracing
1120 of heterogenous systems.
1123 \begin_layout Standard
1124 It should enable to do the following actions.
1127 \begin_layout Itemize
1128 Set the parameters of a trace (channels, buffering, destination of data
1129 (file, network, process)...)
1132 \begin_layout Itemize
1133 Control the recording of events (start, stop, pause the trace)
1136 \begin_layout Itemize
1137 Create tracepoints (on dynamic tracers) and control which tracepoints are
1138 activated (some may be at trace level, others might only permit system
1142 \begin_layout Subsection
1146 \begin_layout Itemize
1147 List the static tracepoints available on a system
1151 \begin_layout Standard
1152 These may be static tracepoints (active or inactive) or dynamic tracepoints
1153 (active or proposed).
1157 \begin_layout Itemize
1158 Add a new dynamic tracepoint
1161 \begin_layout Itemize
1162 Activate a tracepoint
1165 \begin_layout Itemize
1166 Deactivate a tracepoint
1169 \begin_layout Itemize
1170 List available probes
1173 \begin_layout Itemize
1174 Connect a probe to a tracepoint
1177 \begin_layout Itemize
1181 \begin_layout Itemize
1185 \begin_layout Itemize
1186 \begin_inset Note Greyedout
1189 \begin_layout Standard