= 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 trace type
* The trace context
* The trace location
* 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 type''' must be of an ''ITmfTrace'' type. The ''TmfTrace'' class
+will supply many background operations so that the reader only needs to
+implement certain functions. This includes the ''event aspects'' for events of
+this trace type. See the section below.
+
+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.
+
+== Event Aspects ==
+
+In Trace Compass, an ''event aspect'' represents any type of information that
+can be extracted from a trace event. The simple case is information that is
+present directly in the event. For example, the timestamp of an event, a field
+of an LTTng event, or the "payload" that is on the same line of a text trace
+entry. But it could also be the result of an indirect operation, for example a
+state system query at the timestamp of the given event (see the section
+[[#Generic State System]]).
+
+All aspects should implement the '''ITmfEventAspect''' interface. The important
+method in there is ''resolve(ITmfEvent)'', which tells this aspect what to
+output for a given event. The singleton pattern fits well for pre-defined aspect
+classes, in general.
+
+The aspects defined for a trace type determine the initial columns in the Event
+Table, as well as the elements on which the trace can be filtered, among other
+things.
+
+=== Base and custom aspects ===
+
+Some base aspects are defined in '''TmfTrace#BASE_ASPECTS'''. They use generic
+methods found in '''ITmfEvent''', so they should be applicable for any event
+type defined in the framework. If one does not override
+'''TmfTrace#getEventAspects''', then only the base aspects will be used with
+this trace.
+
+Overriding the method does not append to this list, it replaces it. So if you
+wish to define additional aspects for a new trace type, do not forget to include
+the BASE_ASPECTS you want to use, if any, within the list.
+
+The order of the elements in the returned ''Iterable'' may matter to other
+components. For instance, the initial ordering of the columns in the Events
+Table will match it.
+
+Defining additional aspects allows to expose more data from the trace events
+without having to update all the views using the aspects API.
+
+=== Creating event aspects programmatically ===
+
+Another advantage of event aspects is that they can be created programmatically,
+without having to modify the base trace or event classes. A new analysis
+applying to a pre-existing trace type may wish to define additional aspects to
+make its job easier.
+
+While the notion of event aspects should not be exposed to users directly, it is
+possible to create new aspects based on user input. For example, an "event
+field" dialog could ask the user to enter a field name, which would then create
+an aspect that would look for the value of a field with this name in every
+event. The user could then be able to display or filter on this aspect.
+
+== 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.linuxtools.tmf.core''' and '''org.eclipse.linuxtools.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>
* parseEvent (read the next element in the trace)
For reference, there is an example implementation of the Nexus Trace file in
-org.eclipse.linuxtools.tracing.examples.core.trace.nexus.NexusTrace.java.
+org.eclipse.tracecompass.tracing.examples.core.trace.nexus.NexusTrace.java.
-In this example, the '''validate''' function checks first checks if the file
+In this example, the '''validate''' function first checks if the file
exists, then makes sure that it is really a file, and not a directory. Then we
attempt to read the file header, to make sure that it is really a Nexus Trace.
-If that check passes, we return a TmfValidationStatus with a confidence of 20.
+If that check passes, we return a TraceValidationStatus with a confidence of 20.
-Typically, TmfValidationStatus confidences should range from 1 to 100. 1 meaning
+Typically, TraceValidationStatus confidences should range from 1 to 100. 1 meaning
"there is a very small chance that this trace is of this type", and 100 meaning
"it is this type for sure, and cannot be anything else". At run-time, the
-auto-detection will pick the the type which returned the highest confidence. So
+auto-detection will pick the type which returned the highest confidence. So
checks of the type "does the file exist?" should not return a too high
-confidence.
+confidence. If confidence 0 is returned the auto-detection won't pick this type.
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 implement the ''tmf.core.tracetype'' extension in their own plug-in.
+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.linuxtools.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.linuxtools.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.linuxtools.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.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.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.linuxtools.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.linuxtools.internal.lttng2.kernel.ui.viewers.events.Lttng2EventsTable
-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.
* Data requests (TmfEventRequest)
* SWTChart integration
-'''Note''': TMF 3.0.0 provides base implementations for generating SWTChart viewers and views. For more details please refer to chapter [[#TMF Built-in Views and Viewers]].
+'''Note''': Trace Compass 0.1.0 provides base implementations for generating SWTChart viewers and views. For more details please refer to chapter [[#TMF Built-in Views and Viewers]].
=== Prerequisites ===
-The tutorial is based on Eclipse 4.4 (Eclipse Luna), TMF 3.0.0 and SWTChart 0.7.0. If you are using TMF from the source repository, SWTChart is already included in the target definition file (see org.eclipse.linuxtools.lttng.target). You can also install it manually by using the Orbit update site. http://download.eclipse.org/tools/orbit/downloads/
+The tutorial is based on Eclipse 4.4 (Eclipse Luna), Trace Compass 0.1.0 and SWTChart 0.7.0. If you are using TMF from the source repository, SWTChart is already included in the target definition file (see org.eclipse.tracecompass.target). You can also install it manually by using the Orbit update site. http://download.eclipse.org/tools/orbit/downloads/
=== Creating an Eclipse UI Plug-in ===
-To create a new project with name org.eclipse.linuxtools.tmf.sample.ui select '''File -> New -> Project -> Plug-in Development -> Plug-in Project'''. <br>
+To create a new project with name org.eclipse.tracecompass.tmf.sample.ui select '''File -> New -> Project -> Plug-in Development -> Plug-in Project'''. <br>
[[Image:images/Screenshot-NewPlug-inProject1.png]]<br>
[[Image:images/Screenshot-NewPlug-inProject2.png]]<br>
To open the plug-in manifest, double-click on the MANIFEST.MF file. <br>
[[Image:images/SelectManifest.png]]<br>
-Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.linuxtools.tmf.core'' and press '''OK'''<br>
-Following the same steps, add ''org.eclipse.linuxtools.tmf.ui'' and ''org.swtchart''.<br>
+Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.tracecompass.tmf.core'' and press '''OK'''<br>
+Following the same steps, add ''org.eclipse.tracecompass.tmf.ui'' and ''org.swtchart''.<br>
[[Image:images/AddDependencyTmfUi.png]]<br>
Change to the Extensions tab and select '''Add...''' of the ''All Extension'' section. A new dialog box will open. Find the view extension ''org.eclipse.ui.views'' and press '''Finish'''.<br>
This will generate an empty class. Once the quick fixes are applied, the following code is obtained:
<pre>
-package org.eclipse.linuxtools.tmf.sample.ui;
+package org.eclipse.tracecompass.tmf.sample.ui;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.ui.part.ViewPart;
private static final String Y_AXIS_TITLE = "Signal";
private static final String X_AXIS_TITLE = "Time";
private static final String FIELD = "value"; // The name of the field that we want to display on the Y axis
- private static final String VIEW_ID = "org.eclipse.linuxtools.tmf.sample.ui.view";
+ private static final String VIEW_ID = "org.eclipse.tracecompass.tmf.sample.ui.view";
private Chart chart;
private ITmfTrace currentTrace;
== TMF Built-in Views and Viewers ==
-TMF provides base implementations for several types of views and viewers for generating custom X-Y-Charts, Time Graphs, or Trees. They are well integrated with various TMF features such as reading traces and time synchronization with other views. They also handle mouse events for navigating the trace and view, zooming or presenting detailed information at mouse position. The code can be found in the TMF UI plug-in ''org.eclipse.linuxtools.tmf.ui''. See below for a list of relevant java packages:
+TMF provides base implementations for several types of views and viewers for generating custom X-Y-Charts, Time Graphs, or Trees. They are well integrated with various TMF features such as reading traces and time synchronization with other views. They also handle mouse events for navigating the trace and view, zooming or presenting detailed information at mouse position. The code can be found in the TMF UI plug-in ''org.eclipse.tracecompass.tmf.ui''. See below for a list of relevant java packages:
* Generic
-** ''org.eclipse.linuxtools.tmf.ui.views'': Common TMF view base classes
+** ''org.eclipse.tracecompass.tmf.ui.views'': Common TMF view base classes
* X-Y-Chart
-** ''org.eclipse.linuxtools.tmf.ui.viewers.xycharts'': Common base classes for X-Y-Chart viewers based on SWTChart
-** ''org.eclipse.linuxtools.tmf.ui.viewers.xycharts.barcharts'': Base classes for bar charts
-** ''org.eclipse.linuxtools.tmf.ui.viewers.xycharts.linecharts'': Base classes for line charts
+** ''org.eclipse.tracecompass.tmf.ui.viewers.xycharts'': Common base classes for X-Y-Chart viewers based on SWTChart
+** ''org.eclipse.tracecompass.tmf.ui.viewers.xycharts.barcharts'': Base classes for bar charts
+** ''org.eclipse.tracecompass.tmf.ui.viewers.xycharts.linecharts'': Base classes for line charts
* Time Graph View
-** ''org.eclipse.linuxtools.tmf.ui.widgets.timegraph'': Base classes for time graphs e.g. Gantt-charts
+** ''org.eclipse.tracecompass.tmf.ui.widgets.timegraph'': Base classes for time graphs e.g. Gantt-charts
* Tree Viewer
-** ''org.eclipse.linuxtools.tmf.ui.viewers.tree'': Base classes for TMF specific tree viewers
+** ''org.eclipse.tracecompass.tmf.ui.viewers.tree'': Base classes for TMF specific tree viewers
Several features in TMF and the Eclipse LTTng integration are using this framework and can be used as example for further developments:
* X-Y- Chart
-** ''org.eclipse.linuxtools.internal.lttng2.ust.ui.views.memusage.MemUsageView.java''
-** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.cpuusage.CpuUsageView.java''
-** ''org.eclipse.linuxtools.tracing.examples.ui.views.histogram.NewHistogramView.java''
+** ''org.eclipse.tracecompass.internal.lttng2.ust.ui.views.memusage.MemUsageView.java''
+** ''org.eclipse.tracecompass.analysis.os.linux.ui.views.cpuusage.CpuUsageView.java''
+** ''org.eclipse.tracecompass.tracing.examples.ui.views.histogram.NewHistogramView.java''
* Time Graph View
-** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.controlflow.ControlFlowView.java''
-** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.resources.ResourcesView.java''
+** ''org.eclipse.tracecompass.analysis.os.linux.ui.views.controlflow.ControlFlowView.java''
+** ''org.eclipse.tracecompass.analysis.os.linux.ui.views.resources.ResourcesView.java''
* Tree Viewer
-** ''org.eclipse.linuxtools.tmf.ui.views.statesystem.TmfStateSystemExplorer.java''
-** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.cpuusage.CpuUsageComposite.java''
+** ''org.eclipse.tracecompass.tmf.ui.views.statesystem.TmfStateSystemExplorer.java''
+** ''org.eclipse.tracecompass.analysis.os.linux.ui.views.cpuusage.CpuUsageComposite.java''
+
+== Timing Analysis Views and Viewers ==
+
+Trace Compass provides base implementations for timing views and viewers for generating Latency Tables, Scatter Charts, Density Graphs and Statistics Tables. They are well integrated with various Trace Compass features such as reading traces and time synchronization with other views. They also handle mouse events for navigating the trace and view, zooming or presenting detailed information at mouse position. The code can be found in the Analysis Timing plug-in ''org.eclipse.tracecompass.analysis.timing.ui''. See below for a list of relevant java packages:
+
+* Latency Table
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.table'': Base classes for Latency Tables
+* Scatter Chart
+** ''org.eclipse.tracecompass.tmf.ui.views.tmfChartView.java'': Common base classes for X-Y-Chart viewers based on SWTChart
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.scatter'': Base classes for Scatter Charts
+* Density Graph
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.density'': Base classes for Density Graphs
+* Statistics Table
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.statistics'': Base classes for Statistics Tables
+
+Several features in Trace Compass are using this framework and can be used as example for further development:
+
+* Latency Table
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternLatencyTableView.java''
+* Scatter Chart
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyScatterView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternScatterGraphView.java''
+* Density Graph
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyDensityView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternDensityView.java''
+
+* Statistics Table
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.statistics.SystemCallLatencyStatisticsView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternStatisticsView.java''
= Component Interaction =
Received by components that need to be notified of a new trace event count.
-=== TmfTimeSynchSignal ===
+=== TmfSelectionRangeUpdatedSignal ===
''Purpose''
Received by any component that needs to be notified of the currently selected time or time range.
-=== TmfRangeSynchSignal ===
+=== TmfWindowRangeUpdatedSignal ===
''Purpose''
Received by views that analyze packet streams.
+=== TmfStartAnalysisSignal ===
+
+''Purpose''
+
+This signal is used to indicate that an analysis has started.
+
+''Senders''
+
+Sent by an analysis module when it starts to execute the analyis.
+
+''Receivers''
+
+Received by components that need to be notified of the start of an analysis
+or that need to receive the analysis module.
+
+=== TmfCpuSelectedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that the user has selected a CPU core.
+
+''Senders''
+
+Sent by any component that allows the user to select a CPU.
+
+''Receivers''
+
+Received by viewers that show information specific to a selected CPU.
+
+=== TmfThreadSelectedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that the user has selected a thread.
+
+''Senders''
+
+Sent by any component that allows the user to select a thread.
+
+''Receivers''
+
+Received by viewers that show information specific to a selected thread.
+
+=== TmfTraceSynchronizedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that trace synchronization has been completed.
+
+''Senders''
+
+Sent by the experiment after trace synchronization.
+
+''Receivers''
+
+Received by any component that needs to be notified of trace synchronization.
+
+=== TmfMarkerEventSourceUpdatedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that a marker event source has been updated.
+
+''Senders''
+
+Sent by a component that has triggered a change in a marker event source.
+
+''Receivers''
+
+Received by any component that needs to refresh the markers due to the change in marker event source.
+
== Debugging ==
-TMF has built-in Eclipse tracing support for the debugging of signal interaction between components. To enable it, open the '''Run/Debug Configuration...''' dialog, select a configuration, click the '''Tracing''' tab, select the plug-in '''org.eclipse.linuxtools.tmf.core''', and check the '''signal''' item.
+TMF has built-in Eclipse tracing support for the debugging of signal interaction between components. To enable it, open the '''Run/Debug Configuration...''' dialog, select a configuration, click the '''Tracing''' tab, select the plug-in '''org.eclipse.tracecompass.tmf.core''', and check the '''signal''' item.
All signals sent and received will be logged to the file TmfTrace.log located in the Eclipse home directory.
the same time. We are then able to refer to every single attribute with its
path in the tree.
-For example, in the attribute tree for LTTng kernel traces, we use the following
+For example, in the attribute tree for Linux kernel traces, we use the following
attributes, among others:
<pre>
the state system. The exact implementation (how the intervals are stored) is
determined by the storage backend that is used.
-Some backends will use a state history that is peristent on disk, others do not.
+Some backends will use a state history that is persistent on disk, others do not.
When loading a trace, if a history file is available and the backend supports
it, it will be loaded right away, skipping the need to go through another
construction phase.
This section will describe the public interface and classes that can be used if
you want to use the state system.
-=== Main classes in org.eclipse.linuxtools.tmf.core.statesystem ===
+=== Main classes in org.eclipse.tracecompass.tmf.core.statesystem ===
==== ITmfStateProvider / AbstractTmfStateProvider ====
getQuarkAbsolute() takes a variable amount of Strings in parameter, which
represent the full path to the attribute. Some of them can be constants, some
-can come programatically, often from the event's fields.
+can come programmatically, often from the event's fields.
getQuarkRelative() is to be used when you already know the quark of a certain
attribute, and want to access on of its sub-attributes. Its first parameter is
they will have been written by the same person. In other cases, it's possible to
use getSubAttributes() to explore the organization of the attribute tree first.
+===== optQuarkAbsolute()/optQuarkRelative() =====
+
+These two methods are similar to their counterparts getQuarkAbsolute() and
+getQuarkRelative(). The only difference is that if the referenced attribute does
+not exist, the value ITmfStateSystem#INVALID_ATTRIBUTE (-2) is returned instead
+of throwing an exception.
+
+These methods should be used when the presence of the referenced attribute is
+known to be optional, to avoid the performance cost of generating exceptions.
+
+===== getQuarks() =====
+
+This method (with or without a starting node quark) takes an attribute path
+array which may contain wildcard "*" or parent ".." elements, and returns the
+list of matching attribute quarks. If no matching attribute is found, an empty
+list is returned.
+
===== waitUntilBuilt() =====
This is a simple method used to block the caller until the construction phase of
When the construction phase is done, do not forget to call closeHistory() to
tell the backend that no more intervals will be received. Depending on the
backend type, it might have to save files, close descriptors, etc. This ensures
-that a persitent file can then be re-used when the trace is opened again.
+that a persistent file can then be re-used when the trace is opened again.
If you use the AbstractTmfStateProvider, it will call closeHistory()
automatically when it reaches the end of the trace.
=== Other relevant interfaces ===
-==== o.e.l.tmf.core.statevalue.ITmfStateValue ====
+==== ITmfStateValue ====
This is the interface used to represent state values. Those are used when
inserting state changes in the provider, and is also part of the state intervals
Note: Do not instantiate null values manually, use TmfStateValue.nullValue()
-==== o.e.l.tmf.core.interval.ITmfStateInterval ====
+==== ITmfStateInterval ====
This is the interface to represent the state intervals, which are stored in the
state history backend, and are returned when doing state system queries. A very
=== Exceptions ===
-The following exceptions, found in o.e.l.tmf.core.exceptions, are related to
+The following exceptions, found in o.e.t.statesystem.core.exceptions, are related to
state system activities.
==== AttributeNotFoundException ====
-This is thrown by getQuarkRelative() and getQuarkAbsolute() (but not byt the
+This is thrown by getQuarkRelative() and getQuarkAbsolute() (but not by the
-AndAdd versions!) when passing an attribute path that is not present in the
state system. This is to ensure that no new attribute is created when using
these versions of the methods.
of saving the strings that would get repeated every time. This will help in
reducing the size of the history file.
-First we will define a state provider in MyStateProvider. Then, assuming we
-have already implemented a custom trace type extending CtfTmfTrace, we will add
-a section to it to make it build a state system using the provider we defined
-earlier. Finally, we will show some example code that can query the state
-system, which would normally go in a view or analysis module.
+First we will define a state provider in MyStateProvider. Then, we define an
+analysis module that takes care of creating the state provider. The analysis
+module will also contain code that can query the state system.
=== State Provider ===
<pre>
-import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfEvent;
-import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
-import org.eclipse.linuxtools.tmf.core.exceptions.AttributeNotFoundException;
-import org.eclipse.linuxtools.tmf.core.exceptions.StateValueTypeException;
-import org.eclipse.linuxtools.tmf.core.exceptions.TimeRangeException;
-import org.eclipse.linuxtools.tmf.core.statesystem.AbstractTmfStateProvider;
-import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
-import org.eclipse.linuxtools.tmf.core.statevalue.TmfStateValue;
-import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace;
+import static org.eclipse.tracecompass.common.core.NonNullUtils.checkNotNull;
+import org.eclipse.jdt.annotation.NonNull;
+import org.eclipse.tracecompass.statesystem.core.exceptions.AttributeNotFoundException;
+import org.eclipse.tracecompass.statesystem.core.exceptions.StateValueTypeException;
+import org.eclipse.tracecompass.statesystem.core.exceptions.TimeRangeException;
+import org.eclipse.tracecompass.statesystem.core.statevalue.ITmfStateValue;
+import org.eclipse.tracecompass.statesystem.core.statevalue.TmfStateValue;
+import org.eclipse.tracecompass.tmf.core.event.ITmfEvent;
+import org.eclipse.tracecompass.tmf.core.statesystem.AbstractTmfStateProvider;
+import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
+import org.eclipse.tracecompass.tmf.ctf.core.event.CtfTmfEvent;
/**
* Example state system provider.
* @param trace
* The trace to which this state provider is associated
*/
- public MyStateProvider(ITmfTrace trace) {
- super(trace, CtfTmfEvent.class, "Example"); //$NON-NLS-1$
+ public MyStateProvider(@NonNull ITmfTrace trace) {
+ super(trace, "Example"); //$NON-NLS-1$
/*
- * The third parameter here is not important, it's only used to name a
+ * The second parameter here is not important, it's only used to name a
* thread internally.
*/
}
try {
- if (event.getEventName().equals("sched_switch")) {
+ if (event.getType().getName().equals("sched_switch")) {
+ ITmfStateSystemBuilder ss = checkNotNull(getStateSystemBuilder());
int quark = ss.getQuarkAbsoluteAndAdd("CPUs", String.valueOf(event.getCPU()), "Status");
ITmfStateValue value;
if (nextTid > 0) {
}
</pre>
-=== Trace type definition ===
+=== Analysis module definition ===
<pre>
-import java.io.File;
-
-import org.eclipse.core.resources.IProject;
-import org.eclipse.core.runtime.IStatus;
-import org.eclipse.core.runtime.Status;
-import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfTrace;
-import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
-import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateProvider;
-import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateSystem;
-import org.eclipse.linuxtools.tmf.core.statesystem.TmfStateSystemFactory;
-import org.eclipse.linuxtools.tmf.core.trace.TmfTraceManager;
-
-/**
- * Example of a custom trace type using a custom state provider.
- *
- * @author Alexandre Montplaisir
- */
-public class MyTraceType extends CtfTmfTrace {
-
- /** The file name of the history file */
- public final static String HISTORY_FILE_NAME = "mystatefile.ht";
+import static org.eclipse.tracecompass.common.core.NonNullUtils.checkNotNull;
- /** ID of the state system we will build */
- public static final String STATE_ID = "org.eclipse.linuxtools.lttng2.example";
-
- /**
- * Default constructor
- */
- public MyTraceType() {
- super();
- }
-
- @Override
- public IStatus validate(final IProject project, final String path) {
- /*
- * Add additional validation code here, and return a IStatus.ERROR if
- * validation fails.
- */
- return Status.OK_STATUS;
- }
-
- @Override
- protected void buildStateSystem() throws TmfTraceException {
- super.buildStateSystem();
-
- /* Build the custom state system for this trace */
- String directory = TmfTraceManager.getSupplementaryFileDir(this);
- final File htFile = new File(directory + HISTORY_FILE_NAME);
- final ITmfStateProvider htInput = new MyStateProvider(this);
-
- ITmfStateSystem ss = TmfStateSystemFactory.newFullHistory(htFile, htInput, false);
- fStateSystems.put(STATE_ID, ss);
- }
-
-}
-</pre>
-
-=== Query code ===
-
-<pre>
import java.util.List;
-import org.eclipse.linuxtools.tmf.core.exceptions.AttributeNotFoundException;
-import org.eclipse.linuxtools.tmf.core.exceptions.StateSystemDisposedException;
-import org.eclipse.linuxtools.tmf.core.exceptions.TimeRangeException;
-import org.eclipse.linuxtools.tmf.core.interval.ITmfStateInterval;
-import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateSystem;
-import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
-import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace;
+import org.eclipse.tracecompass.statesystem.core.exceptions.AttributeNotFoundException;
+import org.eclipse.tracecompass.statesystem.core.exceptions.StateSystemDisposedException;
+import org.eclipse.tracecompass.statesystem.core.exceptions.TimeRangeException;
+import org.eclipse.tracecompass.statesystem.core.interval.ITmfStateInterval;
+import org.eclipse.tracecompass.statesystem.core.statevalue.ITmfStateValue;
+import org.eclipse.tracecompass.tmf.core.statesystem.ITmfStateProvider;
+import org.eclipse.tracecompass.tmf.core.statesystem.TmfStateSystemAnalysisModule;
+import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
/**
- * Class showing examples of state system queries.
+ * Class showing examples of a StateSystemAnalysisModule with state system queries.
*
* @author Alexandre Montplaisir
*/
-public class QueryExample {
+public class MyStateSystemAnalysisModule extends TmfStateSystemAnalysisModule {
- private final ITmfStateSystem ss;
+ @Override
+ protected ITmfStateProvider createStateProvider() {
+ ITmfTrace trace = checkNotNull(getTrace());
+ return new MyStateProvider(trace);
+ }
- /**
- * Constructor
- *
- * @param trace
- * Trace that this "view" will display.
- */
- public QueryExample(ITmfTrace trace) {
- ss = trace.getStateSystems().get(MyTraceType.STATE_ID);
+ @Override
+ protected StateSystemBackendType getBackendType() {
+ return StateSystemBackendType.FULL;
}
/**
*/
public boolean cpuIsRunning(int cpu, long timestamp) {
try {
- int quark = ss.getQuarkAbsolute("CPUs", String.valueOf(cpu), "Status");
- ITmfStateValue value = ss.querySingleState(timestamp, quark).getStateValue();
+ int quark = getStateSystem().getQuarkAbsolute("CPUs", String.valueOf(cpu), "Status");
+ ITmfStateValue value = getStateSystem().querySingleState(timestamp, quark).getStateValue();
if (value.equals(MyStateProvider.RUNNING)) {
return true;
* Handle the case where the attribute does not exist in the state
* system (no CPU with this number, etc.)
*/
- ...
} catch (TimeRangeException e) {
/*
* Handle the case where 'timestamp' is outside of the range of the
* history.
*/
- ...
} catch (StateSystemDisposedException e) {
/*
* Handle the case where the state system is being disposed. If this
try {
/* Get the list of the quarks we are interested in. */
- List<Integer> quarks = ss.getQuarks("CPUs", "*", "Status");
+ List<Integer> quarks = getStateSystem().getQuarks("CPUs", "*", "Status");
/*
* Get the full state at our target timestamp (it's better than
* doing an arbitrary number of single queries).
*/
- List<ITmfStateInterval> state = ss.queryFullState(timestamp);
+ List<ITmfStateInterval> state = getStateSystem().queryFullState(timestamp);
/* Look at the value of the state for each quark */
for (Integer quark : quarks) {
* Handle the case where 'timestamp' is outside of the range of the
* history.
*/
- ...
} catch (StateSystemDisposedException e) {
/* Handle the case where the state system is being disposed. */
- ...
}
return count;
}
In the UML2 Sequence Diagram Framework an Eclipse extension point is defined so that other plug-ins can contribute code to create sequence diagram.
'''Identifier''': org.eclipse.linuxtools.tmf.ui.uml2SDLoader<br>
-'''Since''': 1.0<br>
'''Description''': This extension point aims to list and connect any UML2 Sequence Diagram loader.<br>
'''Configuration Markup''':<br>
*id - A unique identifier for this uml2SDLoader. This is not mandatory as long as the id attribute cannot be retrieved by the provider plug-in. The class attribute is the one on which the underlying algorithm relies.
*name - An name of the extension instance.
-*class - The implementation of this UML2 SD viewer loader. The class must implement org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader.
-*view - The view ID of the view that this loader aims to populate. Either org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView itself or a extension of org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView.
+*class - The implementation of this UML2 SD viewer loader. The class must implement org.eclipse.tracecompass.tmf.ui.views.uml2sd.load.IUml2SDLoader.
+*view - The view ID of the view that this loader aims to populate. Either org.eclipse.tracecompass.tmf.ui.views.uml2sd.SDView itself or a extension of org.eclipse.tracecompass.tmf.ui.views.uml2sd.SDView.
*default - Set to true to make this loader the default one for the view; in case of several default loaders, first one coming from extensions list is taken.
== Sequence Diagram View ==
-For this extension point a Sequence Diagram View has to be defined as well. The Sequence Diagram View class implementation is provided by the plug-in ''org.eclipse.linuxtools.tmf.ui'' (''org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView'') and can be used as is or can also be sub-classed. For that, a view extension has to be added to the ''plugin.xml''.
+For this extension point a Sequence Diagram View has to be defined as well. The Sequence Diagram View class implementation is provided by the plug-in ''org.eclipse.tracecompass.tmf.ui'' (''org.eclipse.tracecompass.tmf.ui.views.uml2sd.SDView'') and can be used as is or can also be sub-classed. For that, a view extension has to be added to the ''plugin.xml''.
=== Supported Widgets ===
=== Creating an Eclipse UI Plug-in ===
-To create a new project with name org.eclipse.linuxtools.tmf.sample.ui select '''File -> New -> Project -> Plug-in Development -> Plug-in Project'''. <br>
+To create a new project with name org.eclipse.tracecompass.tmf.sample.ui select '''File -> New -> Project -> Plug-in Development -> Plug-in Project'''. <br>
[[Image:images/Screenshot-NewPlug-inProject1.png]]<br>
[[Image:images/Screenshot-NewPlug-inProject2.png]]<br>
To open the plug-in manifest, double-click on the MANIFEST.MF file. <br>
[[Image:images/SelectManifest.png]]<br>
-Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-ins ''org.eclipse.linuxtools.tmf.ui'' and ''org.eclipse.linuxtools.tmf.core'' and then press '''OK'''<br>
+Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-ins ''org.eclipse.tracecompass.tmf.ui'' and ''org.eclipse.tracecompass.tmf.core'' and then press '''OK'''<br>
[[Image:images/AddDependencyTmfUi.png]]<br>
Change to the Extensions tab and select '''Add...''' of the ''All Extension'' section. A new dialog box will open. Find the view extension ''org.eclipse.ui.views'' and press '''Finish'''.<br>
To create a Sequence Diagram View, click the right mouse button. Then select '''New -> view'''<br>
[[Image:images/AddViewExtension2.png]]<br>
-A new view entry has been created. Fill in the fields ''id'', ''name'' and ''class''. Note that for ''class'' the SD view implementation (''org.eclipse.linuxtools.tmf.ui.views.SDView'') of the TMF UI plug-in is used.<br>
+A new view entry has been created. Fill in the fields ''id'', ''name'' and ''class''. Note that for ''class'' the SD view implementation (''org.eclipse.tracecompass.tmf.ui.views.SDView'') of the TMF UI plug-in is used.<br>
[[Image:images/FillSampleSeqDiagram.png]]<br>
The view is prepared. Run the Example. To launch the an Eclipse Application select the ''Overview'' tab and click on '''Launch an Eclipse Application'''<br>
After defining the Sequence Diagram View it's time to create the ''uml2SDLoader'' Extension. <br>
-Before doing that add a dependency to TMF. For that select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.linuxtools.tmf'' and press '''OK'''<br>
-[[Image:images/AddDependencyTmf.png]]<br>
-
To create the loader extension, change to the Extensions tab and select '''Add...''' of the ''All Extension'' section. A new dialog box will open. Find the extension ''org.eclipse.linuxtools.tmf.ui.uml2SDLoader'' and press '''Finish'''.<br>
[[Image:images/AddTmfUml2SDLoader.png]]<br>
Then click on ''class'' (see above) to open the new class dialog box. Fill in the relevant fields and select '''Finish'''. <br>
[[Image:images/NewSampleLoaderClass.png]]<br>
-A new Java class will be created which implements the interface ''org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader''.<br>
+A new Java class will be created which implements the interface ''org.eclipse.tracecompass.tmf.ui.views.uml2sd.load.IUml2SDLoader''.<br>
<pre>
-package org.eclipse.linuxtools.tmf.sample.ui;
+package org.eclipse.tracecompass.tmf.sample.ui;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader;
+import org.eclipse.tracecompass.tmf.ui.views.uml2sd.SDView;
+import org.eclipse.tracecompass.tmf.ui.views.uml2sd.load.IUml2SDLoader;
public class SampleLoader implements IUml2SDLoader {
Next is to implement the methods of the IUml2SDLoader interface method. The following code snippet shows how to create the major sequence diagram elements. Please note that no time information is stored.<br>
<pre>
-package org.eclipse.linuxtools.tmf.sample.ui;
-
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.AsyncMessage;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.AsyncMessageReturn;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.ExecutionOccurrence;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.Frame;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.Lifeline;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.Stop;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.SyncMessage;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.SyncMessageReturn;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader;
+package org.eclipse.tracecompass.tmf.sample.ui;
+
+import org.eclipse.tracecompass.tmf.ui.views.uml2sd.SDView;
+import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.AsyncMessage;
+import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.AsyncMessageReturn;
+import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.EllipsisMessage;
+import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.ExecutionOccurrence;
+import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.Frame;
+import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.Lifeline;
+import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.Stop;
+import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.SyncMessage;
+import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.SyncMessageReturn;
+import org.eclipse.tracecompass.tmf.ui.views.uml2sd.load.IUml2SDLoader;
public class SampleLoader implements IUml2SDLoader {
=== Adding time information ===
-To add time information in sequence diagram the timestamp has to be set for each message. The sequence diagram framework uses the ''TmfTimestamp'' class of plug-in ''org.eclipse.linuxtools.tmf.core''. Use ''setTime()'' on each message ''SyncMessage'' since start and end time are the same. For each ''AsyncMessage'' set start and end time separately by using methods ''setStartTime'' and ''setEndTime''. For example: <br>
+To add time information in sequence diagram the timestamp has to be set for each message. The sequence diagram framework uses the ''TmfTimestamp'' class of plug-in ''org.eclipse.tracecompass.tmf.core''. Use ''setTime()'' on each message ''SyncMessage'' since start and end time are the same. For each ''AsyncMessage'' set start and end time separately by using methods ''setStartTime'' and ''setEndTime''. For example: <br>
<pre>
private void createFrame() {
//...
- start.setTime(new TmfTimestamp(1000, -3));
- syn1.setTime(new TmfTimestamp(1005, -3));
- synReturn1.setTime(new TmfTimestamp(1050, -3));
- asyn1.setStartTime(new TmfTimestamp(1060, -3));
- asyn1.setEndTime(new TmfTimestamp(1070, -3));
- asynReturn1.setStartTime(new TmfTimestamp(1060, -3));
- asynReturn1.setEndTime(new TmfTimestamp(1070, -3));
+ start.setTime(TmfTimestamp.create(1000, -3));
+ syn1.setTime(TmfTimestamp.create(1005, -3));
+ synReturn1.setTime(TmfTimestamp.create(1050, -3));
+ asyn1.setStartTime(TmfTimestamp.create(1060, -3));
+ asyn1.setEndTime(TmfTimestamp.create(1070, -3));
+ asynReturn1.setStartTime(TmfTimestamp.create(1060, -3));
+ asynReturn1.setEndTime(TmfTimestamp.create(1070, -3));
//...
}
</pre>
<pre>
public class SampleLoader implements IUml2SDLoader, ISDPagingProvider {
//...
- private page = 0;
+ private int page = 0;
@Override
public void dispose() {
}
@Override
- public boolean filter(List<?> list) {
+ public boolean filter(List<FilterCriteria> list) {
return false;
}
//...
try {
IWorkbenchPage persp = TmfUiPlugin.getDefault().getWorkbench().getActiveWorkbenchWindow().getActivePage();
SDView view = (SDView) persp.showView("org.eclipse.linuxtools.ust.examples.ui.componentinteraction");
- LoadersManager.getLoadersManager().createLoader("org.eclipse.linuxtools.tmf.ui.views.uml2sd.impl.TmfUml2SDSyncLoader", view);
+ LoadersManager.getLoadersManager().createLoader("org.eclipse.tracecompass.tmf.ui.views.uml2sd.impl.TmfUml2SDSyncLoader", view);
} catch (PartInitException e) {
throw new ExecutionException("PartInitException caught: ", e);
}
=== Downloading the Tutorial ===
-Use the following link to download the source code of the tutorial [http://wiki.eclipse.org/images/e/e6/SamplePlugin.zip Plug-in of Tutorial].
+Use the following link to download the source code of the tutorial [https://wiki.eclipse.org/images/7/79/SamplePluginTC.zip Plug-in of Tutorial].
== Integration of Tracing and Monitoring Framework with Sequence Diagram Framework ==
The reference loader use the TMF Event Request Framework to request events from the experiment and its traces.
-When opening a traces (which is triggered by signal ''TmfExperimentSelected'') or when opening the Sequence Diagram View after a trace had been opened previously, a TMF background request is initiated to index the trace and to fill in the first page of the sequence diagram. The purpose of the indexing is to store time ranges for pages with 10000 messages per page. This allows quickly to move to certain pages in a trace without having to re-parse from the beginning. The request is called indexing request.
+When opening a trace (which is triggered by signal ''TmfTraceSelectedSignal'') or when opening the Sequence Diagram View after a trace had been opened previously, a TMF background request is initiated to index the trace and to fill in the first page of the sequence diagram. The purpose of the indexing is to store time ranges for pages with 10000 messages per page. This allows quickly to move to certain pages in a trace without having to re-parse from the beginning. The request is called indexing request.
When switching pages, the a TMF foreground event request is initiated to retrieve the corresponding events from the experiment. It uses the time range stored in the index for the respective page.
=== Trace Format ===
-The reference implementation in class ''TmfUml2SDSyncLoader'' in package ''org.eclipse.linuxtools.tmf.ui.views.uml2sd.impl'' analyzes events from type ''ITmfEvent'' and creates events type ''ITmfSyncSequenceDiagramEvent'' if the ''ITmfEvent'' contains all relevant information information. The parsing algorithm looks like as follows:
+The reference implementation in class ''TmfUml2SDSyncLoader'' in package ''org.eclipse.tracecompass.tmf.ui.views.uml2sd.impl'' analyzes events from type ''ITmfEvent'' and creates events type ''ITmfSyncSequenceDiagramEvent'' if the ''ITmfEvent'' contains all relevant information information. The parsing algorithm looks like as follows:
<pre>
/**
An example CTF (Common Trace Format) trace is provided that contains trace events with sequence diagram information. To download the reference trace, use the following link: [https://wiki.eclipse.org/images/3/35/ReferenceTrace.zip Reference Trace].
-Run an Eclipse application with TMF 3.0 or later installed. To open the Reference Sequence Diagram View, select '''Windows -> Show View -> Other... -> TMF -> Sequence Diagram''' <br>
+Run an Eclipse application with Trace Compass 0.1.0 or later installed. To open the Reference Sequence Diagram View, select '''Windows -> Show View -> Other... -> Tracing -> Sequence Diagram''' <br>
[[Image:images/ShowTmfSDView.png]]<br>
A blank Sequence Diagram View will open.
=== Extending the Reference Loader ===
-In some case it might be necessary to change the implementation of the analysis of each ''TmfEvent'' for the generation of ''Sequence Diagram Events''. For that just extend the class ''TmfUml2SDSyncLoader'' and overwrite the method ''protected ITmfSyncSequenceDiagramEvent getSequnceDiagramEvent(TmfEvent tmfEvent)'' with your own implementation.
+In some case it might be necessary to change the implementation of the analysis of each ''TmfEvent'' for the generation of ''Sequence Diagram Events''. For that just extend the class ''TmfUml2SDSyncLoader'' and overwrite the method ''protected ITmfSyncSequenceDiagramEvent getSequenceDiagramEvent(ITmfEvent tmfEvent)'' with your own implementation.
= CTF Parser =
* Event streams
=== Metadata ===
-The metadata is either raw text or packetized text. It is tsdl encoded. it contains a description of the type of data in the event streams. It can grow over time if new events are added to a trace but it will never overwrite what is already there.
+The metadata is either raw text or packetized text. It is TSDL encoded. it contains a description of the type of data in the event streams. It can grow over time if new events are added to a trace but it will never overwrite what is already there.
=== Event Streams ===
The event streams are a file per stream per cpu. These streams are binary and packet based. The streams store events and event information (ie lost events) The event data is stored in headers and field payloads.
* The metadata must be read to know how to read the events.
* the events must be read.
-The metadata is a written in a subset of the C language called TSDL. To read it, first it is depacketized (if it is not in plain text) then the raw text is parsed by an antlr grammer. The parsing is done in two phases. There is a lexer (CTFLexer.g) which separated the metatdata text into tokens. The tokens are then pattern matched using the parser (CTFParser.g) to form an AST. This AST is walked through using "IOStructGen.java" to populate streams and traces in trace parent object.
+The metadata is a written in a subset of the C language called TSDL. To read it, first it is depacketized (if it is not in plain text) then the raw text is parsed by an antlr grammar. The parsing is done in two phases. There is a lexer (CTFLexer.g) which separated the metatdata text into tokens. The tokens are then pattern matched using the parser (CTFParser.g) to form an AST. This AST is walked through using "IOStructGen.java" to populate streams and traces in trace parent object.
When the metadata is loaded and read, the trace object will be populated with 3 items:
* the event definitions available per stream: a definition is a description of the datatype.
* the event declarations available per stream: this will save declaration creation on a per event basis. They will all be created in advance, just not populated.
* the beginning of a packet index.
-Now all the trace readers for the event streams have everything they need to read a trace. They will each point to one file, and read the file from packet to packet. Everytime the trace reader changes packet, the index is updated with the new packet's information. The readers are in a priority queue and sorted by timestamp. This ensures that the events are read in a sequential order. They are also sorted by file name so that in the eventuality that two events occur at the same time, they stay in the same order.
+Now all the trace readers for the event streams have everything they need to read a trace. They will each point to one file, and read the file from packet to packet. Every time the trace reader changes packet, the index is updated with the new packet's information. The readers are in a priority queue and sorted by timestamp. This ensures that the events are read in a sequential order. They are also sorted by file name so that in the eventuality that two events occur at the same time, they stay in the same order.
== Seeking in a trace ==
-The reason for maintaining an index is to speed up seeks. In the case that a user wishes to seek to a certain timestamp, they just have to find the index entry that contains the timestamp, and go there to iterate in that packet until the proper event is found. this will reduce the searches time by an order of 8000 for a 256k paket size (kernel default).
+The reason for maintaining an index is to speed up seeks. In the case that a user wishes to seek to a certain timestamp, they just have to find the index entry that contains the timestamp, and go there to iterate in that packet until the proper event is found. this will reduce the searches time by an order of 8000 for a 256k packet size (kernel default).
== Interfacing to TMF ==
The trace can be read easily now but the data is still awkward to extract.
There are other helper files that format given events for views, they are simpler and the architecture does not depend on them.
=== Limitations ===
-For the moment live trace reading is not supported, there are no sources of traces to test on.
+For the moment live CTF trace reading is not supported.
= Event matching and trace synchronization =
== Event matching interfaces ==
-Here's a description of the major parts involved in event matching. These classes are all in the ''org.eclipse.linuxtools.tmf.core.event.matching'' package:
+Here's a description of the major parts involved in event matching. These classes are all in the ''org.eclipse.tracecompass.tmf.core.event.matching'' package:
* '''ITmfEventMatching''': Controls the event matching process
* '''ITmfMatchEventDefinition''': Describes how events are matched
=== ITmfEventMatching interface and derived classes ===
-This interface and its default abstract implementation '''TmfEventMatching''' control the event matching itself. Their only public method is ''matchEvents''. The class needs to manage how to setup the traces, and any initialization or finalization procedures.
-
-The abstract class generates an event request for each trace from which events are matched and waits for the request to complete before calling the one from another trace. The ''handleData'' method from the request calls the ''matchEvent'' method that needs to be implemented in children classes.
+This interface controls the event matching itself. Their only public method is ''matchEvents''. The implementing classes needs to manage how to setup the traces, and any initialization or finalization procedures.
-Class '''TmfNetworkEventMatching''' is a concrete implementation of this interface. It applies to all use cases where a ''in'' event can be matched with a ''out' event (''in'' and ''out'' can be the same event, with different data). It creates a '''TmfEventDependency''' between the source and destination events. The dependency is added to the processing unit.
+The is one concrete implementation of this interface: '''TmfEventMatching'''. It makes a request on the traces and match events where a ''cause'' event can be uniquely matched with a ''effect'' event. It creates a '''TmfEventDependency''' between the source and destination events. The dependency is added to the processing unit.
-To match events requiring other mechanisms (for instance, a series of events can be matched with another series of events), one would need to implement another class either extending '''TmfEventMatching''' or implementing '''ITmfEventMatching'''. It would most probably also require a new '''ITmfMatchEventDefinition''' implementation.
+To match events requiring other mechanisms (for instance, a series of events can be matched with another series of events), one would need to add another class either implementing '''ITmfEventMatching'''. It would most probably also require a new '''ITmfMatchEventDefinition''' implementation.
=== ITmfMatchEventDefinition interface and its derived classes ===
The '''canMatchTrace''' method will tell if a definition is compatible with a given trace.
-The '''getUniqueField''' method will return a list of field values that uniquely identify this event and can be used to find a previous event to match with.
+The '''getEventKey''' method will return a key for an event that uniquely identifies this event and will match the key from another event.
-Typically, there would be a match definition abstract class/interface per event matching type.
+The '''getDirection''' method indicates whether this event is a ''cause'' or ''effect'' event to be matched with one from the opposite direction.
-The interface '''ITmfNetworkMatchDefinition''' adds the ''getDirection'' method to indicate whether this event is a ''in'' or ''out'' event to be matched with one from the opposite direction.
+As examples, two concrete network match definitions have been implemented in the ''org.eclipse.tracecompass.internal.lttng2.kernel.core.event.matching'' package for two compatible methods of matching TCP packets (See the Trace Compass User Guide on ''trace synchronization'' for information on those matching methods). Each one tells which events need to be present in the metadata of a CTF trace for this matching method to be applicable. It also returns the field values from each event that will uniquely match 2 events together.
-As examples, two concrete network match definitions have been implemented in the ''org.eclipse.linuxtools.lttng2.kernel.core.event.matching'' package for two compatible methods of matching TCP packets (See the LTTng User Guide on ''trace synchronization'' for information on those matching methods). Each one tells which events need to be present in the metadata of a CTF trace for this matching method to be applicable. It also returns the field values from each event that will uniquely match 2 events together.
+Each '''IMatchEventDefinition''' needs to be registered to the '''TmfEventMatching''' class using the following code for example
+
+<pre>
+TmfEventMatching.registerMatchObject(new TcpEventMatching());
+</pre>
=== IMatchProcessingUnit interface and derived classes ===
-While matching events is an exercice in itself, it's what to do with the match that really makes this functionality interesting. This is the job of the '''IMatchProcessingUnit''' interface.
+While matching events is an exercise in itself, it's what to do with the match that really makes this functionality interesting. This is the job of the '''IMatchProcessingUnit''' interface.
'''TmfEventMatches''' provides a default implementation that only stores the matches to count them. When a new match is obtained, the ''addMatch'' is called with the match and the processing unit can do whatever needs to be done with it.
};
ITmfTrace[] traces = { getTrace() };
- tcpMatching = new TmfNetworkEventMatching(traces, matchProcessing);
+ tcpMatching = new TmfEventMatching(traces, matchProcessing);
tcpMatching.initMatching();
MyEventRequest request = new MyEventRequest(this, i);
}
</pre>
-=== Match network events from UST traces ===
+=== Match events from UST traces ===
Suppose a client-server application is instrumented using LTTng-UST. Traces are collected on the server and some clients on different machines. The traces can be synchronized using network event matching.
One would need to write an event match definition for those 2 events as follows:
<pre>
-public class MyAppUstEventMatching implements ITmfNetworkMatchDefinition {
+public class MyAppUstEventMatching implements ITmfMatchEventDefinition {
+
+ public class MyEventMatchingKey implements IEventMatchingKey {
+
+ private static final HashFunction HF = checkNotNull(Hashing.goodFastHash(32));
+ private final int fTo;
+ private final long fId;
+
+ public MyEventMatchingKey(int to, long id) {
+ fTo = to;
+ fId = id;
+ }
+
+ @Override
+ public int hashCode() {
+ return HF.newHasher()
+ .putInt(fTo)
+ .putLong(fId).hash().asInt();
+ }
+
+ @Override
+ public boolean equals(@Nullable Object o) {
+ if (o instanceof MyEventMatchingKey) {
+ MyEventMatchingKey key = (MyEventMatchingKey) o;
+ return (key.fTo == fTo &&
+ key.fId == fId);
+ }
+ return false;
+ }
+ }
+
@Override
public Direction getDirection(ITmfEvent event) {
String evname = event.getType().getName();
if (evname.equals("myapp:receive")) {
- return Direction.IN;
+ return Direction.EFFECT;
} else if (evname.equals("myapp:send")) {
- return Direction.OUT;
+ return Direction.CAUSE;
}
return null;
}
@Override
- public List<Object> getUniqueField(ITmfEvent event) {
- List<Object> keys = new ArrayList<Object>();
+ public IEventMatchingKey getEventKey(ITmfEvent event) {
+ IEventMatchingKey key;
if (evname.equals("myapp:receive")) {
- keys.add(event.getContent().getField("from").getValue());
- keys.add(event.getContent().getField("messageid").getValue());
+ key = new MyEventMatchingKey(event.getContent().getField("from").getValue(),
+ event.getContent().getField("messageid").getValue());
} else {
- keys.add(event.getContent().getField("sendto").getValue());
- keys.add(event.getContent().getField("messageid").getValue());
+ key = new MyEventMatchingKey(event.getContent().getField("sendto").getValue(),
+ event.getContent().getField("messageid").getValue());
}
- return keys;
+ return key;
}
@Override
public boolean canMatchTrace(ITmfTrace trace) {
- if (!(trace instanceof CtfTmfTrace)) {
+ Set<String> events = ImmutableSet.of("myapp:receive", "myapp:send");
+ if (!(trace instanceof ITmfTraceWithPreDefinedEvents)) {
return false;
}
- CtfTmfTrace ktrace = (CtfTmfTrace) trace;
- String[] events = { "myapp:receive", "myapp:send" };
- return ktrace.hasAtLeastOneOfEvents(events);
- }
+ ITmfTraceWithPreDefinedEvents ktrace = (ITmfTraceWithPreDefinedEvents) trace;
- @Override
- public MatchingType[] getApplicableMatchingTypes() {
- MatchingType[] types = { MatchingType.NETWORK };
- return types;
+ Set<String> traceEvents = TmfEventTypeCollectionHelper.getEventName(ktrace.getContainedEventTypes());
+ traceEvents.retainAll(events);
+ return !traceEvents.isEmpty();
}
}
</pre>
-Somewhere in code that will be executed at the start of the plugin (like in the Activator), the following code will have to be run:
+The following code will have to be run before the trace synchronization takes place, for example in the Activator of the plugin:
<pre>
TmfEventMatching.registerMatchObject(new MyAppUstEventMatching());
</pre>
-Now, only adding the traces in an experiment and clicking the '''Synchronize traces''' menu element would synchronize the traces using the new definition for event matching.
+Now, only adding the traces in an experiment and clicking the '''Synchronize traces''' menu item will synchronize the traces using the new definition for event matching.
== Trace synchronization ==
-Trace synchronization classes and interfaces are located in the ''org.eclipse.linuxtools.tmf.core.synchronization'' package.
+Trace synchronization classes and interfaces are located in the ''org.eclipse.tracecompass.tmf.core.synchronization'' package.
=== Synchronization algorithm ===
The following classes implement this interface:
-* '''TmfTimestampTransform''': default transform. It cannot be instantiated, it has a single static object TmfTimestampTransform.IDENTITY, which returns the original timestamp.
+* '''TmfTimestampTransform''': default transform. It cannot be instantiated, it has a single static object ''TmfTimestampTransform.IDENTITY'', which returns the original timestamp.
+* '''TmfConstantTransform''': simply applies an offset to the timestamp, so the formula would be: ''f(t) = t + c'' where ''c'' is the offset to apply.
* '''TmfTimestampTransformLinear''': transforms the timestamp using a linear formula: ''f(t) = at + b'', where ''a'' and ''b'' are computed by the synchronization algorithm.
+These classes are not accessible directly, to create any timestamp transform, one needs to use one of the methods from the '''TimestampTransformFactory''' utility class.
+
One could extend the interface for other timestamp transforms, for instance to have a transform where the formula would change over the course of the trace.
== Todo ==
Here's a list of features not yet implemented that would enhance trace synchronization and event matching:
* Ability to select a synchronization algorithm
-* Implement a better way to select the reference trace instead of arbitrarily taking the first in alphabetical order (for instance, the minimum spanning tree algorithm by Masoume Jabbarifar (article on the subject not published yet))
-* Ability to join traces from the same host so that even if one of the traces is not synchronized with the reference trace, it will take the same timestamp transform as the one on the same machine.
+* Implement the minimum spanning tree algorithm by Masoume Jabbarifar (article on the subject not published yet) to automatically select the best reference trace
* Instead of having the timestamp transforms per trace, have the timestamp transform as part of an experiment context, so that the trace's specific analysis, like the state system, are in the original trace, but are transformed only when needed for an experiment analysis.
* Add more views to display the synchronization information (only textual statistics are available for now)
=== Example ===
-This example shows how to add a simple analysis module for an LTTng kernel trace with two parameters.
+This example shows how to add a simple analysis module for an LTTng kernel trace with two parameters. It also specifies two mandatory events by overriding '''getAnalysisRequirements'''. The analysis requirements are further explained in the section [[#Providing requirements to analyses]].
<pre>
public class MyLttngKernelAnalysis extends TmfAbstractAnalysisModule {
public static final String PARAM2 = "myotherparam";
@Override
- public boolean canExecute(ITmfTrace trace) {
- /* This just makes sure the trace is an Lttng kernel trace, though
- usually that should have been done by specifying the trace type
- this analysis module applies to */
- if (!LttngKernelTrace.class.isAssignableFrom(trace.getClass())) {
- return false;
- }
+ public Iterable<TmfAnalysisRequirement> getAnalysisRequirements() {
+
+ // initialize the requirement: events
+ Set<@NonNull String> requiredEvents = ImmutableSet.of("sched_switch", "sched_wakeup");
+ TmfAbstractAnalysisRequirement eventsReq = new TmfAnalysisEventRequirement(requiredEvents, PriorityLevel.MANDATORY);
- /* Does the trace contain the appropriate events? */
- String[] events = { "sched_switch", "sched_wakeup" };
- return ((LttngKernelTrace) trace).hasAllEvents(events);
+ return ImmutableList.of(eventsReq);
}
@Override
default_value="3"
name="myotherparam">
<tracetype
- class="org.eclipse.linuxtools.lttng2.kernel.core.trace.LttngKernelTrace">
+ class="org.eclipse.tracecompass.lttng2.kernel.core.trace.LttngKernelTrace">
</tracetype>
</module>
</extension>
<extension
point="org.eclipse.linuxtools.tmf.core.analysis">
<output
- class="org.eclipse.linuxtools.tmf.ui.analysis.TmfAnalysisViewOutput"
+ class="org.eclipse.tracecompass.tmf.ui.analysis.TmfAnalysisViewOutput"
id="my.plugin.package.ui.views.myView">
<analysisId
id="my.lttng.kernel.analysis.id">
</analysisId>
</output>
<output
- class="org.eclipse.linuxtools.tmf.ui.analysis.TmfAnalysisViewOutput"
+ class="org.eclipse.tracecompass.tmf.ui.analysis.TmfAnalysisViewOutput"
id="my.plugin.package.ui.views.myMoreGenericView">
<analysisModuleClass
class="my.plugin.package.core.MyAnalysisModuleClass">
/*
* Constructor
*/
- public CriticalPathParameterProvider() {
+ public MyLttngKernelParameterProvider() {
super();
registerListener();
}
return null;
}
if (name.equals(MyLttngKernelAnalysis.PARAM1)) {
- return fCurrentEntry.getThreadId()
+ return fCurrentEntry.getThreadId();
}
return null;
}
=== Analysis requirement provider API ===
-A requirement defines the needs of an analysis. For example, an analysis could need an event named ''"sched_switch"'' in order to be properly executed. The requirements are represented by the class '''TmfAnalysisRequirement'''. Since '''IAnalysisModule''' extends the '''IAnalysisRequirementProvider''' interface, all analysis modules must provide their requirements. If the analysis module extends '''TmfAbstractAnalysisModule''', it has the choice between overriding the requirements getter ('''IAnalysisRequirementProvider#getAnalysisRequirements()''') or not, since the abstract class returns an empty collection by default (no requirements).
+A requirement defines the needs of an analysis. For example, an analysis could need an event named ''"sched_switch"'' in order to be properly executed. The requirements are represented by extending the class '''TmfAbstractAnalysisRequirement'''. Since '''IAnalysisModule''' extends the '''IAnalysisRequirementProvider''' interface, all analysis modules must provide their requirements. If the analysis module extends '''TmfAbstractAnalysisModule''', it has the choice between overriding the requirements getter ('''IAnalysisRequirementProvider#getAnalysisRequirements()''') or not, since the abstract class returns an empty collection by default (no requirements).
=== Requirement values ===
-When instantiating a requirement, the developer needs to specify a type to which all the values added to the requirement will be linked. In the earlier example, there would be an ''"event"'' or ''"eventName"'' type. The type is represented by a string, like all values added to the requirement object. With an 'event' type requirement, a trace generator like the LTTng Control could automatically enable the required events. This is possible by calling the '''TmfAnalysisRequirementHelper''' class. Another point we have to take into consideration is the priority level of each value added to the requirement object. The enum '''TmfAnalysisRequirement#ValuePriorityLevel''' gives the choice between '''ValuePriorityLevel#MANDATORY''' and '''ValuePriorityLevel#OPTIONAL'''. That way, we can tell if an analysis can run without a value or not. To add values, one must call '''TmfAnalysisRequirement#addValue()'''.
+Each concrete analysis requirement class will define how a requirement is verified on a given trace.
+When creating a requirement, the developer will specify a set of values for that class.
+With an 'event' type requirement, a trace generator like the LTTng Control could automatically
+enable the required events.
+Another point we have to take into consideration is the priority level when creating a requirement object.
+The enum '''TmfAbstractAnalysisRequirement#PriorityLevel''' gives the choice
+between '''PriorityLevel#OPTIONAL''', '''PriorityLevel#ALL_OR_NOTHING''',
+'''PriorityLevel#AT_LEAST_ONE''' or '''PriorityLevel#MANDATORY'''. That way, we
+can tell if an analysis can run without a value or not.
+
+
+To create a requirement one has the choice to extend the abstract class
+'''TmfAbstractAnalysisRequirement''' or use the existing implementations:
+'''TmfAnalysisEventRequirement''' (will verify the presence of events identified by name),
+'''TmfAnalysisEventFieldRequirement''' (will verify the presence of fields for some or all events) or
+'''TmfCompositeAnalysisRequirement''' (join requirements together with one of the priority levels).
Moreover, information can be added to requirements. That way, the developer can explicitly give help details at the requirement level instead of at the analysis level (which would just be a general help text). To add information to a requirement, the method '''TmfAnalysisRequirement#addInformation()''' must be called. Adding information is not mandatory.
=== Example of providing requirements ===
-In this example, we will implement a method that initializes a requirement object and return it in the '''IAnalysisRequirementProvider#getAnalysisRequirements()''' getter. The example method will return a set with two requirements. The first one will indicate the events needed by a specific analysis and the last one will tell on what domain type the analysis applies. In the event type requirement, we will indicate that the analysis needs a mandatory event and an optional one.
+In this example, we will implement a method that initializes a requirement object
+and return it in the '''IAnalysisRequirementProvider#getAnalysisRequirements()'''
+getter. The example method will return a set with three requirements.
+The first one will indicate a mandatory event needed by a specific analysis,
+the second one will tell an optional event name and the third will indicate
+mandatory event fields for the given event type.
+
+Note that in LTTng event contexts are considered as event fields. Using the
+'''TmfAnalysisEventFieldRequirement''' it's possible to define requirements
+on event contexts (see 3rd requirement in example below).
<pre>
-@Override
-public Iterable<TmfAnalysisRequirement> getAnalysisRequirements() {
- Set<TmfAnalysisRequirement> requirements = new HashSet<>();
+ @Override
+ public @NonNull Iterable<@NonNull TmfAbstractAnalysisRequirement> getAnalysisRequirements() {
- /* Create requirements of type 'event' and 'domain' */
- TmfAnalysisRequirement eventRequirement = new TmfAnalysisRequirement("event");
- TmfAnalysisRequirement domainRequirement = new TmfAnalysisRequirement("domain");
+ /* Requirement on event name */
+ Set<@NonNull String> requiredEvents = ImmutableSet.of("sched_wakeup");
+ TmfAbstractAnalysisRequirement eventsReq1 = new TmfAnalysisEventRequirement(requiredEvents, PriorityLevel.MANDATORY);
- /* Add the values */
- domainRequirement.addValue("kernel", TmfAnalysisRequirement.ValuePriorityLevel.MANDATORY);
- eventRequirement.addValue("sched_switch", TmfAnalysisRequirement.ValuePriorityLevel.MANDATORY);
- eventRequirement.addValue("sched_wakeup", TmfAnalysisRequirement.ValuePriorityLevel.OPTIONAL);
+ requiredEvents = ImmutableSet.of("sched_switch");
+ TmfAbstractAnalysisRequirement eventsReq2 = new TmfAnalysisEventRequirement(requiredEvents, PriorityLevel.OPTIONAL);
- /* An information about the events */
- eventRequirement.addInformation("The event sched_wakeup is optional because it's not properly handled by this analysis yet.");
+ /* An information about the events */
+ eventsReq2.addInformation("The event sched_wakeup is optional because it's not properly handled by this analysis yet.");
- /* Add them to the set */
- requirements.add(domainRequirement);
- requirements.add(eventRequirement);
+ /* Requirement on event fields */
+ Set<@NonNull String> requiredEventFields = ImmutableSet.of("context._procname", "context._ip");
+ TmfAbstractAnalysisRequirement eventFieldRequirement = new TmfAnalysisEventFieldRequirement(
+ "event name",
+ requiredEventFields,
+ PriorityLevel.MANDATORY);
- return requirements;
-}
+ Set<TmfAbstractAnalysisRequirement> requirements = ImmutableSet.of(eventsReq1, eventsReq2, eventFieldRequirement);
+ return requirements;
+ }
</pre>
* Add the possibility for an analysis requirement to be composed of another requirement.
* Generate a trace session from analysis requirements.
+= TMF Remote API =
+The TMF remote API is based on the remote services implementation of the Eclipse PTP project. It comes with a built-in SSH implementation based JSch as well as with support for a local connection. The purpose of this API is to provide a programming interface to the PTP remote services implementation for connection handling, command-line execution and file transfer handling. It provides utility functions to simplify repetitive tasks.
+
+The TMF Remote API can be used for remote trace control, fetching of traces from a remote host into the Eclipse Tracing project or uploading files to the remote host. For example, the LTTng tracer control feature uses the TMF remote API to control an LTTng host remotely and to download corresponding traces.
+
+In the following chapters the relevant classes and features of the TMF remote API is described.
+
+== Prerequisites ==
+
+To use the TMF remote API one has to add the relevant plug-in dependencies to a plug-in project. To create a plug-in project see chapter [[#Creating an Eclipse UI Plug-in]].
+
+To add plug-in dependencies double-click on the MANIFEST.MF file. Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.tracecompass.tmf.remote.core'' and press '''OK'''. Follow the same steps, add ''org.eclipse.remote.core''. If UI elements are needed in the plug-in also add ''org.eclipse.tracecompass.tmf.remote.ui'' and ''org.eclipse.remote.ui''.
+
+== TmfRemoteConnectionFactory ==
+This class is a utility class for creating ''IRemoteConnection'' instances of PTP programatically. It also provides access methods to the OSGI remote services of PTP.
+
+=== Accessing the remote services manager (OSGI service) ===
+The main entry point into the PTP remote services system is the ''IRemoteServicesManager'' OSGI service. It provides a list of connection types and the global list of all connections.
+
+To access an OSGI service, use the method '''getService()''' of the '''TmfRemoteConnectionFactory''' class:
+
+<pre>
+IRemoteServicesManager manager = TmfRemoteConnectionFactory.getService(IRemoteServicesManager.class);
+</pre>
+
+=== Obtaining a IRemoteConnection ===
+To obtain an '''IRemoteConnection''' instance use the method '''TmfRemoteConnectionFactory.getRemoteConnection(String remoteServicesId, String name)''', where ''remoteServicesId'' is the ID of service ID for the connection, and ''name'' the name of the connection. For built-in SSH the ''remoteServicesId'' is "org.eclipse.remote.JSch".
+
+<pre>
+IRemoteConnection connection = TmfRemoteConnectionFactory.getRemoteConnection("org.eclipse.remote.JSch", "My Connection");
+</pre>
+
+Note that the connection needs to be created beforehand using the Remote Connection wizard implementation ('''Window -> Preferences -> Remote Development -> Remote Connection''') in the Eclipse application that executes this plug-in. For more information about creating connections using the Remote Connections feature of PTP refer to [http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.ptp.doc.user%2Fhtml%2FremoteTools.html&anchor=remote link]. Alternatively it can be created programmatically using the corresponding API of TMF ([[#Creating an IRemoteConnection instance]]).
+
+To obtain an '''IRemoteConnection''' instance use method '''TmfRemoteConnectionFactory.getLocalConnection()'''.
+<pre>
+IRemoteConnection connection = TmfRemoteConnectionFactory.getLocalConnection();
+</pre>
+
+=== Creating an IRemoteConnection instance ===
+It is possible to create an '''IRemoteConnection''' instance programmatically using the '''TmfRemoteConnectionFactory'''. Right now only build-in SSH or Local connection is supported.
+
+To create an '''IRemoteConnection''' instance use the method '''createConnection(URI hostURI, String name)''' of class '''TmfRemoteConnectionFactory''', where ''hostURI'' is the URI of the remote connection, and ''name'' the name of the connection. For a built-in SSH use:
+<pre>
+import org.eclipse.remote.core.IRemoteConnection;
+...
+ try {
+ URI hostUri = URIUtil.fromString("ssh://userID@127.0.0.1:22");
+ IRemoteConnection connection = TmfRemoteConnectionFactory.createConnection(hostUri, "MyHost");
+ } catch (URISyntaxException e) {
+ return new Status(IStatus.ERROR, "my.plugin.id", "URI syntax error", e);
+ } catch (RemoteConnectionException e) {
+ return new Status(IStatus.ERROR, "my.plugin.id", "Connection cannot be created", e);
+ }
+...
+</pre>
+
+Note that if a connection already exists with the given name then this connection will be returned.
+
+=== Providing a connection factory ===
+Right now only build-in SSH or Local connection of PTP is supported. If one wants to provide another connection factory with a different remote service implementation use the interface '''IConnectionFactory''' to implement a new connection factory class. Then, register the new factory to '''TmfRemoteConnectionFactory''' using method '''registerConnectionFactory(String connectionTypeId, IConnectionFactory factory)''', where ''connectionTypeId'' is a unique ID and ''factory'' is the corresponding connection factory implementation.
+
+== RemoteSystemProxy ==
+The purpose of the RemoteSystemProxy is to handle the connection state of '''IRemoteConnection''' (connect/disconnect). Before opening a connection it checks if the connection had been open previously. If it was open, disconnecting the proxy will not close the connection. This is useful if multiple components using the same connection at the same time for different features (e.g. Tracer Control and remote fetching of traces) without impacting each other.
+
+=== Creating a RemoteSystemProxy ===
+Once one has an '''IRemoteConnection''' instance a '''RemoteSystemProxy''' can be constructed by:
+<pre>
+// Get local connection (for example)
+IRemoteConnection connection = TmfRemoteConnectionFactory.getLocalConnection();
+RemoteSystemProxy proxy = new RemoteSystemProxy(connection);
+</pre>
+
+=== Opening the remote connection ===
+To open the connection call method '''connect()''':
+<pre>
+ proxy.connect();
+</pre>
+
+This will open the connection. If the connection has been previously opened then it will immediately return.
+
+=== Closing the remote connection ===
+To close the connection call method '''disconnect()''':
+<pre>
+ proxy.disconnect();
+</pre>
+
+Note: This will close the connection if the connection was opened by this proxy. Otherwise it will stay open.
+
+=== Disposing the remote connection ===
+If a remote system proxy is not needed anymore the proxy instance needs to be disposed by calling method '''dispose()'''. This may close the connection if the connection was opened by this proxy. Otherwise it will stay open.
+
+<pre>
+ proxy.dispose();
+</pre>
+
+=== Checking the connection state ===
+
+To check the connection state use method '''isConnected()''' of the '''RemoteSystemProxy''' class.
+
+<pre>
+ if (proxy.isConnected()) {
+ // do something
+ }
+</pre>
+
+
+=== Retrieving the IRemoteConnection instance ===
+To retrieve the '''IRemoteConnection''' instance use the '''getRemoteConnection()''' method of the '''RemoteSystemProxy''' class. Using this instance relevant features of the remote connection implementation can be accessed, for example remote file service ('''IRemoteFileService''') or remote process service ('''IRemoteProcessService''').
+
+<pre>
+import org.eclipse.remote.core.IRemoteConnection;
+import org.eclipse.remote.core.IRemoteFileService;
+...
+ IRemoteRemoteConnection connection = proxy.getRemoteConnection();
+ IRemoteFileService fileService = connection.getService(IRemoteFileService.class);
+ if (fileService != null) {
+ // do something (e.g. download or upload a file)
+ }
+</pre>
+
+<pre>
+import org.eclipse.remote.core.IRemoteConnection;
+import org.eclipse.remote.core.IRemoteFileService;
+...
+ IRemoteRemoteConnection connection = proxy.getRemoteConnection();
+ IRemoteFileService processService = connection.getService(IRemoteProcessService.class);
+ if (processService != null) {
+ // do something (e.g. execute command)
+ }
+</pre>
+
+=== Obtaining a command shell ===
+The TMF remote API provides a Command shell implementation to execute remote command-line commands. To obtain a command-line shell use the RemoteSystemProxy.
+
+<pre>
+import org.eclipse.remote.core.IRemoteConnection;
+import org.eclipse.remote.core.IRemoteFileService;
+import org.eclipse.tracecompass.tmf.remote.core.shell.ICommandShell
+...
+ ICommandShell shell = proxy.createCommandShell();
+ ICommandInput command = fCommandShell.createCommand();
+ command.add("ls");
+ command.add("-l");
+ ICommandResult result = shell.executeCommand(command, new NullProgressMonitor);
+ System.out.println("Return value: " result.getResult());
+ for (String line : result.getOutput()) {
+ System.out.println(line);
+ }
+ for (String line : result.getErrorOutput()) {
+ System.err.println(line);
+ }
+ shell.dispose();
+</pre>
+
+Note that the shell needs to be disposed if not needed anymore.
+
+Note for creating a command with parameters using the '''CommandInput''' class, add the command and each parameter separately instead of using one single String.
= Performance Tests =
Tests are to be added to a package under the ''perf'' directory, the package name would typically match the name of the package it is testing. For each package, a class named '''AllPerfTests''' would list all the performance tests classes inside this package. And like for unit tests, a class named '''AllPerfTests''' for the plug-in would list all the packages' '''AllPerfTests''' classes.
-When adding performance tests for the first time in a plug-in, the plug-in's '''AllPerfTests''' class should be added to the global list of performance tests, found in package ''org.eclipse.linuxtools.lttng.alltests'', in class '''RunAllPerfTests'''. This will ensure that performance tests for the plug-in are run along with the other performance tests
+When adding performance tests for the first time in a plug-in, the plug-in's '''AllPerfTests''' class should be added to the global list of performance tests, found in package ''org.eclipse.tracecompass.alltests'', in class '''RunAllPerfTests'''. This will ensure that performance tests for the plug-in are run along with the other performance tests
=== How ===
for (int i = 0; i < LOOP_COUNT; i++) {
/** Start each run of the test with new objects to avoid different code paths */
- try (IAnalysisModule module = new LttngKernelAnalysisModule();
+ try (IAnalysisModule module = new KernelAnalysis();
LttngKernelTrace trace = new LttngKernelTrace()) {
module.setId("test");
trace.initTrace(null, testTrace.getPath(), CtfTmfEvent.class);
CPU time: CPU time represent the total time spent on CPU by the current process, for the time of the test execution. It is the sum of the time spent by all threads. On one hand, it is more significant than the elapsed time, since it should be the same no matter how many CPU cores the computer has. But since it calculates the time of every thread, one has to make sure that only threads related to what is being tested are executed during that time, or else the results will include the times of those other threads. For an application like TMF, it is hard to control all the threads, and empirically, it is found to vary a lot more than the system time from one run to the other.
-System time (Elapsed time): The time between the start and the end of the execution. It will vary depending on the parallelisation of the threads and the load of the machine.
+System time (Elapsed time): The time between the start and the end of the execution. It will vary depending on the parallelization of the threads and the load of the machine.
Kernel time: Time spent in kernel mode
=== Architecture ===
All the TMF pcap-related code is divided in three projects (not considering the tests plugins):
-* '''org.eclipse.linuxtools.pcap.core''', which contains the parser that will read pcap files and constructs the different packets from a ByteBuffer. It also contains means to build packet streams, which are conversation (list of packets) between two endpoints. To add a protocol, almost all of the work will be in that project.
-* '''org.eclipse.linuxtools.tmf.pcap.core''', which contains TMF-specific concepts and act as a wrapper between TMF and the pcap parsing library. It only depends on org.eclipse.linuxtools.tmf.core and org.eclipse.pcap.core. To add a protocol, one file must be edited in this project.
-* '''org.eclipse.linuxtools.tmf.pcap.ui''', which contains all TMF pcap UI-specific concepts, such as the views and perspectives. No work is needed in that project.
+* '''org.eclipse.tracecompass.pcap.core''', which contains the parser that will read pcap files and constructs the different packets from a ByteBuffer. It also contains means to build packet streams, which are conversation (list of packets) between two endpoints. To add a protocol, almost all of the work will be in that project.
+* '''org.eclipse.tracecompass.tmf.pcap.core''', which contains TMF-specific concepts and act as a wrapper between TMF and the pcap parsing library. It only depends on org.eclipse.tracecompass.tmf.core and org.eclipse.tracecompass.pcap.core. To add a protocol, one file must be edited in this project.
+* '''org.eclipse.tracecompass.tmf.pcap.ui''', which contains all TMF pcap UI-specific concepts, such as the views and perspectives. No work is needed in that project.
=== UDP Packet Structure ===
=== Creating the UDPPacket ===
-First, in org.eclipse.linuxtools.pcap.core, create a new package named '''org.eclipse.linuxtools.pcap.core.protocol.name''' with name being the name of the new protocol. In our case name is udp so we create the package '''org.eclipse.linuxtools.pcap.core.protocol.udp'''. All our work is going in this package.
+First, in org.eclipse.tracecompass.pcap.core, create a new package named '''org.eclipse.tracecompass.pcap.core.protocol.name''' with name being the name of the new protocol. In our case name is udp so we create the package '''org.eclipse.tracecompass.pcap.core.protocol.udp'''. All our work is going in this package.
In this package, we create a new class named UDPPacket that extends Packet. All new protocol must define a packet type that extends the abstract class Packet. We also add different fields:
* ''Packet'' '''fChildPacket''', which is the packet encapsulated by this UDP packet, if it exists. This field will be initialized by findChildPacket().
The following class is obtained:
<pre>
-package org.eclipse.linuxtools.pcap.core.protocol.udp;
+package org.eclipse.tracecompass.pcap.core.protocol.udp;
import java.nio.ByteBuffer;
import java.util.Map;
-import org.eclipse.linuxtools.internal.pcap.core.endpoint.ProtocolEndpoint;
-import org.eclipse.linuxtools.internal.pcap.core.packet.BadPacketException;
-import org.eclipse.linuxtools.internal.pcap.core.packet.Packet;
+import org.eclipse.tracecompass.internal.pcap.core.endpoint.ProtocolEndpoint;
+import org.eclipse.tracecompass.internal.pcap.core.packet.BadPacketException;
+import org.eclipse.tracecompass.internal.pcap.core.packet.Packet;
public class UDPPacket extends Packet {
* Thrown when the packet is erroneous.
*/
public UDPPacket(PcapFile file, @Nullable Packet parent, ByteBuffer packet) throws BadPacketException {
- super(file, parent, Protocol.UDP);
+ super(file, parent, PcapProtocol.UDP);
// TODO Auto-generated constructor stub
}
We obtain the following unimplemented class:
<pre>
-package org.eclipse.linuxtools.pcap.core.protocol.udp;
+package org.eclipse.tracecompass.pcap.core.protocol.udp;
-import org.eclipse.linuxtools.internal.pcap.core.endpoint.ProtocolEndpoint;
-import org.eclipse.linuxtools.internal.pcap.core.packet.Packet;
+import org.eclipse.tracecompass.internal.pcap.core.endpoint.ProtocolEndpoint;
+import org.eclipse.tracecompass.internal.pcap.core.packet.Packet;
public class UDPEndpoint extends ProtocolEndpoint {
=== Registering the UDP protocol ===
-The last step is to register the new protocol. There are three places where the protocol has to be registered. First, the parser has to know that a new protocol has been added. This is defined in the enum org.eclipse.linuxtools.pcap.core.protocol.PcapProtocol. Simply add the protocol name here, along with a few arguments:
+The last step is to register the new protocol. There are three places where the protocol has to be registered. First, the parser has to know that a new protocol has been added. This is defined in the enum org.eclipse.tracecompass.internal.pcap.core.protocol.PcapProtocol. Simply add the protocol name here, along with a few arguments:
* ''String'' '''longname''', which is the long version of name of the protocol. In our case, it is "User Datagram Protocol".
* ''String'' '''shortName''', which is the shortened name of the protocol. In our case, it is "UDP".
* ''Layer'' '''layer''', which is the layer to which the protocol belongs in the OSI model. In our case, this is the layer 4.
UDP("User Datagram Protocol", "udp", Layer.LAYER_4, true),
</pre>
-Also, TMF has to know about the new protocol. This is defined in org.eclipse.linuxtools.tmf.pcap.core.protocol.TmfPcapProtocol. We simply add it, with a reference to the corresponding protocol in PcapProtocol. Thus, the following line is added in the TmfPcapProtocol enum:
+Also, TMF has to know about the new protocol. This is defined in org.eclipse.tracecompass.internal.tmf.pcap.core.protocol.TmfPcapProtocol. We simply add it, with a reference to the corresponding protocol in PcapProtocol. Thus, the following line is added in the TmfPcapProtocol enum:
<pre>
UDP(PcapProtocol.UDP),
</pre>
* Make adding protocol more "plugin-ish", via extension points for instance. This would make it easier to support new protocols, without modifying the source code.
* Control dumpcap directly from eclipse, similar to how LTTng is controlled in the Control View.
* Support pcapng. See: http://www.winpcap.org/ntar/draft/PCAP-DumpFileFormat.html for the file format.
-* Add SWTBOT tests to org.eclipse.linuxtools.tmf.pcap.ui
+* Add SWTBOT tests to org.eclipse.tracecompass.tmf.pcap.ui
* Add a Raw Viewer, similar to Wireshark. We could use the “Show Raw” in the event editor to do that.
-* Externalize strings in org.eclipse.linuxtools.pcap.core. At the moment, all the strings are hardcoded. It would be good to externalize them all.
+* Externalize strings in org.eclipse.tracecompass.pcap.core. At the moment, all the strings are hardcoded. It would be good to externalize them all.
+
+= Markers =
+
+Markers are annotations that are defined with a time range, a color, a category and an optional label. The markers are displayed in the time graph of any view that extends ''AbstractTimeGraphView''. The markers are drawn as a line or a region (in case the time range duration is not zero) of the given color, which can have an alpha value to use transparency. The markers can be drawn in the foreground (above time graph states) or in the background (below time graph states). An optional label can be drawn in the the time scale area.
+
+The developer can add trace-specific markers and/or view-specific markers.
+
+== Trace-specific markers ==
+
+Trace-specific markers can be added by registering an ''IAdapterFactory'' with the TmfTraceAdapterManager. The adapter factory must provide adapters of the ''IMarkerEventSource'' class for a given ''ITmfTrace'' object. The adapter factory can be registered for traces of a certain class (which will include sub-classes of the given class) or it can be registered for traces of a certain trace type id (as defined in the ''org.eclipse.linuxtools.tmf.core.tracetype'' extension point).
+
+The adapter factory can be registered in the ''Activator'' of the plug-in that introduces it, in the ''start()'' method, and unregistered in the ''stop()'' method.
+
+It is recommended to extend the ''AbstractTmfTraceAdapterFactory'' class when creating the adapter factory. This will ensure that a single instance of the adapter is created for a specific trace and reused by all components that need the adapter, and that the adapter is disposed when the trace is closed.
+
+The adapter implementing the ''IMarkerEventSource'' interface must provide two methods:
+
+* ''getMarkerCategories()'' returns a list of category names which will be displayed to the user, who can then enable or disable markers on a per-category basis.
+
+* ''getMarkerList()'' returns a list of markers instances of class ''IMarkerEvent'' for the given category and time range. The resolution can be used to limit the number of markers returned for the current zoom level, and the progress monitor can be checked for early cancellation of the marker computation.
+
+The trace-specific markers for a particular trace will appear in all views extending ''AbstractTimeGraphView'' when that trace (or an experiment containing that trace) is selected.
+
+An example of a trace-specific markers implementation can be seen by examining classes ''LostEventsMarkerEventSourceFactory'', ''LostEventsMarkerEventSource'' and ''Activator'' in the ''org.eclipse.tracecompass.tmf.ui'' plug-in.
+
+== View-specific markers ==
+
+View-specific markers can by added in sub-classes of ''AbstractTimeGraphView'' by implementing the following two methods:
+
+* ''getViewMarkerCategories()'' returns a list of category names which will be displayed to the user, who can then enable or disable markers on a per-category basis.
+
+* ''getViewMarkerList()'' returns a list of markers instances of class ''IMarkerEvent'' for the given time range. The resolution can be used to limit the number of markers returned for the current zoom level, and the progress monitor can be checked for early cancellation of the marker computation.
+
+= Virtual Machine Analysis =
+
+Virtualized environment are becoming more popular and understanding them can be challenging as machines share resources (CPU, disks, memory, etc), but from their point of view, they are running on bare metal. Tracing all the machines (guests and hosts) in a virtualized environment allows information to be correlated between all the nodes to better understand the system. See the User documentation for more info on this analysis.
+
+The virtual machine analysis has been implemented in the following plugins:
+
+* '''org.eclipse.tracecompass.lttng2.kernel.core''' contains the virtual machine analysis itself, the model of the virtualized environment, as well as its implementation for different hypervisors.
+* '''org.eclipse.tracecompass.lttng2.kernel.ui''' contains the views for the analysis.
+
+== Adding support for an hypervisor ==
+
+Supporting a new hypervisor in Trace Compass requires implementing the model for this new hypervisor. The following sections will describe for each part of the model what has to be considered, what information we need to have, etc. Note that each hypervisor will require some work and investigation. The information might already be available as a single tracepoint for some, while other may require many tracepoints. It is also possible that some will require to add tracepoints, either to the kernel, or the hypervisor code itself, in which case a userspace trace (LTTng UST) might be necessary to get all the information.
+
+=== Virtual CPU analysis ===
+
+This analysis tracks the state of the virtual CPUs in conjunction with the physical CPU it is running on. For this, we need the following information:
+
+* A way to link a virtual CPU on a guest with a process on the host, such that it is possible to determine when the virtual CPU is preempted on the host. If trace data does not provide this information, some hypervisors have a command line option to dump that information. Manually feeding that information to the analysis is not supported now though.
+* A way to differentiate between hypervisor mode and normal mode for the virtual CPU. A virtual CPU usually runs within a process on the host, but sometimes that process may need to run hypervisor-specific code. That is called '''hypervisor mode'''. During that time, no code from the guest itself is run. Typically, the process is running on the host (not preempted), but from the guest's point of view, the virtual CPU should be preempted.
+
+A model implementation for a new hypervisor will need to implement class '''IVirtualMachineModel''', that can be found in package '''org.eclipse.tracecompass.internal.lttng2.kernel.core.analysis.vm.model'''. See the javadoc in the class itself for more information on what each method does.
+
+= JUL Logging =
+
+Logging can be quite useful to debug a class, see its interactions with other components and understand the behavior of the system. TraceCompass uses JUL to log various events in the code, which can then be used to model and analyze the system's workflow. Here are some guidelines to use logging efficiently in Trace Compass. See the User Documentation for instructions on how to enable logging and obtain traces.
+
+=== Use a static logger for each class ===
+
+Each class should define and use their own static logger like this:
+
+ private static final Logger LOGGER = TraceCompassLog.getLogger(StateSystem.class);
+
+It is then easy to filter the components to log by their full class name. The ''TraceCompassLog#getLogger'' method is a wrapper for ''java.util.logging.Logger#getLogger'', but the Trace Compass's logging initialization (overriding the default's ConsoleHandler and INFO level for the org.eclipse.tracecompass namespace when logging is not enabled) is done in the static initializer of this class. Using the wrapper method ensures that this code is called and the user will not see Console message all over the place.
+
+'''Note on abstract classes''': It is debatable whether to use a static logger with the abstract class name or a logger with the concrete class's name.
+
+In the former case, logging for this class uses the classes's own namespace, but it is impossible to discriminate logging statement by concrete classes unless the concrete class name is added as parameter to the statement (when necessary).
+
+The latter case has the advantage that one can log only the concrete class and see all that goes on in the abstract class as well, but the concrete class may be in another namespace and will not benefit from the ''TraceCompassLog'' logging initialization and the user will see console logging happen.
+
+Both methods have their advantages and there is no clear good answer.
+
+=== Use a message supplier ===
+
+A logging statement, to be meaningful, will usually log a string that contains data from the context and will thus do string concatenation. This has a non-negligible overhead. To avoid having to do the costly string concatenation when the statement is not logged, java provides method taking a ''Supplier<String>'' as argument and that method should be used for all logging statements
+
+ LOGGER.info(() -> "[Component:Action] param1=" + myParam1 + ", param2=" + myParam2);
+
+=== Choose the appropriate log level ===
+
+The available log levels for JUL are SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST. The default level when not specified is INFO.
+
+* As a rule of thumb, enabling all INFO level statements should have a near zero impact on the execution, so log parameters that require some computations, or methods that are called very often should not be logged at INFO level.
+* CONFIG level should provide more detailed information than the INFO level, but still not impact the execution too much. It should be possible for a component to use up to CONFIG level statements and make meaningful analyses using the timestamps of the events.
+* FINE, FINER and FINEST are for statements that will not be used with the timestamps. Enabling them may have a visible effect on the performance of Trace Compass. They will typically be used with a purpose in mind, like debugging a component or getting data on caches for examples.
+
+=== Log message format ===
+
+JUL logging will produce trace data and unless one wants to visually parse a trace one event at a time, it will typically be used with an analysis to produce a result. To do so, the log messages should have a format that can then be associated with a trace type.
+
+Third party plugins provide a custom trace parser and LTTng trace type for JUL statements that use the following format
+
+ [EventName:MayContainSemiColon] paramName1=paramValue1, paramName2=paramValue2
projects / deliverable / tracecompass.git / blobdiff