= Introduction =
-The purpose of the '''Tracing Monitoring Framework (TMF)''' is to facilitate the integration of tracing and monitoring tools into Eclipse, to provide out-of-the-box generic functionalities/views and provide extension mechanisms of the base functionalities for application specific purposes.
+The purpose of '''Trace Compass''' is to facilitate the integration of tracing
+and monitoring tools into Eclipse, to provide out-of-the-box generic
+functionalities/views and provide extension mechanisms of the base
+functionalities for application specific purposes.
+
+This guide goes over the internal components of the Trace Compass framework. It
+should help developers trying to add new capabilities (support for new trace
+type, new analysis or views, etc.) to the framework. End-users, using the RCP
+for example, should not have to worry about the concepts explained here.
= Implementing a New Trace Type =
-The framework can easily be extended to support more trace types. To make a new trace type, one must define the following items:
+The framework can easily be extended to support more trace types. To make a new
+trace type, one must define the following items:
* The event type
* The trace reader
* The ''org.eclipse.linuxtools.tmf.core.tracetype'' plug-in extension point
* (Optional) The ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension point
-The '''event type''' must implement an ''ITmfEvent'' or extend a class that implements an ''ITmfEvent''. Typically it will extend ''TmfEvent''. The event type must contain all the data of an event. The '''trace reader''' must be of an ''ITmfTrace'' type. The ''TmfTrace'' class will supply many background operations so that the reader only needs to implement certain functions. The '''trace context''' can be seen as the internals of an iterator. It is required by the trace reader to parse events as it iterates the trace and to keep track of its rank and location. It can have a timestamp, a rank, a file position, or any other element, it should be considered to be ephemeral. The '''trace location''' is an element that is cloned often to store checkpoints, it is generally persistent. It is used to rebuild a context, therefore, it needs to contain enough information to unambiguously point to one and only one event. Finally the ''tracetype'' plug-in extension associates a given trace, non-programmatically to a trace type for use in the UI.
+The '''event type''' must implement an ''ITmfEvent'' or extend a class that
+implements an ''ITmfEvent''. Typically it will extend ''TmfEvent''. The event
+type must contain all the data of an event.
+
+The '''trace reader''' must be of an ''ITmfTrace'' type. The ''TmfTrace'' class
+will supply many background operations so that the reader only needs to
+implement certain functions.
+
+The '''trace context''' can be seen as the internals of an iterator. It is
+required by the trace reader to parse events as it iterates the trace and to
+keep track of its rank and location. It can have a timestamp, a rank, a file
+position, or any other element, it should be considered to be ephemeral.
+
+The '''trace location''' is an element that is cloned often to store
+checkpoints, it is generally persistent. It is used to rebuild a context,
+therefore, it needs to contain enough information to unambiguously point to one
+and only one event. Finally the ''tracetype'' plug-in extension associates a
+given trace, non-programmatically to a trace type for use in the UI.
+
+== Optional Trace Type Attributes ==
+
+After defining the trace type as described in the previous chapters it is
+possible to define optional attributes for the trace type.
+
+=== Default Editor ===
+
+The '''defaultEditor''' attribute of the '''org.eclipse.linuxtools.tmf.ui.tracetypeui'''
+extension point allows for configuring the editor to use for displaying the
+events. If omitted, the ''TmfEventsEditor'' is used as default.
+
+To configure an editor, first add the '''defaultEditor''' attribute to the trace
+type in the extension definition. This can be done by selecting the trace type
+in the plug-in manifest editor. Then click the right mouse button and select
+'''New -> defaultEditor''' in the context sensitive menu. Then select the newly
+added attribute. Now you can specify the editor id to use on the right side of
+the manifest editor. For example, this attribute could be used to implement an
+extension of the class ''org.eclipse.ui.part.MultiPageEditor''. The first page
+could use the ''TmfEventsEditor''' to display the events in a table as usual and
+other pages can display other aspects of the trace.
+
+=== Events Table Type ===
+
+The '''eventsTableType''' attribute of the '''org.eclipse.linuxtools.tmf.ui.tracetypeui'''
+extension point allows for configuring the events table class to use in the
+default events editor. If omitted, the default events table will be used.
+
+To configure a trace type specific events table, first add the
+'''eventsTableType''' attribute to the trace type in the extension definition.
+This can be done by selecting the trace type in the plug-in manifest editor.
+Then click the right mouse button and select '''New -> eventsTableType''' in the
+context sensitive menu. Then select the newly added attribute and click on
+''class'' on the right side of the manifest editor. The new class wizard will
+open. The ''superclass'' field will be already filled with the class ''org.eclipse.tracecompass.tmf.ui.viewers.events.TmfEventsTable''.
+
+By using this attribute, a table with different columns than the default columns
+can be defined. See the class
+''org.eclipse.tracecompass.internal.gdbtrace.ui.views.events.GdbEventsTable''
+for an example implementation.
+
+== Other Considerations ==
+
+Other views and components may provide additional features that are active only
+when the event or trace type class implements certain additional interfaces.
+
+=== Collapsing of repetitive events ===
+
+By implementing the interface
+''org.eclipse.tracecompass.tmf.core.event.collapse.ITmfCollapsibleEvent'' the
+event table will allow to collapse repetitive events by selecting the menu item
+'''Collapse Events''' after pressing the right mouse button in the table.
+
+== Best Practices ==
+
+* Do not load the whole trace in RAM, it will limit the size of the trace that can be read.
+* Reuse as much code as possible, it makes the trace format much easier to maintain.
+* Use Eclipse's editor instead of editing the XML directly.
+* Do not forget Java supports only signed data types, there may be special care needed to handle unsigned data.
+* If the support for your trace has custom UI elements (like icons, views, etc.), split the core and UI parts in separate plugins, named identically except for a ''.core'' or ''.ui'' suffix.
+** Implement the ''tmf.core.tracetype'' extension in the core plugin, and the ''tmf.ui.tracetypeui'' extension in the UI plugin if applicable.
== An Example: Nexus-lite parser ==
=== Description of the file ===
-This is a very small subset of the nexus trace format, with some changes to make it easier to read. There is one file. This file starts with 64 Strings containing the event names, then an arbitrarily large number of events. The events are each 64 bits long. the first 32 are the timestamp in microseconds, the second 32 are split into 6 bits for the event type, and 26 for the data payload.
+This is a very small subset of the nexus trace format, with some changes to make
+it easier to read. There is one file. This file starts with 64 Strings
+containing the event names, then an arbitrarily large number of events. The
+events are each 64 bits long. the first 32 are the timestamp in microseconds,
+the second 32 are split into 6 bits for the event type, and 26 for the data
+payload.
-The trace type will be made of two parts, part 1 is the event description, it is just 64 strings, comma seperated and then a line feed.
+The trace type will be made of two parts, part 1 is the event description, it is
+just 64 strings, comma separated and then a line feed.
<pre>
Startup,Stop,Load,Add, ... ,reserved\n
=== NexusLite Plug-in ===
-Create a '''New''', '''Project...''', '''Plug-in Project''', set the title to '''com.example.nexuslite''', click '''Next >''' then click on '''Finish'''.
+Create a '''New''', '''Project...''', '''Plug-in Project''', set the title to
+'''com.example.nexuslite''', click '''Next >''' then click on '''Finish'''.
Now the structure for the Nexus trace Plug-in is set up.
-Add a dependency to TMF core and UI by opening the '''MANIFEST.MF''' in '''META-INF''', selecting the '''Dependencies''' tab and '''Add ...''' '''org.eclipse.tracecompass.tmf.core''' and '''org.eclipse.tracecompass.tmf.ui'''.
+Add a dependency to TMF core and UI by opening the '''MANIFEST.MF''' in
+'''META-INF''', selecting the '''Dependencies''' tab and '''Add ...'''
+'''org.eclipse.tracecompass.tmf.core''' and '''org.eclipse.tracecompass.tmf.ui'''.
[[Image:images/NTTAddDepend.png]]<br>
[[Image:images/NTTSelectProjects.png]]<br>
Here we used a confidence of 20, to leave "room" for more specific trace types
in the Nexus format that could be defined in TMF.
-The '''initTrace''' function will read the event names, and find where the data starts. After this, the number of events is known, and since each event is 8 bytes long according to the specs, the seek is then trivial.
+The '''initTrace''' function will read the event names, and find where the data
+starts. After this, the number of events is known, and since each event is 8
+bytes long according to the specs, the seek is then trivial.
The '''seek''' here will just reset the reader to the right location.
-The '''parseEvent''' method needs to parse and return the current event and store the current location.
+The '''parseEvent''' method needs to parse and return the current event and
+store the current location.
-The '''getNext''' method (in base class) will read the next event and update the context. It calls the '''parseEvent''' method to read the event and update the location. It does not need to be overridden and in this example it is not. The sequence of actions necessary are parse the next event from the trace, create an '''ITmfEvent''' with that data, update the current location, call '''updateAttributes''', update the context then return the event.
+The '''getNext''' method (in base class) will read the next event and update the
+context. It calls the '''parseEvent''' method to read the event and update the
+location. It does not need to be overridden and in this example it is not. The
+sequence of actions necessary are parse the next event from the trace, create an
+'''ITmfEvent''' with that data, update the current location, call
+'''updateAttributes''', update the context then return the event.
Traces will typically implement an index, to make seeking faster. The index can
be rebuilt every time the trace is opened. Alternatively, it can be saved to
=== Trace Location ===
-The trace location will be a long, representing the rank in the file. The '''TmfLongLocation''' will be the used, once again, no code is required.
+The trace location will be a long, representing the rank in the file. The
+'''TmfLongLocation''' will be the used, once again, no code is required.
-=== The ''org.eclipse.linuxtools.tmf.core.tracetype'' and ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension point ===
+=== The ''org.eclipse.linuxtools.tmf.core.tracetype'' and ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension points ===
One should use the ''tmf.core.tracetype'' extension point in their own plug-in.
In this example, the Nexus trace plug-in will be modified.
-The '''plugin.xml''' file in the ui plug-in needs to be updated if one wants users to access the given event type. It can be updated in the Eclipse plug-in editor.
+The '''plugin.xml''' file in the ui plug-in needs to be updated if one wants
+users to access the given event type. It can be updated in the Eclipse plug-in
+editor.
# In Extensions tab, add the '''org.eclipse.linuxtools.tmf.core.tracetype''' extension point.
[[Image:images/NTTExtension.png]]<br>
The '''category''' (optional) is the container in which this trace type will be stored.
-# (Optional) To also add UI-specific properties to your trace type, use the '''org.eclipse.linuxtools.tmf.ui.tracetypeui''' extension. To do that,
-'''right click''' on the extension then in the context menu, go to
-'''New >''', '''type'''.
+# (Optional) To also add UI-specific properties to your trace type, use the '''org.eclipse.linuxtools.tmf.ui.tracetypeui''' extension. To do that, '''right click''' on the extension then in the context menu, go to '''New >''', '''type'''.
The '''tracetype''' here is the '''id''' of the
''org.eclipse.linuxtools.tmf.core.tracetype'' mentioned above.
[[Image:images/NTTPluginxmlComplete.png]]<br>
-== Other Considerations ==
-The ''org.eclipse.tracecompass.tmf.ui.viewers.events.TmfEventsTable'' provides additional features that are active when the event class (defined in '''event type''') implements certain additional interfaces.
-
-=== Collapsing of repetitive events ===
-By implementing the interface ''org.eclipse.tracecompass.tmf.core.event.collapse.ITmfCollapsibleEvent'' the events table will allow to collapse repetitive events by selecting the menu item '''Collapse Events''' after pressing the right mouse button in the table.
-
-== Best Practices ==
-
-* Do not load the whole trace in RAM, it will limit the size of the trace that can be read.
-* Reuse as much code as possible, it makes the trace format much easier to maintain.
-* Use Eclipse's editor instead of editing the XML directly.
-* Do not forget Java supports only signed data types, there may be special care needed to handle unsigned data.
-* If the support for your trace has custom UI elements (like icons, views, etc.), split the core and UI parts in separate plugins, named identically except for a ''.core'' or ''.ui'' suffix.
-** Implement the ''tmf.core.tracetype'' extension in the core plugin, and the ''tmf.ui.tracetypeui'' extension in the UI plugin if applicable.
-
-== Download the Code ==
-
-The described example is available in the
-org.eclipse.tracecompass.tracing.examples.(tests.)trace.nexus packages with a
-trace generator and a quick test case.
-
-== Optional Trace Type Attributes ==
-
-After defining the trace type as described in the previous chapters it is possible to define optional attributes for the trace type.
-
-=== Default Editor ===
-
-The '''defaultEditor''' attribute of the '''org.eclipse.linuxtools.tmf.ui.tracetypeui'''
-extension point allows for configuring the editor to use for displaying the
-events. If omitted, the ''TmfEventsEditor'' is used as default.
-
-To configure an editor, first add the '''defaultEditor''' attribute to the trace
-type in the extension definition. This can be done by selecting the trace type
-in the plug-in manifest editor. Then click the right mouse button and select
-'''New -> defaultEditor''' in the context sensitive menu. Then select the newly
-added attribute. Now you can specify the editor id to use on the right side of
-the manifest editor. For example, this attribute could be used to implement an
-extension of the class ''org.eclipse.ui.part.MultiPageEditor''. The first page
-could use the ''TmfEventsEditor''' to display the events in a table as usual and
-other pages can display other aspects of the trace.
-
-=== Events Table Type ===
-
-The '''eventsTableType''' attribute of the '''org.eclipse.linuxtools.tmf.ui.tracetypeui'''
-extension point allows for configuring the events table class to use in the
-default events editor. If omitted, the default events table will be used.
-
-To configure a trace type specific events table, first add the
-'''eventsTableType''' attribute to the trace type in the extension definition.
-This can be done by selecting the trace type in the plug-in manifest editor.
-Then click the right mouse button and select '''New -> eventsTableType''' in the
-context sensitive menu. Then select the newly added attribute and click on
-''class'' on the right side of the manifest editor. The new class wizard will
-open. The ''superclass'' field will be already filled with the class ''org.eclipse.tracecompass.tmf.ui.viewers.events.TmfEventsTable''.
-
-By using this attribute, a table with different columns than the default columns
-can be defined. See the class org.eclipse.tracecompass.internal.gdbtrace.ui.views.events.GdbEventsTable
-for an example implementation.
-
= View Tutorial =
This tutorial describes how to create a simple view using the TMF framework and the SWTChart library. SWTChart is a library based on SWT that can draw several types of charts including a line chart which we will use in this tutorial. We will create a view containing a line chart that displays time stamps on the X axis and the corresponding event values on the Y axis.
projects / deliverable / tracecompass.git / commitdiff
