Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Linux Tools Project/TMF/User Guide"
m (→Supported Traces) |
(Add TMF statistics framework user guide including tutorials) |
||
Line 1,032: | Line 1,032: | ||
=== Download Reference Plug-in === | === Download Reference Plug-in === | ||
To download the reference plug-in that demonstrates the reference loader, use the following link: [[Media:ReferencePlugin.zip | Reference Plug-in]]. Just extract the zip file and import the extracted Eclipse plug-in (plug-in name: ''org.eclipse.linuxtools.tmf.reference.ui'') to your Eclipse workspace. <br> | To download the reference plug-in that demonstrates the reference loader, use the following link: [[Media:ReferencePlugin.zip | Reference Plug-in]]. Just extract the zip file and import the extracted Eclipse plug-in (plug-in name: ''org.eclipse.linuxtools.tmf.reference.ui'') to your Eclipse workspace. <br> | ||
+ | |||
+ | = TMF Statistic Framework = | ||
+ | TMF provides a framework for displaying and collection trace specific statistics. By default, the generic statistics view displays the number events per event type and per trace. The design can be easily extended to display other types of statistics depending on the application. This following section will describe the default TMF Statistics View and it's usage. Subsequent sections will be explain how to extend the framework for other types of statistics. | ||
+ | |||
+ | == Default TMF Statistics View == | ||
+ | To open the TMF Statistics View, select '''Windows -> Show View -> Other... -> Tracing -> TMF Statistics''' | ||
+ | A new view will open with the name TMF Statistics. This view shows 2 columns ''Level'' and ''Number of Events''. After parsing a trace the view will display the number of events per event type. The cell where the number of events are printed also contain a coloured bar that indicates the percentage of the event count in relation to the total number of events. The statistics ic collected for the whole trace. The example below shows the statistics for an TMF experiment with 2 LTTng traces in it. | ||
+ | |||
+ | [[Image:TmfStatisticsView.png]]<br> | ||
+ | |||
+ | == Extending the TMF Statistic Framework == | ||
+ | |||
+ | To create customized Statistics View several class implementations have to be provided. | ||
+ | * Statistics Data Model | ||
+ | * Column Data Provider | ||
+ | * Statistics View Implementation | ||
+ | |||
+ | === Statistics Data Model === | ||
+ | First of all a data model has to be created. The TMF statistics model is based on tree. Each node can be reached by a path implmented by an array of strings (class ''org.eclipse.linuxtools.tmf.util.TmfFixedArray''). The software designer has the choice to extend the abstract class ''org.eclipse.linuxtools.tmf.ui.views.statistics.model.AbsTmfStatisticsTree'' or to extend a basic implementation of ''AbsTmfStatisticsTree'' with the name ''org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsTree''. | ||
+ | |||
+ | Depending on the application and types of statistic, the following methods need to be considered for overwriting: | ||
+ | |||
+ | * protected TmfFixedArray<String>[] getNormalPaths(TmfEvent event, ITmfExtraEventInfo extraInfo); | ||
+ | * protected TmfFixedArray<String>[] getTypePaths(TmfEvent event, ITmfExtraEventInfo extraInfo); | ||
+ | * protected abstract void registerName(final TmfFixedArray<String> path); | ||
+ | * public abstract Collection<TmfStatisticsTreeNode> getChildren(final TmfFixedArray<String> path); | ||
+ | * public abstract Collection<TmfStatisticsTreeNode> getAllChildren(final TmfFixedArray<String> path); | ||
+ | * public abstract void increase(TmfEvent event, ITmfExtraEventInfo extraInfo, int values); | ||
+ | * public abstract void registerEvent(TmfEvent event, ITmfExtraEventInfo extraInfo); | ||
+ | |||
+ | If other statistic types than number of events have to be counted the designer has to extend the ''TmfStatistics'' class and add other statistics. Such other statistic could be for example elapsed time or latency. To be able to use this subclass the designer has to extend class ''TmfStatisticsTreeNode''. The constructor will have to instantiate the new ''TmfStatistics'' class and save it in the member ''fValue''. All other classes below will have to use these new classes to display the addtional statistics. | ||
+ | |||
+ | === Column Data Provider === | ||
+ | For that the designer has the choise of implementing the interface ''org.eclipse.linuxtools.tmf.ui.views.statistics.model.ITmfColumnDataProvider'' or extend the base implementation ''org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider''. This implementation defines the columns of the statistics tree in the view. The ''TmfBaseColumnDataProvider'' can be used if only the event types need to be counted on different levels. | ||
+ | |||
+ | If other statistics types than number of events have to be counted the designer has to make sure that the column provider uses the class that extends ''TmfStatistics''. | ||
+ | |||
+ | === Statistics View Implementation === | ||
+ | The provided TMF Statistic View implementation takes a data model from type ''AbsTmfStatisticsTree'' and uses the column data provider that implements the interface ''ITmfColumnDataProvider'' to display statistics in a tree structure. The view also requests data from the trace and feeds it to the model. By default it uses the base model ''TmfBaseStatisticsTree'' and the ''TmfBaseColumnDataProvider''. To change this the designer has to overwrite the following methods to provide their own implementation. | ||
+ | |||
+ | * protected AbsTmfStatisticsTree getStatisticData(); | ||
+ | * protected ITmfColumnDataProvider getColumnDataProvider(); | ||
+ | * protected void requestData(final TmfExperiment<?> experiment, TmfTimeRange timeRange); | ||
+ | |||
+ | If other statistic than number of events have to be counted the designer has to implement the retrieval and analysis of events from the trace. For that, the designer might have to overwrite the method below, implement it's own TmfDataRequest, parse each event and feed that event along with ITmfExtraEventInfo to the data model (see [[#Statistics Data Model|Statistics Data Model]] for more details about the data model). | ||
+ | |||
+ | * protected void requestData(final TmfExperiment<?> experiment, TmfTimeRange timeRange); | ||
+ | |||
+ | == Tutorials == | ||
+ | This section provides two tutorials to explain how to extend the TMF statistics framework for other statistics than the default statistics. Tutorial 1 explains how to add new levels for counting event types. The second tutorial explains how to add new columns of statistics. The example source code depends on the ''LTTng'' feature including ''TMF'' of the Eclipse's Linux Tools project. | ||
+ | |||
+ | === Tutorial 1: Adding a New Statistics Level === | ||
+ | This tutorial explains how to add new levels (e.g. process level, CPU level) for counting event types. The LTTng example used will also count event types per CPU ID. | ||
+ | |||
+ | ==== Creating an Eclipse Plug-in for Statistics ==== | ||
+ | A new Eclipse plug-in will be used for the new statistics view. Please refer to section [[#Creating an Eclipse UI Plug-in | Creating an Eclipse UI Plug-in]] for how to create an Eclipse Plug-in. Now create a plug-in with the name ''org.eclipse.linuxtools.ust.sample.ui''. | ||
+ | |||
+ | To be able to use the TMF Statistics, the new plug-in requires the plug-in ''org.eclipse.linuxtools.tmf.ui'' and ''org.eclipse.linuxtools.tmf.core''. See chapter [[#Creating a Sequence Diagram View | Creating a Sequence Diagram View]] for how to add plug-dependencies. For this tutorial also add ''org.eclipse.linuxtools.lttng.core'' as plug-in dependency. <br> | ||
+ | |||
+ | ==== Creating a Customized Statistics Data Model ==== | ||
+ | |||
+ | Next we need to extend the statistics data model and data providers based on existing base class in TMF. | ||
+ | |||
+ | Firstly, create a new package with name ''model''. To create a new package, select java ''org.eclipse.linuxtools.ust.sample.ui'' in the package explorer, then select '''File->New->Package'''. An new dialog box will open for the creation of a package. Fill in the relevant data and press '''Finish'''. | ||
+ | |||
+ | [[Image:TmfAddModelPackage.png]] | ||
+ | |||
+ | To create a new model class, select ''org.eclipse.linuxtools.ust.sample.ui.model'' in the package explorer, then select '''File->New->Class'''. An new dialog box will open for the creation of a class. Fill in the ''Name'' and ''Superclass'' and press '''Finish'''. | ||
+ | |||
+ | [[Image:TmfAddModelClass.png]] | ||
+ | |||
+ | A new Java class will be created with the name ''org.eclipse.linuxtools.ust.sample.ui.statistics.CustomStatisticsModel''.<br> | ||
+ | |||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample.ui.model; | ||
+ | |||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsTree; | ||
+ | |||
+ | public class CustomStatisticsModel extends TmfBaseStatisticsTree { | ||
+ | |||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | The new class have to be filled. The ''CustomStatisticsModel'' extends ''TmfBaseStatisticsTree'', which extends the abstract class ''AbsTmfStatisticsTree''. The base class provides base implementations for abstract methods. Depending on the application these methods need to overwritten. | ||
+ | |||
+ | For this example change the ''CustomStatisticsModel'' as follows: | ||
+ | |||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample.ui.model; | ||
+ | |||
+ | import java.util.ArrayList; | ||
+ | import java.util.Arrays; | ||
+ | import java.util.HashSet; | ||
+ | import java.util.List; | ||
+ | import java.util.Map; | ||
+ | import java.util.Set; | ||
+ | |||
+ | import org.eclipse.linuxtools.lttng.event.LttngEvent; | ||
+ | import org.eclipse.linuxtools.tmf.event.TmfEvent; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.ITmfExtraEventInfo; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsTree; | ||
+ | import org.eclipse.linuxtools.tmf.util.TmfFixedArray; | ||
+ | |||
+ | public class CustomStatisticsModel extends TmfBaseStatisticsTree { | ||
+ | |||
+ | /** | ||
+ | * <h4>Header for the event types categories.</h4> | ||
+ | */ | ||
+ | protected static final String HEADER_CPUS = "CPUs"; //$NON-NLS-1$ | ||
+ | |||
+ | /** | ||
+ | * Construct a UST statistics tree. | ||
+ | * Add the CPU category to the base statistics tree from TmfBaseStatisticsData | ||
+ | */ | ||
+ | public CustomStatisticsModel() { | ||
+ | super(); | ||
+ | Map<String, Set<String>> keys = getKeys(); | ||
+ | |||
+ | // //////////// Adding category sets | ||
+ | keys.put(HEADER_CPUS, new HashSet<String>()); | ||
+ | |||
+ | // /////////// Adding value sets | ||
+ | // Under a trace | ||
+ | // Add the CPU category to the root node | ||
+ | Set<String> temp = keys.get(ROOT_NODE_KEY); | ||
+ | if (temp == null) { | ||
+ | temp = new HashSet<String>(); | ||
+ | } | ||
+ | temp.add(HEADER_CPUS); | ||
+ | keys.put(ROOT_NODE_KEY, temp); | ||
+ | // Under a CPU | ||
+ | temp = new HashSet<String>(4); | ||
+ | temp.add(HEADER_EVENT_TYPES); | ||
+ | keys.put(mergeString(HEADER_CPUS, NODE), temp); | ||
+ | } | ||
+ | |||
+ | /* | ||
+ | * (non-Javadoc) | ||
+ | * @see org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsData#getNormalPaths(org.eclipse.linuxtools.tmf.event.TmfEvent, | ||
+ | * org.eclipse.linuxtools.tmf.ui.views.statistics.ITmfEventInfo) | ||
+ | */ | ||
+ | @Override | ||
+ | @SuppressWarnings("unchecked") | ||
+ | protected TmfFixedArray<String>[] getNormalPaths(TmfEvent event, ITmfExtraEventInfo extraInfo) { | ||
+ | String trace = extraInfo.getTraceName(); | ||
+ | LttngEvent lttngEvent = (LttngEvent) event; | ||
+ | String cpus = String.valueOf(lttngEvent.getCpuId()); | ||
+ | |||
+ | List<TmfFixedArray<String>> paths = new ArrayList<TmfFixedArray<String>>(Arrays.asList(super.getNormalPaths(event, extraInfo))); | ||
+ | |||
+ | paths.add(new TmfFixedArray<String>(trace, HEADER_CPUS, cpus)); | ||
+ | return paths.toArray(new TmfFixedArray[0]); | ||
+ | } | ||
+ | |||
+ | /* | ||
+ | * (non-Javadoc) | ||
+ | * @see org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsData#getTypePaths(org.eclipse.linuxtools.tmf.event.TmfEvent, | ||
+ | * org.eclipse.linuxtools.tmf.ui.views.statistics.ITmfEventInfo) | ||
+ | */ | ||
+ | @Override | ||
+ | @SuppressWarnings("unchecked") | ||
+ | protected TmfFixedArray<String>[] getTypePaths(TmfEvent event, ITmfExtraEventInfo extraInfo) { | ||
+ | String trace = extraInfo.getTraceName(); | ||
+ | LttngEvent lttngEvent = (LttngEvent) event; | ||
+ | String cpus = String.valueOf(lttngEvent.getCpuId()); | ||
+ | |||
+ | List<TmfFixedArray<String>> paths = new ArrayList<TmfFixedArray<String>>(Arrays.asList(super.getTypePaths(event, extraInfo))); | ||
+ | |||
+ | String type = event.getType().toString(); | ||
+ | |||
+ | paths.add(new TmfFixedArray<String>(trace, HEADER_CPUS, cpus, HEADER_EVENT_TYPES, type)); | ||
+ | return paths.toArray(new TmfFixedArray[0]); | ||
+ | } | ||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | ==== Creating a Customized Column Data Provider ==== | ||
+ | |||
+ | A column provider for the tree viewer of the Statistics View is needed. Create a new class (as described above) with ''Name'' CustomColumnDataProvider and ''Superclass'' ''org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider''. | ||
+ | |||
+ | A new Java class will be created with the name ''org.eclipse.linuxtools.ust.sample.ui.statistics.model.CustomColumnDataProvider''.<br> | ||
+ | |||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample.ui.model; | ||
+ | |||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider; | ||
+ | |||
+ | public class CustomColumnDataProvider extends TmfBaseColumnDataProvider { | ||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | The ''CustomColumnDataProvider'' extends ''TmfBaseColumnDataProvider'', which implements the interface ''ITmfColumnDataProvider''. The base class provides base implementations for the interface. Depending on the application the methods need to overwritten. For this example change the ''CustomColumnDataProvider'' as follows: | ||
+ | |||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample.ui.model; | ||
+ | |||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider; | ||
+ | |||
+ | public class CustomColumnDataProvider extends TmfBaseColumnDataProvider { | ||
+ | public CustomColumnDataProvider() { | ||
+ | super(); | ||
+ | fFolderLevels.add(CustomStatisticsModel.HEADER_CPUS); | ||
+ | } | ||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | ==== Creating a Customized Statistics View ==== | ||
+ | |||
+ | In the MANIFEST.MF file, 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> | ||
+ | [[Image:AddViewExtension1.png]]<br> | ||
+ | |||
+ | A new view entry has been created. Fill in the fields ''id'', ''name'' and ''class''. | ||
+ | |||
+ | [[Image:TmfAddStatisticsView.png]] <br> | ||
+ | |||
+ | To create the view class, press on the label ''class''. A new dialog box will open for the creation of the statistics class. This class will extend the basic view implementation ''TmfStatisticsView''. Fill in ''Name'' and ''Superclass''<br> and press '''Finish'''. | ||
+ | |||
+ | [[Image:TmfAddStatisticsViewClass.png]] | ||
+ | |||
+ | A new Java class will be created with the name ''org.eclipse.linuxtools.ust.sample.ui.statistics.CustomStatisticsView''.<br> | ||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample.ui; | ||
+ | |||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.TmfStatisticsView; | ||
+ | |||
+ | public class CustomStatisticsView extends TmfStatisticsView { | ||
+ | |||
+ | public CustomStatisticsView(String viewName) { | ||
+ | super(viewName); | ||
+ | // TODO Auto-generated constructor stub | ||
+ | } | ||
+ | |||
+ | public CustomStatisticsView() { | ||
+ | // TODO Auto-generated constructor stub | ||
+ | } | ||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | At last, implement the class ''CustomStatisticsView'' which extends ''TmfStatisticsView''. Depending on the application certain methods need to overwritten. For this example change the ''CustomStatisticsView'' as follows: | ||
+ | |||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample.ui; | ||
+ | |||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.TmfStatisticsView; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.AbsTmfStatisticsTree; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.ITmfColumnDataProvider; | ||
+ | import org.eclipse.linuxtools.ust.sample.ui.model.CustomColumnDataProvider; | ||
+ | import org.eclipse.linuxtools.ust.sample.ui.model.CustomStatisticsModel; | ||
+ | |||
+ | public class CustomStatisticsView extends TmfStatisticsView { | ||
+ | |||
+ | /** | ||
+ | * The ID correspond to the package in which this class is embedded | ||
+ | */ | ||
+ | public static final String ID = "org.eclipse.linuxtools.lttng.ui.views.ustStatistics"; //$NON-NLS-1$ | ||
+ | |||
+ | /** | ||
+ | * Constructor of a statistics view. | ||
+ | * | ||
+ | * @param viewName | ||
+ | * The name to give to the view. | ||
+ | */ | ||
+ | public CustomStatisticsView(String viewName) { | ||
+ | super(viewName); | ||
+ | } | ||
+ | |||
+ | private static final String UST_STATISTICS_VIEW = "USTStatisticsView"; //$NON-NLS-1$ | ||
+ | |||
+ | /** | ||
+ | * Default constructor. | ||
+ | */ | ||
+ | public CustomStatisticsView() { | ||
+ | this(UST_STATISTICS_VIEW); | ||
+ | } | ||
+ | |||
+ | /* | ||
+ | * (non-Javadoc) | ||
+ | * @see org.eclipse.linuxtools.tmf.ui.views.statistics.TmfStatisticsView#getStatisticData() | ||
+ | */ | ||
+ | @Override | ||
+ | protected AbsTmfStatisticsTree getStatisticData() { | ||
+ | return new CustomStatisticsModel(); | ||
+ | } | ||
+ | |||
+ | /* | ||
+ | * (non-Javadoc) | ||
+ | * @see org.eclipse.linuxtools.tmf.ui.views.statistics.TmfStatisticsView#getColumnDataProvider() | ||
+ | */ | ||
+ | @Override | ||
+ | protected ITmfColumnDataProvider getColumnDataProvider() { | ||
+ | return new CustomColumnDataProvider(); | ||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | ==== Running the Eclipse Application ==== | ||
+ | |||
+ | Now it's time to run the example application. To launch the Example Application select the ''Overview'' tab of the MANIFEST.MF file and click on '''Launch an Eclipse Application'''. A new Eclipse application window will be shown. In the new window go to '''Windows -> Show View -> Other... -> Other -> Custom Statistics View'''. A new view will open. After parsing a trace the view will display the number of events per event type as well as the number of events per CPU and event type. For an example trace the output looks as follows: | ||
+ | |||
+ | [[Image:CustomStatisticsView.png]] | ||
+ | |||
+ | ==== Downloading the tutorial ==== | ||
+ | Use the following link to download the source code of the tutorial: [[Media:SampleStatsPlugin.zip | Plug-in of Statistics Tutorial]] | ||
+ | |||
+ | === Tutorial 2: Adding new Statistic Types === | ||
+ | This tutorial will describe how to extend the TMF statistics to support other event types. In addition to the number of events this statistics implementation will provide the longest latency in nano seconds. The latency is the time spent between two related events, a start event and an end event. The latency will be shown at the level of the end event. In the example below no analysis is implemented. The ''LatencyCalculator'' class just generates random numbers for certain events. | ||
+ | |||
+ | Create an Eclipse plug-in with name ''org.eclipse.linuxtools.ust.sample2.ui'' as described in [[#Creating an Eclipse UI Plug-in | Creating an Eclipse UI Plug-in]]. Also create a model package with name ''org.eclipse.linuxtools.ust.sample2.ui.statistics.model'' as described in [[#Creating a Customized Statistics Data Model | Creating a Customized Statistics Data Model]]. | ||
+ | |||
+ | ==== Implementing a Customized Statistics Data Model ==== | ||
+ | Firstly, add the ''LatencyCalculator'' class. Under package ''org.eclipse.linuxtools.ust.sample2.ui.statistics.model'', create a new class (as described above) with ''Name'' LatencyCalculator. Add the following implementation: | ||
+ | |||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample2.ui.model; | ||
+ | |||
+ | import org.eclipse.linuxtools.lttng.event.LttngEvent; | ||
+ | |||
+ | public class LatencyCalculator { | ||
+ | |||
+ | private final long fMin = 400; | ||
+ | private final long fMax = 20000000; | ||
+ | |||
+ | /** | ||
+ | * Dummy implementation | ||
+ | */ | ||
+ | public void initialize() { | ||
+ | } | ||
+ | |||
+ | /** | ||
+ | * Dummy implementation that returns random latency values for certain event types. | ||
+ | * | ||
+ | * @param event | ||
+ | * @return latency or -1 | ||
+ | */ | ||
+ | @SuppressWarnings("nls") | ||
+ | public long calculate (LttngEvent event) { | ||
+ | |||
+ | String markerName = event.getMarkerName(); | ||
+ | |||
+ | if (markerName.equals("syscall_exit") || markerName.equals("softirq_exit") || markerName.equals("close") || markerName.equals("process_exit")) { | ||
+ | long random = fMin + (int)(Math.random() * ((fMax - fMin) + 1)); | ||
+ | return random; | ||
+ | } | ||
+ | return -1; | ||
+ | } | ||
+ | } | ||
+ | |||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | Next, we need a new class that holds the new counter and that extends ''TmfStatistics''. Under package ''org.eclipse.linuxtools.ust.sample2.ui.statistics.model'', create a new class (as described above) with ''Name'' NewStatistics and ''Superclass'' ''org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatistics''. A new Java class will be created with the name ''org.eclipse.linuxtools.ust.sample2.ui.statistics.model.NewStatistics''.<br> | ||
+ | |||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample2.ui.model; | ||
+ | |||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatistics; | ||
+ | |||
+ | public class NewStatistics extends TmfStatistics { | ||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | Add the latency statistics to this class. | ||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample2.ui.model; | ||
+ | |||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatistics; | ||
+ | |||
+ | public class NewStatistics extends TmfStatistics { | ||
+ | public long latency = 0; | ||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | Next step is it to extend the class ''TmfStatisticsTreeNode'' so that the class ''NewStatistics'' is used instead of the base type. | ||
+ | |||
+ | Under package ''org.eclipse.linuxtools.ust.sample2.ui.statistics.model'', create a new class (as described above) with ''Name'' NewStatisticsTreeNode and ''Superclass'' ''org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatisticsTreeNode''. A new Java class will be created with the name ''org.eclipse.linuxtools.ust.sample2.ui.statistics.model.NewStatisticsTreeNode''.<br> | ||
+ | |||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample2.ui.model; | ||
+ | |||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.AbsTmfStatisticsTree; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatisticsTreeNode; | ||
+ | import org.eclipse.linuxtools.tmf.util.TmfFixedArray; | ||
+ | |||
+ | public class NewStatisticsTreeNode extends TmfStatisticsTreeNode { | ||
+ | |||
+ | public NewStatisticsTreeNode(TmfFixedArray<String> path, AbsTmfStatisticsTree nodes) { | ||
+ | super(path, nodes); | ||
+ | // TODO Auto-generated constructor stub | ||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | Now we need to update the code to use and instantiate ''CustomStatistics'' instead of ''TmfStatistics''. | ||
+ | |||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample2.ui.model; | ||
+ | |||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.AbsTmfStatisticsTree; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatisticsTreeNode; | ||
+ | import org.eclipse.linuxtools.tmf.util.TmfFixedArray; | ||
+ | |||
+ | public class NewStatisticsTreeNode extends TmfStatisticsTreeNode { | ||
+ | |||
+ | public NewStatisticsTreeNode(TmfFixedArray<String> path, AbsTmfStatisticsTree nodes) { | ||
+ | super(path, nodes); | ||
+ | fValue = new NewStatistics(); | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | public void reset() { | ||
+ | super.reset(); | ||
+ | fValue = new NewStatistics(); | ||
+ | } | ||
+ | } | ||
+ | |||
+ | Next, create the statistics model class which extends ''TmfBaseStatisticsTree''. Under package ''org.eclipse.linuxtools.ust.sample2.ui.statistics.model'', create a new class (as described above) with ''Name'' NewStatisticsModel and ''Superclass'' ''org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsTree''. A new Java class will be created with the name ''org.eclipse.linuxtools.ust.sample2.ui.statistics.model.NewStatisticsModel''.<br> | ||
+ | |||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample2.ui.model; | ||
+ | |||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsTree; | ||
+ | |||
+ | public class NewStatisticsModel extends TmfBaseStatisticsTree { | ||
+ | |||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | Now we have to override certain method to use the new statistics class ''NewStatistics'' and to count the latency. | ||
+ | |||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample2.ui.model; | ||
+ | |||
+ | import org.eclipse.linuxtools.lttng.event.LttngEvent; | ||
+ | import org.eclipse.linuxtools.tmf.event.TmfEvent; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.ITmfExtraEventInfo; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsTree; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatistics; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatisticsTreeNode; | ||
+ | import org.eclipse.linuxtools.tmf.util.TmfFixedArray; | ||
+ | |||
+ | public class NewStatisticsModel extends TmfBaseStatisticsTree { | ||
+ | |||
+ | private LatencyCalculator fLatencyCalulator; | ||
+ | |||
+ | public NewStatisticsModel() { | ||
+ | super(); | ||
+ | fLatencyCalulator = new LatencyCalculator(); | ||
+ | fLatencyCalulator.initialize(); | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | public void increase(TmfEvent event, ITmfExtraEventInfo extraInfo, int values) { | ||
+ | |||
+ | if (event instanceof LttngEvent) { | ||
+ | |||
+ | long latency = fLatencyCalulator.calculate((LttngEvent)event); | ||
+ | |||
+ | if (latency >= 0) { | ||
+ | TmfFixedArray<String>[] paths = getNormalPaths(event, extraInfo); | ||
+ | |||
+ | for (TmfFixedArray<String> path : paths) { | ||
+ | TmfStatistics current = getOrCreate(path).getValue(); | ||
+ | if (current instanceof NewStatistics) { | ||
+ | ((NewStatistics)current).latency = Math.max(((NewStatistics)current).latency, latency); | ||
+ | } | ||
+ | } | ||
+ | paths = getTypePaths(event, extraInfo); | ||
+ | for (TmfFixedArray<String> path : paths) { | ||
+ | TmfStatistics current = getOrCreate(path).getValue(); | ||
+ | if (current instanceof NewStatistics) { | ||
+ | ((NewStatistics)current).latency = Math.max(((NewStatistics)current).latency, latency); | ||
+ | } | ||
+ | } | ||
+ | } | ||
+ | } | ||
+ | else { | ||
+ | return; | ||
+ | } | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | public TmfStatisticsTreeNode getOrCreate(final TmfFixedArray<String> path) { | ||
+ | TmfStatisticsTreeNode current = fNodes.get(path); | ||
+ | if (current == null) { | ||
+ | registerName(path); | ||
+ | current = new NewStatisticsTreeNode(path, this); | ||
+ | fNodes.put(path, current); | ||
+ | } | ||
+ | return current; | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | public void reset(final TmfFixedArray<String> path) { | ||
+ | super.reset(path); | ||
+ | fLatencyCalulator.initialize(); | ||
+ | } | ||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | ==== Implementing a Customized Column Data Provider ==== | ||
+ | |||
+ | A column provider for the tree viewer of the Statistics View is needed. Create a new class (as described above) with ''Name'' NewColumnDataProvider and ''Superclass'' ''org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider''. | ||
+ | |||
+ | A new Java class will be created with the name ''org.eclipse.linuxtools.ust.sample2.ui.statistics.model.NewColumnDataProvider''.<br> | ||
+ | |||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample2.ui.model; | ||
+ | |||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider; | ||
+ | |||
+ | public class NewColumnDataProvider extends TmfBaseColumnDataProvider { | ||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | The ''NewColumnDataProvider'' extends ''TmfBaseColumnDataProvider'', which implements the interface ''ITmfColumnDataProvider''. An new column has to be created by adding a ''TmfBaseColumnData'' to the ColumnData list. For this example change the ''NewColumnDataProvider'' as follows: | ||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample2.ui.model; | ||
+ | |||
+ | import org.eclipse.jface.viewers.ColumnLabelProvider; | ||
+ | import org.eclipse.jface.viewers.Viewer; | ||
+ | import org.eclipse.jface.viewers.ViewerComparator; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnData; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatistics; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatisticsTreeNode; | ||
+ | import org.eclipse.swt.SWT; | ||
+ | |||
+ | public class NewStatisticsColumnDataProvider extends TmfBaseColumnDataProvider { | ||
+ | |||
+ | protected final static String TIME_COUNT_COLUMN = "Longest Latency"; //$NON-NLS-1$ | ||
+ | protected final static String TIME_COLUMN_TIP = "Longest Latency for give start event"; //$NON-NLS-1$ | ||
+ | |||
+ | public NewStatisticsColumnDataProvider() { | ||
+ | super(); | ||
+ | fColumnData.add(new TmfBaseColumnData(TIME_COUNT_COLUMN, 125, SWT.LEFT, TIME_COLUMN_TIP, new ColumnLabelProvider() { | ||
+ | @Override | ||
+ | public String getText(Object element) { | ||
+ | TmfStatisticsTreeNode node = (TmfStatisticsTreeNode) element; | ||
+ | if (!fFolderLevels.contains(node.getKey())) { | ||
+ | TmfStatistics value = node.getValue(); | ||
+ | if (value instanceof NewStatistics) { | ||
+ | long longValue = ((NewStatistics)node.getValue()).latency; | ||
+ | if (longValue != 0) { | ||
+ | return String.valueOf(longValue); | ||
+ | } | ||
+ | return ""; //$NON-NLS-1$ | ||
+ | } | ||
+ | } | ||
+ | return ""; //$NON-NLS-1$ | ||
+ | } | ||
+ | }, new ViewerComparator() { | ||
+ | @Override | ||
+ | public int compare(Viewer viewer, Object e1, Object e2) { | ||
+ | TmfStatisticsTreeNode n1 = (TmfStatisticsTreeNode) e1; | ||
+ | TmfStatisticsTreeNode n2 = (TmfStatisticsTreeNode) e2; | ||
+ | |||
+ | TmfStatistics value1 = n1.getValue(); | ||
+ | TmfStatistics value2 = n2.getValue(); | ||
+ | if (value1 instanceof NewStatistics && value2 instanceof NewStatistics) { | ||
+ | return (int) (((NewStatistics) value1).latency - ((NewStatistics) value2).latency); | ||
+ | } | ||
+ | |||
+ | return 0; | ||
+ | |||
+ | } | ||
+ | }, null)); // null to indicate that there isn't a percentage provider | ||
+ | } | ||
+ | } | ||
+ | |||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | ==== Implementing a Customized Statistics View ==== | ||
+ | |||
+ | Add a new Eclipse view with the view name ''New Statistics View'' and a view class with name ''NewStatisticsView'' that extends ''TmfStatisticsView'' as described in section [[#Creating a Customized Statistics View | Creating a Customized Statistics View]]. | ||
+ | |||
+ | A new Java class will be created with the name ''org.eclipse.linuxtools.ust.sample.ui.statistics.NewStatisticsView''.<br> | ||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample2.ui; | ||
+ | |||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.TmfStatisticsView; | ||
+ | |||
+ | public class NewStatisticsView extends TmfStatisticsView { | ||
+ | |||
+ | public CustomStatisticsView(String viewName) { | ||
+ | super(viewName); | ||
+ | // TODO Auto-generated constructor stub | ||
+ | } | ||
+ | |||
+ | public CustomStatisticsView() { | ||
+ | // TODO Auto-generated constructor stub | ||
+ | } | ||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | At last, override all relevant methods as shown below: | ||
+ | |||
+ | <code> | ||
+ | <pre> | ||
+ | package org.eclipse.linuxtools.ust.sample2.ui; | ||
+ | |||
+ | import org.eclipse.linuxtools.tmf.event.TmfTimeRange; | ||
+ | import org.eclipse.linuxtools.tmf.experiment.TmfExperiment; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.TmfStatisticsView; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.AbsTmfStatisticsTree; | ||
+ | import org.eclipse.linuxtools.tmf.ui.views.statistics.model.ITmfColumnDataProvider; | ||
+ | import org.eclipse.linuxtools.ust.sample2.ui.model.NewStatisticsColumnDataProvider; | ||
+ | import org.eclipse.linuxtools.ust.sample2.ui.model.NewStatisticsModel; | ||
+ | |||
+ | public class NewStatisticsView extends TmfStatisticsView { | ||
+ | |||
+ | public NewStatisticsView(String viewName) { | ||
+ | super(viewName); | ||
+ | } | ||
+ | |||
+ | public NewStatisticsView() { | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | protected AbsTmfStatisticsTree getStatisticData() { | ||
+ | return new NewStatisticsModel(); | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | protected ITmfColumnDataProvider getColumnDataProvider() { | ||
+ | return new NewStatisticsColumnDataProvider(); | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | protected void requestData(final TmfExperiment<?> experiment, TmfTimeRange timeRange) { | ||
+ | // do some initialization | ||
+ | super.requestData(experiment, timeRange); | ||
+ | } | ||
+ | } | ||
+ | </pre> | ||
+ | </code> | ||
+ | |||
+ | ==== Running the Eclipse Application ==== | ||
+ | |||
+ | Now it's time to run the example application. To launch the Example Application select the ''Overview'' tab of the MANIFEST.MF file and click on '''Launch an Eclipse Application'''. A new Eclipse application window will be shown. In the new window go to '''Windows -> Show View -> Other... -> Other -> New Statistics View'''. A new view will open. After parsing a trace the view will display the number of events per event type and longest latency were it is applicable. On the trace level the longest latency of all latencies is shown as well. For an example trace the output looks as follows: | ||
+ | |||
+ | [[Image:ExampleNewStatsView.png]] | ||
+ | |||
+ | ==== Downloading the tutorial ==== | ||
+ | Use the following link to download the source code of the tutorial: [[Media:SampleStatsPlugin2.zip | Plug-in of Statistics Tutorial]] |
Revision as of 09:08, 1 November 2011
{{#eclipseproject:technology.linux-distros}}
Linux Tools | |
Website | |
Download | |
Community | |
Mailing List • Forums • IRC • mattermost | |
Issues | |
Open • Help Wanted • Bug Day | |
Contribute | |
Browse Source |
Contents
- 1 Introduction
- 2 TMF UML2 Sequence Diagram Framework
- 2.1 TMF UML2 Sequence Diagram Extensions
- 2.2 Management of the Extension Point
- 2.3 Sequence Diagram View
- 2.4 Tutorial
- 2.4.1 Prerequisites
- 2.4.2 Creating an Eclipse UI Plug-in
- 2.4.3 Creating a Sequence Diagram View
- 2.4.4 Defining the uml2SDLoader Extension
- 2.4.5 Implementing the Loader Class
- 2.4.6 Adding time information
- 2.4.7 Default Coolbar and Menu Items
- 2.4.8 Implementing Optional Callbacks
- 2.4.8.1 Using the Paging Provider Interface
- 2.4.8.2 Using the Find Provider Interface
- 2.4.8.3 Using the Filter Provider Interface
- 2.4.8.4 Using the Extended Action Bar Provider Interface
- 2.4.8.5 Using the Properties Provider Interface
- 2.4.8.6 Using the Collapse Provider Interface
- 2.4.8.7 Using the Selection Provider Service
- 2.4.9 Printing a Sequence Diagram
- 2.4.10 Using one Sequence Diagram View with Multiple Loaders
- 2.4.11 Download Tutorial
- 2.5 Integration of Tracing and Monitoring Framework with Sequence Diagram Framework
- 3 TMF Statistic Framework
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.
TMF UML2 Sequence Diagram Framework
The purpose of the UML2 Sequence Diagram Framework of TMF is to provide a framework for generation of UML2 sequence diagrams. It provides
- UML2 Sequence diagram drawing capabilities (i.e. lifelines, messages, activations, object creation and deletion)
- a generic, re-usable Sequence Diagram View
- Eclipse Extension Point for the creation of sequence diagrams
- callback hooks for searching and filtering within the Sequence Diagram View
- scalability
The following chapters describe the Sequence Diagram Framework as well as a reference implementation and its usage.
TMF UML2 Sequence Diagram Extensions
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
Since: Since 0.3.2 (based on UML2SD of org.eclipse.tptp.common.ui)
Description: This extension point aims to list and connect any UML2 Sequence Diagram loader.
Configuration Markup:
<!ELEMENT extension (uml2SDLoader)+> <!ATTLIST extension point CDATA #REQUIRED id CDATA #IMPLIED name CDATA #IMPLIED >
- point - A fully qualified identifier of the target extension point.
- id - An optional identifier of the extension instance.
- name - An optional name of the extension instance.
<!ELEMENT uml2SDLoader EMPTY> <!ATTLIST uml2SDLoader id CDATA #REQUIRED name CDATA #REQUIRED class CDATA #REQUIRED view CDATA #REQUIRED default (true | false)
- 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 algorythm 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.
- 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.
Management of the Extension Point
The TMF UI plug-in is responsible for evaluating each contribution to the extension point.
With this extension point, a loader class is associated with a Sequence Diagram View. Multiple loaders can be associated to a single Sequence Diagram View. However, additional means have to be implemented to specify which loader should be used when opening the view. For example, an eclipse action or command could be used for that. This additional code is not necessary if there is only one loader for a given Sequence Diagram View associated and this loader has the attribute "default" set to "true". (see also Using one Sequence Diagram View with Multiple Loaders)
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.
Supported Widgets
The loader class provides a frame containing all the UML2 widgets to be displayed. The following widgets exist:
- Lifeline
- Activation
- Synchronous Message
- Asynchronous Message
- Synchronous Message Return
- Asynchronous Message Return
- Stop
For a lifeline, a category can be defined. The lifeline category defines icons, which are displayed in the lifeline header.
Zooming
The Sequence Diagram View allows the user to zoom in, zoom out and reset the zoom factor.
Printing
It is possible to print the whole sequence diagram as well as part of it.
Key Bindings
- SHIFT+ALT+ARROW-DOWN - to scroll down within sequence diagram one view page at a time
- SHIFT+ALT+ARROW-UP - to scroll up within sequence diagram one view page at a time
- SHIFT+ALT+ARROW-RIGHT - to scroll right within sequence diagram one view page at a time
- SHIFT+ALT+ARROW-LEFT - to scroll left within sequence diagram one view page at a time
- SHIFT+ALT+ARROW-HOME - to jump to the beginning of the selected message if not already visible in page
- SHIFT+ALT+ARROW-END - to jump to the end of the selected message if not already visible in page
- CTRL+F - to open find dialog if either the basic or extended find provider is defined (see Using the Find Provider Interface)
- CTRL+P - to open print dialog
Preferences
The UML2 Sequence Diagram Framework provides preferences to customize the appearance of the Sequence Diagram View. The color of all widgets and text as well as the fonts of the text of all widget can be adjust. Amongst others the default lifeline width can be alternated. To change preferences select Windows->Preferences->Tracing->UML2 Sequence Diagrams. The following preference page will show:
After changing the preferences select OK.
Callback hooks
The Sequence Diagram View provides several callback hooks so that extension can provide application specific functionality. The following interfaces can be provided:
- Basic find provider or extended find Provider
For finding within the sequence diagram - Basic filter provider and extended Filter Provider
For filtering within the sequnce diagram. - Basic paging provider or advanced paging provider
For scalability reasons, used to limit number of displayed messages - Properies provider
To provide properties of selected elements - Collapse provider
To collapse areas of the sequence diagram
Tutorial
This tutorial describes how to create a UML2 Sequence Diagram Loader extension and use this loader in the in Eclipse.
Prerequisites
The tutorial is based on Eclipse 3.7 (Eclipse Indigo) and TMF 0.3.2.
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.
Creating a Sequence Diagram View
To open the plug-in manifest, 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.linuxtools.tmf.ui and press OK
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.
To create a Sequence Diagram View, click the right mouse button. Then select New -> view
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.
The view is prepared. Run the Example. To launch the an Eclipse Application select the Overview tab and click on Launch an Eclipse Application
A new Eclipse application window will show. In the new window go to Windows -> Show View -> Other... -> Other -> Sample Sequence Diagram.
The Sequence Diagram View will open with an blank page.
Close the Example Application.
Defining the uml2SDLoader Extension
After defining the Sequence Diagram View it's time to create the uml2SDLoader Extension.
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
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.
A new 'uml2SDLoader extension has been created. Fill in fields id, name, class, view and default. Use default equal true for this example. For the view add the id of the Sequence Diagram View of chapter Creating a Sequence Diagram View.
Then click on class (see above) to open the new class dialog box. Fill in the relevant fields and select Finish.
A new Java class will be created which implements the interface org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader.
package org.eclipse.linuxtools.tmf.sample.ui; import org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView; import org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader; public class SampleLoader implements IUml2SDLoader { public SampleLoader() { // TODO Auto-generated constructor stub } @Override public void dispose() { // TODO Auto-generated method stub } @Override public String getTitleString() { // TODO Auto-generated method stub return null; } @Override public void setViewer(SDView arg0) { // TODO Auto-generated method stub }
Implementing the Loader Class
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.
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; public class SampleLoader implements IUml2SDLoader { private SDView fSdView; public SampleLoader() { } @Override public void dispose() { } @Override public String getTitleString() { return "Sample Diagram"; } @Override public void setViewer(SDView arg0) { fSdView = arg0; createFrame(); } private void createFrame() { Frame testFrame = new Frame(); testFrame.setName("Sample Frame"); /* * Create lifelines */ Lifeline lifeLine1 = new Lifeline(); lifeLine1.setName("Object1"); testFrame.addLifeLine(lifeLine1); Lifeline lifeLine2 = new Lifeline(); lifeLine2.setName("Object2"); testFrame.addLifeLine(lifeLine2); /* * Create Sync Message */ // Get new occurrence on lifelines lifeLine1.getNewEventOccurrence(); // Get Sync message instances SyncMessage start = new SyncMessage(); start.setName("Start"); start.setEndLifeline(lifeLine1); testFrame.addMessage(start); /* * Create Sync Message */ // Get new occurrence on lifelines lifeLine1.getNewEventOccurrence(); lifeLine2.getNewEventOccurrence(); // Get Sync message instances SyncMessage syn1 = new SyncMessage(); syn1.setName("Sync Message 1"); syn1.setStartLifeline(lifeLine1); syn1.setEndLifeline(lifeLine2); testFrame.addMessage(syn1); /* * Create corresponding Sync Message Return */ // Get new occurrence on lifelines lifeLine1.getNewEventOccurrence(); lifeLine2.getNewEventOccurrence(); SyncMessageReturn synReturn1 = new SyncMessageReturn(); synReturn1.setName("Sync Message Return 1"); synReturn1.setStartLifeline(lifeLine2); synReturn1.setEndLifeline(lifeLine1); synReturn1.setMessage(syn1); testFrame.addMessage(synReturn1); /* * Create Activations (Execution Occurrence) */ ExecutionOccurrence occ1 = new ExecutionOccurrence(); occ1.setStartOccurrence(start.getEventOccurrence()); occ1.setEndOccurrence(synReturn1.getEventOccurrence()); lifeLine1.addExecution(occ1); occ1.setName("Activation 1"); ExecutionOccurrence occ2 = new ExecutionOccurrence(); occ2.setStartOccurrence(syn1.getEventOccurrence()); occ2.setEndOccurrence(synReturn1.getEventOccurrence()); lifeLine2.addExecution(occ2); occ2.setName("Activation 2"); /* * Create Sync Message */ // Get new occurrence on lifelines lifeLine1.getNewEventOccurrence(); lifeLine2.getNewEventOccurrence(); // Get Sync message instances AsyncMessage asyn1 = new AsyncMessage(); asyn1.setName("Async Message 1"); asyn1.setStartLifeline(lifeLine1); asyn1.setEndLifeline(lifeLine2); testFrame.addMessage(asyn1); /* * Create corresponding Sync Message Return */ // Get new occurrence on lifelines lifeLine1.getNewEventOccurrence(); lifeLine2.getNewEventOccurrence(); AsyncMessageReturn asynReturn1 = new AsyncMessageReturn(); asynReturn1.setName("Async Message Return 1"); asynReturn1.setStartLifeline(lifeLine2); asynReturn1.setEndLifeline(lifeLine1); asynReturn1.setMessage(asyn1); testFrame.addMessage(asynReturn1); /* * Create a note */ // Get new occurrence on lifelines lifeLine1.getNewEventOccurrence(); EllipsisisMessage info = new EllipsisisMessage(); info.setName("Object deletion"); info.setStartLifeline(lifeLine2); testFrame.addNode(info); /* * Create a Stop */ Stop stop = new Stop(); stop.setLifeline(lifeLine2); stop.setEventOccurrence(lifeLine2.getNewEventOccurrence()); lifeLine2.addNode(stop); fSdView.setFrame(testFrame); } }
Now it's time to run the example application. To launch the Example Application select the Overview tab and click on Launch an Eclipse Application
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. 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:
private void createFrame() { //... start.setTime(new TmfTimestamp(1000, (byte) -3)); syn1.setTime(new TmfTimestamp(1005, (byte) -3)); synReturn1.setTime(new TmfTimestamp(1050, (byte) -3)); asyn1.setStartTime(new TmfTimestamp(1060, (byte) -3)); asyn1.setEndTime(new TmfTimestamp(1070, (byte) -3)); asynReturn1.setStartTime(new TmfTimestamp(1060, (byte) -3)); asynReturn1.setEndTime(new TmfTimestamp(1070, (byte) -3)); //... }
When running the example application, a time compression bar on the left appears which indicates the time elapsed between consecutive events. The time compression scale shows where the time falls between the minimum and maximum delta times. The intensity of the color is used to indicate the length of time, namely, the deeper the intensity, the higher the delta time. The minimum and maximum delta times are configurable through the collbar menu Configure Min Max. The time compression bar and scale may provide an indication about which events consumes the most time. By hovering over the time compression bar a tooltip appears containing more information.
By hovering over a message it will show the time information in the appearing tooltip. For each SyncMessage it shows its time occurrence and for each AsyncMessage it shows the start and end time.
To see the time elapsed between 2 messages, select one message and hover over a second message. A tooltip will show with the delta in time. Note if the second message is before the first then a negative delta is displayed. Note that for AsynMessage the end time is used for the delta calculation.
Default Coolbar and Menu Items
The Sequence Diagram View comes with default coolbar and menu items. By default, each sequence diagram shows the following actions:
- Zoom in
- Zoom out
- Reset Zoom Factor
- Selection
- Configure Min Max (drop-down menu only)
- Navigation -> Show the node end (drop-down menu only)
- Navigation -> Show the node start (drop-down menu only)
Implementing Optional Callbacks
The following chapters describe how to use all supported provider interfaces.
Using the Paging Provider Interface
For scalability reasons, the paging provider interfaces exists to limit the number of messages displayed in the Sequence Diagram View at a time. For that, two interfaces exist, the basic paging provider and the advanced paging provider. When using the basic paging interface, actions for traversing page by page through the sequence diagram of a trace will be provided.
To use the basic paging provider, first the interface methods of the ISDPagingProvider have to be implemented by a class. (i.e. hasNextPage(), hasPrevPage(), nextPage(), prevPage(), firstPage() and endPage(). Typically, this is implemented in the loader class. Secondly, the provider has to be set in the Sequence Diagram View. This will be done in the setViewer() method of the loader class. Lastly, the paging provider has to be removed from the view, when the dispose() method of the loader class is called.
public class SampleLoader implements IUml2SDLoader, ISDPagingProvider { //... private page = 0; @Override public void dispose() { if (fSdView != null) { fSdView.resetProviders(); } } @Override public void setViewer(SDView arg0) { fSdView = arg0; fSdView.setSDPagingProvider(this); createFrame(); } private void createSecondFrame() { Frame testFrame = new Frame(); testFrame.setName("SecondFrame"); Lifeline lifeline = new Lifeline(); lifeline.setName("LifeLine 0"); testFrame.addLifeLine(lifeline); lifeline = new Lifeline(); lifeline.setName("LifeLine 1"); testFrame.addLifeLine(lifeline); for (int i = 1; i < 5; i++) { SyncMessage message = new SyncMessage(); message.autoSetStartLifeline(testFrame.getLifeline(0)); message.autoSetEndLifeline(testFrame.getLifeline(0)); message.setName((new StringBuilder("Message ")).append(i).toString()); testFrame.addMessage(message); SyncMessageReturn messageReturn = new SyncMessageReturn(); messageReturn.autoSetStartLifeline(testFrame.getLifeline(0)); messageReturn.autoSetEndLifeline(testFrame.getLifeline(0)); testFrame.addMessage(messageReturn); messageReturn.setName((new StringBuilder("Message return ")).append(i).toString()); ExecutionOccurrence occ = new ExecutionOccurrence(); occ.setStartOccurrence(testFrame.getSyncMessage(i - 1).getEventOccurrence()); occ.setEndOccurrence(testFrame.getSyncMessageReturn(i - 1).getEventOccurrence()); testFrame.getLifeline(0).addExecution(occ); } fSdView.setFrame(testFrame); } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.uml2sd.handlers.provider.ISDPagingProvider#hasNextPage() */ @Override public boolean hasNextPage() { return page == 0; } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.uml2sd.handlers.provider.ISDPagingProvider#hasPrevPage() */ @Override public boolean hasPrevPage() { return page == 1; } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.uml2sd.handlers.provider.ISDPagingProvider#nextPage() */ @Override public void nextPage() { page = 1; createSecondFrame(); } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.uml2sd.handlers.provider.ISDPagingProvider#prevPage() */ @Override public void prevPage() { page = 0; createFrame(); } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.uml2sd.handlers.provider.ISDPagingProvider#firstPage() */ @Override public void firstPage() { page = 0; createFrame(); } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.uml2sd.handlers.provider.ISDPagingProvider#lastPage() */ @Override public void lastPage() { page = 1; createSecondFrame(); } //... }
When running the example application, new actions will be shown in the coolbar and the coolbar menu.
To use the advanced paging provider, the interface ISDAdvancePagingProvider has to be implemented. It extends the basic paging provider. The methods currentPage(), pagesCount() and pageNumberChanged() have to be added.
Using the Find Provider Interface
For finding nodes in a sequence diagram two interfaces exists. One for basic finding and one for extended finding. The basic find comes with a dialog box for entering find criterias as regular expressions. This find criteria can be used to execute the find. Find criterias a persisted in the Eclipse workspace.
For the extended find provider interface a org.eclipse.jface.action.Action class has to be provided. The actual find handling has to be implemented and triggered by the action.
Only on at a time can be active. If the extended find provder is defined it obsoletes the basic find provider.
To use the basic find provider, first the interface methods of the ISDFindProvider have to be implemented by a class. Typically, this is implemented in the loader class. Add the ISDFindProvider to the list of implemented interfaces, implement the methods find() and cancel() and set the provider in the setViewer() method as well as remove the provider in the dispose() method of the loader class. Please note that the ISDFindProvider extends the interface ISDGraphNodeSupporter which methods (isNodeSupported() and getNodeName()) have to be implemented, too. The following shows an example implementation. Please note that only search for lifelines and SynchMessage are supported. The find itself will always find only the first occurrence the pattern to match.
public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider { //... @Override public void dispose() { if (fSdView != null) { fSdView.resetProviders(); } } @Override public void setViewer(SDView arg0) { fSdView = arg0; fSdView.setSDPagingProvider(this); fSdView.setSDFindProvider(this); createFrame(); } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.uml2sd.handlers.provider.ISDGraphNodeSupporter#isNodeSupported(int) */ @Override public boolean isNodeSupported(int nodeType) { switch (nodeType) { case ISDGraphNodeSupporter.LIFELINE: case ISDGraphNodeSupporter.SYNCMESSAGE: return true; default: break; } return false; } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.uml2sd.handlers.provider.ISDGraphNodeSupporter#getNodeName(int, java.lang.String) */ @Override public String getNodeName(int nodeType, String loaderClassName) { switch (nodeType) { case ISDGraphNodeSupporter.LIFELINE: return "Lifeline"; case ISDGraphNodeSupporter.SYNCMESSAGE: return "Sync Message"; } return ""; } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.uml2sd.handlers.provider.ISDFindProvider#find(org.eclipse.linuxtools.tmf.ui.views.uml2sd.handlers.widgets.Criteria) */ @Override public boolean find(Criteria criteria) { Frame frame = fSdView.getFrame(); if (criteria.isLifeLineSelected()) { for (int i = 0; i < frame.lifeLinesCount(); i++) { if (criteria.matches(frame.getLifeline(i).getName())) { fSdView.getSDWidget().moveTo(frame.getLifeline(i)); return true; } } } if (criteria.isSyncMessageSelected()) { for (int i = 0; i < frame.syncMessageCount(); i++) { if (criteria.matches(frame.getSyncMessage(i).getName())) { fSdView.getSDWidget().moveTo(frame.getSyncMessage(i)); return true; } } } return false; } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.uml2sd.handlers.provider.ISDFindProvider#cancel() */ @Override public void cancel() { // reset find parameters } //... }
When running the example application, the find action will be shown in the coolbar and the coolbar menu.
To find a sequence diagram node press on the find button of the coolbar (see above). A new dialog box will open. Enter a regular expression in the Matching String text box, select the node types (e.g. Sync Message) and press Find. If found the corresponding node will be selected. If not found the dialog box will indicate not found.
Note that the find dialog will be opened by typing the key shortcut CRTL+F.
Using the Filter Provider Interface
For filtering of sequence diagram elements two interfaces exists. One basic for filtering and one for extended filtering. The basic filtering comes with two dialog for entering filter criterias as regular expressions and one for selecting the filter to be used. Multiple filters can be active at a time. Filter criterias are persisted in the Eclipse workspace.
To use the basic filter provider, first the interface method of the ISDFilterProvider has to be implemented by a class. Typically, this is implemented in the loader class. Add the ISDFilterProvider to the list of implemented interfaces, implement the method filter()and set the provider in the setViewer() method as well as remove the provider in the dispose() method of the loader class. Please note that the ISDFindProvider extends the interface ISDGraphNodeSupporter which methods (isNodeSupported() and getNodeName()) have to be implemented, too.
Note that no example implementation of filter() is provided.
public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider { //... @Override public void dispose() { if (fSdView != null) { fSdView.resetProviders(); } } @Override public void setViewer(SDView arg0) { fSdView = arg0; fSdView.setSDPagingProvider(this); fSdView.setSDFindProvider(this); fSdView.setSDFilterProvider(this); createFrame(); } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.uml2sd.handlers.provider.ISDFilterProvider#filter(java.util.List) */ @Override public boolean filter(List<?> list) { return false; } //... }
When running the example application, the filter action will be shown in the coolbar menu.
To filter select the Hide Patterns... of the coolbar menu. A new dialog box will open.
To Add a new filter press Add.... A new dialog box will open. Enter a regular expression in the Matching String text box, select the node types (e.g. Sync Message) and press Create'.
Now back at the Hide Pattern dialog. Select one or more filter and select OK.
To use the extended filter provider, the interface ISDExtendedFilterProvider has to be implemented. It will provide a org.eclipse.jface.action.Action class containing the actual filter handling and filter algorithm.
Using the Extended Action Bar Provider Interface
The extended action bar provider can be used to add customized actions to the Sequence Diagram View.
To use the extended action bar provider, first the interface method of the interface ISDExtendedActionBarProvider has to be implemented by a class. Typically, this is implemented in the loader class. Add the ISDExtendedActionBarProvider to the list of implemented interfaces, implement the method supplementCoolbarContent() and set the provider in the setViewer() method as well as remove the provider in the dispose() method of the loader class.
public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider, ISDExtendedActionBarProvider { //... @Override public void dispose() { if (fSdView != null) { fSdView.resetProviders(); } } @Override public void setViewer(SDView arg0) { fSdView = arg0; fSdView.setSDPagingProvider(this); fSdView.setSDFindProvider(this); fSdView.setSDFilterProvider(this); fSdView.setSDExtendedActionBarProvider(this); createFrame(); } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.uml2sd.handlers.provider.ISDExtendedActionBarProvider#supplementCoolbarContent(org.eclipse.ui.IActionBars) */ @Override public void supplementCoolbarContent(IActionBars iactionbars) { Action action = new Action("Refresh") { @Override public void run() { System.out.println("Refreshing..."); } }; iactionbars.getMenuManager().add(action); iactionbars.getToolBarManager().add(action); } //... }
When running the example application, all new actions will be added to the coolbar and coolbar menu according to the implementation of supplementCoolbarContent()
.
For the example above the coolbar and coolbar menu will look as follows.
Using the Properties Provider Interface
This interface can be used to provide property information. A property provider which returns an IPropertyPageSheet (see org.eclipse.ui.views) has to be implemented and set in the Sequence Diagram View.
To use the property provider, first the interface method of the ISDPropertiesProvider has to be implemented by a class. Typically, this is implemented in the loader class. Add the ISDPropertiesProvider to the list of implemented interfaces, implement the method getPropertySheetEntry() and set the provider in the setViewer() method as well as remove the provider in the dispose() method of the loader class. Please note that no example is provided here.
Please refer to the following Eclipse articles for more information about properties and tabed properties.
Using the Collapse Provider Interface
This interface can be used to define a provider which responsibility is to collapse two selected lifelines. This can be used to hide a pair of lifelines.
To use the collapse provider, first the interface method of the ISDCollapseProvider has to be implemented by a class. Typically, this is implemented in the loader class. Add the ISDCollapseProvider to the list of implemented interfaces, implement the method collapseTwoLifelines() and set the provider in the setViewer() method as well as remove the provider in the dispose() method of the loader class. Please note that no example is provided here.
Using the Selection Provider Service
The Sequence Diagram View comes with a build in selection provider service. To this service listeners can be added. To use the selection provider service, the interface ISelectionListener of plug-in org.eclipse.ui has to implemented. Typically this is implemented in loader class. Firstly, add the ISelectionListener interface to the list of implemented interfaces, implement the method selectionChanged() and set the listener in method setViewer() as well as remove the listener in the dispose() method of the loader class.
public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider, ISDExtendedActionBarProvider, ISelectionListener { //... @Override public void dispose() { if (fSdView != null) { PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().removePostSelectionListener(this); fSdView.resetProviders(); } } @Override public String getTitleString() { return "Sample Diagram"; } @Override public void setViewer(SDView arg0) { fSdView = arg0; PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().addPostSelectionListener(this); fSdView.setSDPagingProvider(this); fSdView.setSDFindProvider(this); fSdView.setSDFilterProvider(this); fSdView.setSDExtendedActionBarProvider(this); createFrame(); } /* * (non-Javadoc) * @see org.eclipse.ui.ISelectionListener#selectionChanged(org.eclipse.ui.IWorkbenchPart, org.eclipse.jface.viewers.ISelection) */ @Override public void selectionChanged(IWorkbenchPart part, ISelection selection) { ISelection sel = PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().getSelection(); if (sel != null && (sel instanceof StructuredSelection)) { StructuredSelection stSel = (StructuredSelection) sel; if (stSel.getFirstElement() instanceof BaseMessage) { BaseMessage syncMsg = ((BaseMessage) stSel.getFirstElement()); System.out.println("Message '" + syncMsg.getName() + "' selected."); } } } //... }
Printing a Sequence Diagram
To print a the whole sequence diagram or only parts of it, select the Sequence Diagram View and select File -> Print... or type the key combination CTRL+P. A new print dialog will open.
Fill in all the relevant information, select Printer... to choose the printer and the press OK.
Using one Sequence Diagram View with Multiple Loaders
A Sequence Diagram View definition can be used with multiple sequence diagram loaders. However, the active loader to be used when opening the view has to be set. For this define an Eclipse action or command and assign the current loader to the view. Here is a code snippet for that:
public class OpenSDView extends AbstractHandler { @Override public Object execute(ExecutionEvent event) throws ExecutionException { 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); } catch (PartInitException e) { throw new ExecutionException("PartInitException caught: ", e); } return null; } }
Download Tutorial
Use the following link to download the source code of the tutorial Plug-in of Tutorial
Integration of Tracing and Monitoring Framework with Sequence Diagram Framework
In the previous sections the Sequence Diagram Framework has been described and a tutorial was provided. In the following sections the integration of the Sequence Diagram Framework with other features of TMF will be described. Together it is a powerful framework to analyze and visualize content of traces. The integration is explained using the reference implementation of a UML2 sequence diagram loader which part of the TMF UI delivery. The reference implementation can be used as is, can be sub-classed or simply be an example for other sequence diagram loaders to be implemented.
Reference Implementation
A Sequence Diagram View Extension is defined in the plug-in TMF UI as well as a uml2SDLoader Extension with the reference loader.
Used Sequence Diagram Features
Besides the default features of the Sequence Diagram Framework, the reference implementation uses the following additional features:
- Advanced paging
- Basic finding
- Basic filtering
- Selection Service
Advanced paging
The reference loader implements the interface ISDAdvancedPagingProvider interface. Please refer to section Using the Paging Provider Interface for more details about the advanced paging feature.
Basic finding
The reference loader implements the interface ISDFindProvider interface. The user can search for Lifelines and Interactions. The find is done across pages. If the expression to match is not on the current page a new thread is started to search on other pages. If expression is found the corresponding page is shown as well as the searched item is displayed. If not found then a message is displayed in the Progress View of Eclipse. Please refer to section Using the Find Provider Interface for more details about the basic find feature.
Basic filtering
The reference loader implements the interface ISDFilterProvider interface. The user can filter on Lifelines and Interactions. Please refer to section Using the Filter Provider Interface for more details about the basic filter feature.
Selection Service
The reference loader implements the interface ISelectionListener interface. When an interaction is selected a TmfTimeSynchSignal is broadcast (see TMF Signal Framework). Please also refer to section Using the Selection Provider Service for more details about the selection service and .
Used TMF Features
The reference implementation uses the following features of TMF:
- TMF Experiment and Trace for accessing traces
- Event Request Framework to request TMF events from the experiment and respective traces
- Signal Framework for broadcasting and receiving TMF signals for synchronization purposes
TMF Experiment and Trace for accessing traces
The reference loader uses TMF Experiments to access traces and to request data from the traces.
TMF Event Request 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 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.
A third type of event request is issued for finding specific data across pages.
TMF Signal Framework
The reference loader extends the class TmfComponent. By doing that the loader is register as TMF signal handler for sending and receiving TMF signals. The loader implements signal handlers for the following TMF signals:
- TmfExperimentSelectedSignal
This signal indicates that a Experiment was selected. When receiving this signal the indexing request is initiated and the first page is displayed after receiving the relevant information.
- TmfExperimentDisposedSignal
This signal indicates that a Experiment was disposed. When receiving this signal the loader resets its data and a blank page is loaded in the Sequence Diagram View.
- TmfTimeSynchSignal
This signal indicates that a event with a certain time stamp is selected. When receiving this signal the corresponding message is selected in the Sequence Diagram View. If necessary, the page is changed.
- TmfRangeSynchSignal
This signal indicates that a new time range is in focus. When receiving this signal the loader loads the page which corresponds to the start time of the time range signal. The message with the start time will be in focus.
Besides acting on receiving signals, the reference loader is also sending signals. A TmfTimeSynchSignal is broadcasted with the time stamp of the message which was selected in the Sequence Diagram View. TmfRangeSynchSignal is sent when a page is changed in the Sequence Diagram View. The start timestamp of the time range sent is the timestamp of the first message. The end timestamp sent is the timestamp of the first message plus the current time range window. The current time range window is the time window that was indicated in the last received TmfRangeSynchSignal.
Supported Traces
The reference implementation is able to analyze traces from a single component that traces the interaction between other components. For example, a server node could have trace information about its interaction with client nodes. The server node could be traced and then analyzed using TMF and the Sequence Diagram Framework of TMF could used to visualize the interactions with the client nodes.
Note that combined traces of multiple component, that contain the trace information about the same interactions are not supported in the reference implementation!
Trace Format
The reference implementation in class TmfUml2SDSyncLoader in package org.eclipse.linuxtools.tmf.ui.views.uml2sd.implanalyzes events from type TmfEvent and creates events type ITmfSyncSequenceDiagramEvent if the TmfEvent contains all relevant information information. The parsing algorithm looks like as follows:
/** * @param tmfEvent Event to parse for sequence diagram event details * @return sequence diagram event if details are available else null */ protected ITmfSyncSequenceDiagramEvent getSequnceDiagramEvent(TmfEvent tmfEvent){ //type = .*RECEIVE.* or .*SEND.* //content = sender:<sender name>:receiver:<receiver name>,signal:<signal name> String eventType = tmfEvent.getType().toString(); if (eventType.contains(Messages.TmfUml2SDSyncCloader_EventTypeSend) || eventType.contains(Messages.TmfUml2SDSyncCloader_EventTypeReceive)) { try { Object sender = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncCloader_FieldSender); Object receiver = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncCloader_FieldReceiver); Object name = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncCloader_FieldSignal); if ((sender instanceof TmfEventField) && (receiver instanceof TmfEventField) && (name instanceof TmfEventField)) { ITmfSyncSequenceDiagramEvent sdEvent = new TmfSyncSequenceDiagramEvent(tmfEvent, ((TmfEventField)sender).getValue().toString(), ((TmfEventField)receiver).getValue().toString(), ((TmfEventField)name).getValue().toString()); return sdEvent; } } catch (TmfNoSuchFieldException e) { } } return null; }
The analysis looks for event type Strings containing SEND and RECEIVE. If event type matches this key works, the analyzer will look for strings sender, receiver and signal in the event fields of type TmfEventField. If all the data is found a sequence diagram event from can be created. Note that Sync Messages are assumed, which means start and end time are the same.
How to use the Reference Implementation
An example trace visualizer is provided that uses a trace in binary format. It contains trace events with sequence diagram information. To parse the data using TMF a class is provided that implements ITmfTrace. Additionally, a parser is provided that reads from the file and converts a trace event to TmfEvent. This parser implements the interface ITmfEventParser. To get the source code see Download Reference Plug-in
The plug-in structure will look like this:
To open the plug-in manifest, double-click on the MANIFEST.MF file.
Run the Reference Application. To launch the Eclipse Application select the Overview tab and click on Launch an Eclipse Application
To open the Reference Sequence Diagram View, select Windows -> Show View -> Other... -> TMF -> Sequence Diagram
An blank Sequence Diagram View will open. Open also the TMF Events View by selecting Windows -> Show View -> Other... -> TMF -> Events
Select the Select Experiment button of the toolbar to load the sequence diagram from the data provided in the trace file. What this does is open the file tracesets/sdEvents, parse this file through TMF and analyze all events of type TmfEvent and generates the Sequence Digram out of it.
Now the reference application can be explored. To demonstrate the view features try the following things:
- Select a message in the Sequence diagram. As result the corresponding event will be selected in the Events View.
- Select an event in the Events View. As result the corresponding message in the Sequence Diagram View will be selected. If necessary, the page will be changed.
- In the Events View, press key End. As result, the Sequence Diagram view will jump to the last page.
- In the Events View, press key Home. As result, the Sequence Diagram view will jump to the first page.
- In the Sequence Diagram View select the find button. Enter the expression REGISTER.*, select Search for Interaction and press Find. As result the corresponding message will be selected in the Sequence Diagram and the corresponding event in the Events View will be selected. Select again Find the next occurrence of will be selected. Since the second occurrence is on a different page than the first, the corresponding page will be loaded.
- In the Sequence Diagram View, select menu item Hide Patterns.... Add the filter BALL.* for Interaction only and select OK. As result all messages with name BALL_REQUEST and BALL_REPLY will be hidden. To remove the filter, select menu item Hide Patterns..., deselect the corresponding filter and press OK. All the messages will be shown again.
To dispose the diagram, select the Dispose Experiment button of the toolbar. The current sequence diagram will be disposed and an empty diagram will be loaded.
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.
Download Reference Plug-in
To download the reference plug-in that demonstrates the reference loader, use the following link: Reference Plug-in. Just extract the zip file and import the extracted Eclipse plug-in (plug-in name: org.eclipse.linuxtools.tmf.reference.ui) to your Eclipse workspace.
TMF Statistic Framework
TMF provides a framework for displaying and collection trace specific statistics. By default, the generic statistics view displays the number events per event type and per trace. The design can be easily extended to display other types of statistics depending on the application. This following section will describe the default TMF Statistics View and it's usage. Subsequent sections will be explain how to extend the framework for other types of statistics.
Default TMF Statistics View
To open the TMF Statistics View, select Windows -> Show View -> Other... -> Tracing -> TMF Statistics A new view will open with the name TMF Statistics. This view shows 2 columns Level and Number of Events. After parsing a trace the view will display the number of events per event type. The cell where the number of events are printed also contain a coloured bar that indicates the percentage of the event count in relation to the total number of events. The statistics ic collected for the whole trace. The example below shows the statistics for an TMF experiment with 2 LTTng traces in it.
Extending the TMF Statistic Framework
To create customized Statistics View several class implementations have to be provided.
- Statistics Data Model
- Column Data Provider
- Statistics View Implementation
Statistics Data Model
First of all a data model has to be created. The TMF statistics model is based on tree. Each node can be reached by a path implmented by an array of strings (class org.eclipse.linuxtools.tmf.util.TmfFixedArray). The software designer has the choice to extend the abstract class org.eclipse.linuxtools.tmf.ui.views.statistics.model.AbsTmfStatisticsTree or to extend a basic implementation of AbsTmfStatisticsTree with the name org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsTree.
Depending on the application and types of statistic, the following methods need to be considered for overwriting:
- protected TmfFixedArray<String>[] getNormalPaths(TmfEvent event, ITmfExtraEventInfo extraInfo);
- protected TmfFixedArray<String>[] getTypePaths(TmfEvent event, ITmfExtraEventInfo extraInfo);
- protected abstract void registerName(final TmfFixedArray<String> path);
- public abstract Collection<TmfStatisticsTreeNode> getChildren(final TmfFixedArray<String> path);
- public abstract Collection<TmfStatisticsTreeNode> getAllChildren(final TmfFixedArray<String> path);
- public abstract void increase(TmfEvent event, ITmfExtraEventInfo extraInfo, int values);
- public abstract void registerEvent(TmfEvent event, ITmfExtraEventInfo extraInfo);
If other statistic types than number of events have to be counted the designer has to extend the TmfStatistics class and add other statistics. Such other statistic could be for example elapsed time or latency. To be able to use this subclass the designer has to extend class TmfStatisticsTreeNode. The constructor will have to instantiate the new TmfStatistics class and save it in the member fValue. All other classes below will have to use these new classes to display the addtional statistics.
Column Data Provider
For that the designer has the choise of implementing the interface org.eclipse.linuxtools.tmf.ui.views.statistics.model.ITmfColumnDataProvider or extend the base implementation org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider. This implementation defines the columns of the statistics tree in the view. The TmfBaseColumnDataProvider can be used if only the event types need to be counted on different levels.
If other statistics types than number of events have to be counted the designer has to make sure that the column provider uses the class that extends TmfStatistics.
Statistics View Implementation
The provided TMF Statistic View implementation takes a data model from type AbsTmfStatisticsTree and uses the column data provider that implements the interface ITmfColumnDataProvider to display statistics in a tree structure. The view also requests data from the trace and feeds it to the model. By default it uses the base model TmfBaseStatisticsTree and the TmfBaseColumnDataProvider. To change this the designer has to overwrite the following methods to provide their own implementation.
- protected AbsTmfStatisticsTree getStatisticData();
- protected ITmfColumnDataProvider getColumnDataProvider();
- protected void requestData(final TmfExperiment<?> experiment, TmfTimeRange timeRange);
If other statistic than number of events have to be counted the designer has to implement the retrieval and analysis of events from the trace. For that, the designer might have to overwrite the method below, implement it's own TmfDataRequest, parse each event and feed that event along with ITmfExtraEventInfo to the data model (see Statistics Data Model for more details about the data model).
- protected void requestData(final TmfExperiment<?> experiment, TmfTimeRange timeRange);
Tutorials
This section provides two tutorials to explain how to extend the TMF statistics framework for other statistics than the default statistics. Tutorial 1 explains how to add new levels for counting event types. The second tutorial explains how to add new columns of statistics. The example source code depends on the LTTng feature including TMF of the Eclipse's Linux Tools project.
Tutorial 1: Adding a New Statistics Level
This tutorial explains how to add new levels (e.g. process level, CPU level) for counting event types. The LTTng example used will also count event types per CPU ID.
Creating an Eclipse Plug-in for Statistics
A new Eclipse plug-in will be used for the new statistics view. Please refer to section Creating an Eclipse UI Plug-in for how to create an Eclipse Plug-in. Now create a plug-in with the name org.eclipse.linuxtools.ust.sample.ui.
To be able to use the TMF Statistics, the new plug-in requires the plug-in org.eclipse.linuxtools.tmf.ui and org.eclipse.linuxtools.tmf.core. See chapter Creating a Sequence Diagram View for how to add plug-dependencies. For this tutorial also add org.eclipse.linuxtools.lttng.core as plug-in dependency.
Creating a Customized Statistics Data Model
Next we need to extend the statistics data model and data providers based on existing base class in TMF.
Firstly, create a new package with name model. To create a new package, select java org.eclipse.linuxtools.ust.sample.ui in the package explorer, then select File->New->Package. An new dialog box will open for the creation of a package. Fill in the relevant data and press Finish.
To create a new model class, select org.eclipse.linuxtools.ust.sample.ui.model in the package explorer, then select File->New->Class. An new dialog box will open for the creation of a class. Fill in the Name and Superclass and press Finish.
A new Java class will be created with the name org.eclipse.linuxtools.ust.sample.ui.statistics.CustomStatisticsModel.
package org.eclipse.linuxtools.ust.sample.ui.model; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsTree; public class CustomStatisticsModel extends TmfBaseStatisticsTree { }
The new class have to be filled. The CustomStatisticsModel extends TmfBaseStatisticsTree, which extends the abstract class AbsTmfStatisticsTree. The base class provides base implementations for abstract methods. Depending on the application these methods need to overwritten.
For this example change the CustomStatisticsModel as follows:
package org.eclipse.linuxtools.ust.sample.ui.model; import java.util.ArrayList; import java.util.Arrays; import java.util.HashSet; import java.util.List; import java.util.Map; import java.util.Set; import org.eclipse.linuxtools.lttng.event.LttngEvent; import org.eclipse.linuxtools.tmf.event.TmfEvent; import org.eclipse.linuxtools.tmf.ui.views.statistics.ITmfExtraEventInfo; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsTree; import org.eclipse.linuxtools.tmf.util.TmfFixedArray; public class CustomStatisticsModel extends TmfBaseStatisticsTree { /** * <h4>Header for the event types categories.</h4> */ protected static final String HEADER_CPUS = "CPUs"; //$NON-NLS-1$ /** * Construct a UST statistics tree. * Add the CPU category to the base statistics tree from TmfBaseStatisticsData */ public CustomStatisticsModel() { super(); Map<String, Set<String>> keys = getKeys(); // //////////// Adding category sets keys.put(HEADER_CPUS, new HashSet<String>()); // /////////// Adding value sets // Under a trace // Add the CPU category to the root node Set<String> temp = keys.get(ROOT_NODE_KEY); if (temp == null) { temp = new HashSet<String>(); } temp.add(HEADER_CPUS); keys.put(ROOT_NODE_KEY, temp); // Under a CPU temp = new HashSet<String>(4); temp.add(HEADER_EVENT_TYPES); keys.put(mergeString(HEADER_CPUS, NODE), temp); } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsData#getNormalPaths(org.eclipse.linuxtools.tmf.event.TmfEvent, * org.eclipse.linuxtools.tmf.ui.views.statistics.ITmfEventInfo) */ @Override @SuppressWarnings("unchecked") protected TmfFixedArray<String>[] getNormalPaths(TmfEvent event, ITmfExtraEventInfo extraInfo) { String trace = extraInfo.getTraceName(); LttngEvent lttngEvent = (LttngEvent) event; String cpus = String.valueOf(lttngEvent.getCpuId()); List<TmfFixedArray<String>> paths = new ArrayList<TmfFixedArray<String>>(Arrays.asList(super.getNormalPaths(event, extraInfo))); paths.add(new TmfFixedArray<String>(trace, HEADER_CPUS, cpus)); return paths.toArray(new TmfFixedArray[0]); } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsData#getTypePaths(org.eclipse.linuxtools.tmf.event.TmfEvent, * org.eclipse.linuxtools.tmf.ui.views.statistics.ITmfEventInfo) */ @Override @SuppressWarnings("unchecked") protected TmfFixedArray<String>[] getTypePaths(TmfEvent event, ITmfExtraEventInfo extraInfo) { String trace = extraInfo.getTraceName(); LttngEvent lttngEvent = (LttngEvent) event; String cpus = String.valueOf(lttngEvent.getCpuId()); List<TmfFixedArray<String>> paths = new ArrayList<TmfFixedArray<String>>(Arrays.asList(super.getTypePaths(event, extraInfo))); String type = event.getType().toString(); paths.add(new TmfFixedArray<String>(trace, HEADER_CPUS, cpus, HEADER_EVENT_TYPES, type)); return paths.toArray(new TmfFixedArray[0]); } }
Creating a Customized Column Data Provider
A column provider for the tree viewer of the Statistics View is needed. Create a new class (as described above) with Name CustomColumnDataProvider and Superclass org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider.
A new Java class will be created with the name org.eclipse.linuxtools.ust.sample.ui.statistics.model.CustomColumnDataProvider.
package org.eclipse.linuxtools.ust.sample.ui.model; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider; public class CustomColumnDataProvider extends TmfBaseColumnDataProvider { }
The CustomColumnDataProvider extends TmfBaseColumnDataProvider, which implements the interface ITmfColumnDataProvider. The base class provides base implementations for the interface. Depending on the application the methods need to overwritten. For this example change the CustomColumnDataProvider as follows:
package org.eclipse.linuxtools.ust.sample.ui.model; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider; public class CustomColumnDataProvider extends TmfBaseColumnDataProvider { public CustomColumnDataProvider() { super(); fFolderLevels.add(CustomStatisticsModel.HEADER_CPUS); } }
Creating a Customized Statistics View
In the MANIFEST.MF file, 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.
A new view entry has been created. Fill in the fields id, name and class.
To create the view class, press on the label class. A new dialog box will open for the creation of the statistics class. This class will extend the basic view implementation TmfStatisticsView. Fill in Name and Superclass
and press Finish.
A new Java class will be created with the name org.eclipse.linuxtools.ust.sample.ui.statistics.CustomStatisticsView.
package org.eclipse.linuxtools.ust.sample.ui; import org.eclipse.linuxtools.tmf.ui.views.statistics.TmfStatisticsView; public class CustomStatisticsView extends TmfStatisticsView { public CustomStatisticsView(String viewName) { super(viewName); // TODO Auto-generated constructor stub } public CustomStatisticsView() { // TODO Auto-generated constructor stub } }
At last, implement the class CustomStatisticsView which extends TmfStatisticsView. Depending on the application certain methods need to overwritten. For this example change the CustomStatisticsView as follows:
package org.eclipse.linuxtools.ust.sample.ui; import org.eclipse.linuxtools.tmf.ui.views.statistics.TmfStatisticsView; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.AbsTmfStatisticsTree; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.ITmfColumnDataProvider; import org.eclipse.linuxtools.ust.sample.ui.model.CustomColumnDataProvider; import org.eclipse.linuxtools.ust.sample.ui.model.CustomStatisticsModel; public class CustomStatisticsView extends TmfStatisticsView { /** * The ID correspond to the package in which this class is embedded */ public static final String ID = "org.eclipse.linuxtools.lttng.ui.views.ustStatistics"; //$NON-NLS-1$ /** * Constructor of a statistics view. * * @param viewName * The name to give to the view. */ public CustomStatisticsView(String viewName) { super(viewName); } private static final String UST_STATISTICS_VIEW = "USTStatisticsView"; //$NON-NLS-1$ /** * Default constructor. */ public CustomStatisticsView() { this(UST_STATISTICS_VIEW); } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.statistics.TmfStatisticsView#getStatisticData() */ @Override protected AbsTmfStatisticsTree getStatisticData() { return new CustomStatisticsModel(); } /* * (non-Javadoc) * @see org.eclipse.linuxtools.tmf.ui.views.statistics.TmfStatisticsView#getColumnDataProvider() */ @Override protected ITmfColumnDataProvider getColumnDataProvider() { return new CustomColumnDataProvider(); }
Running the Eclipse Application
Now it's time to run the example application. To launch the Example Application select the Overview tab of the MANIFEST.MF file and click on Launch an Eclipse Application. A new Eclipse application window will be shown. In the new window go to Windows -> Show View -> Other... -> Other -> Custom Statistics View. A new view will open. After parsing a trace the view will display the number of events per event type as well as the number of events per CPU and event type. For an example trace the output looks as follows:
Downloading the tutorial
Use the following link to download the source code of the tutorial: Plug-in of Statistics Tutorial
Tutorial 2: Adding new Statistic Types
This tutorial will describe how to extend the TMF statistics to support other event types. In addition to the number of events this statistics implementation will provide the longest latency in nano seconds. The latency is the time spent between two related events, a start event and an end event. The latency will be shown at the level of the end event. In the example below no analysis is implemented. The LatencyCalculator class just generates random numbers for certain events.
Create an Eclipse plug-in with name org.eclipse.linuxtools.ust.sample2.ui as described in Creating an Eclipse UI Plug-in. Also create a model package with name org.eclipse.linuxtools.ust.sample2.ui.statistics.model as described in Creating a Customized Statistics Data Model.
Implementing a Customized Statistics Data Model
Firstly, add the LatencyCalculator class. Under package org.eclipse.linuxtools.ust.sample2.ui.statistics.model, create a new class (as described above) with Name LatencyCalculator. Add the following implementation:
package org.eclipse.linuxtools.ust.sample2.ui.model; import org.eclipse.linuxtools.lttng.event.LttngEvent; public class LatencyCalculator { private final long fMin = 400; private final long fMax = 20000000; /** * Dummy implementation */ public void initialize() { } /** * Dummy implementation that returns random latency values for certain event types. * * @param event * @return latency or -1 */ @SuppressWarnings("nls") public long calculate (LttngEvent event) { String markerName = event.getMarkerName(); if (markerName.equals("syscall_exit") || markerName.equals("softirq_exit") || markerName.equals("close") || markerName.equals("process_exit")) { long random = fMin + (int)(Math.random() * ((fMax - fMin) + 1)); return random; } return -1; } }
Next, we need a new class that holds the new counter and that extends TmfStatistics. Under package org.eclipse.linuxtools.ust.sample2.ui.statistics.model, create a new class (as described above) with Name NewStatistics and Superclass org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatistics. A new Java class will be created with the name org.eclipse.linuxtools.ust.sample2.ui.statistics.model.NewStatistics.
package org.eclipse.linuxtools.ust.sample2.ui.model; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatistics; public class NewStatistics extends TmfStatistics { }
Add the latency statistics to this class.
package org.eclipse.linuxtools.ust.sample2.ui.model; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatistics; public class NewStatistics extends TmfStatistics { public long latency = 0; }
Next step is it to extend the class TmfStatisticsTreeNode so that the class NewStatistics is used instead of the base type.
Under package org.eclipse.linuxtools.ust.sample2.ui.statistics.model, create a new class (as described above) with Name NewStatisticsTreeNode and Superclass org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatisticsTreeNode. A new Java class will be created with the name org.eclipse.linuxtools.ust.sample2.ui.statistics.model.NewStatisticsTreeNode.
package org.eclipse.linuxtools.ust.sample2.ui.model; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.AbsTmfStatisticsTree; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatisticsTreeNode; import org.eclipse.linuxtools.tmf.util.TmfFixedArray; public class NewStatisticsTreeNode extends TmfStatisticsTreeNode { public NewStatisticsTreeNode(TmfFixedArray<String> path, AbsTmfStatisticsTree nodes) { super(path, nodes); // TODO Auto-generated constructor stub }
Now we need to update the code to use and instantiate CustomStatistics instead of TmfStatistics.
package org.eclipse.linuxtools.ust.sample2.ui.model; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.AbsTmfStatisticsTree; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatisticsTreeNode; import org.eclipse.linuxtools.tmf.util.TmfFixedArray; public class NewStatisticsTreeNode extends TmfStatisticsTreeNode { public NewStatisticsTreeNode(TmfFixedArray<String> path, AbsTmfStatisticsTree nodes) { super(path, nodes); fValue = new NewStatistics(); } @Override public void reset() { super.reset(); fValue = new NewStatistics(); } } Next, create the statistics model class which extends ''TmfBaseStatisticsTree''. Under package ''org.eclipse.linuxtools.ust.sample2.ui.statistics.model'', create a new class (as described above) with ''Name'' NewStatisticsModel and ''Superclass'' ''org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsTree''. A new Java class will be created with the name ''org.eclipse.linuxtools.ust.sample2.ui.statistics.model.NewStatisticsModel''.<br> <code> <pre> package org.eclipse.linuxtools.ust.sample2.ui.model; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsTree; public class NewStatisticsModel extends TmfBaseStatisticsTree { }
Now we have to override certain method to use the new statistics class NewStatistics and to count the latency.
package org.eclipse.linuxtools.ust.sample2.ui.model; import org.eclipse.linuxtools.lttng.event.LttngEvent; import org.eclipse.linuxtools.tmf.event.TmfEvent; import org.eclipse.linuxtools.tmf.ui.views.statistics.ITmfExtraEventInfo; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseStatisticsTree; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatistics; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatisticsTreeNode; import org.eclipse.linuxtools.tmf.util.TmfFixedArray; public class NewStatisticsModel extends TmfBaseStatisticsTree { private LatencyCalculator fLatencyCalulator; public NewStatisticsModel() { super(); fLatencyCalulator = new LatencyCalculator(); fLatencyCalulator.initialize(); } @Override public void increase(TmfEvent event, ITmfExtraEventInfo extraInfo, int values) { if (event instanceof LttngEvent) { long latency = fLatencyCalulator.calculate((LttngEvent)event); if (latency >= 0) { TmfFixedArray<String>[] paths = getNormalPaths(event, extraInfo); for (TmfFixedArray<String> path : paths) { TmfStatistics current = getOrCreate(path).getValue(); if (current instanceof NewStatistics) { ((NewStatistics)current).latency = Math.max(((NewStatistics)current).latency, latency); } } paths = getTypePaths(event, extraInfo); for (TmfFixedArray<String> path : paths) { TmfStatistics current = getOrCreate(path).getValue(); if (current instanceof NewStatistics) { ((NewStatistics)current).latency = Math.max(((NewStatistics)current).latency, latency); } } } } else { return; } } @Override public TmfStatisticsTreeNode getOrCreate(final TmfFixedArray<String> path) { TmfStatisticsTreeNode current = fNodes.get(path); if (current == null) { registerName(path); current = new NewStatisticsTreeNode(path, this); fNodes.put(path, current); } return current; } @Override public void reset(final TmfFixedArray<String> path) { super.reset(path); fLatencyCalulator.initialize(); } }
Implementing a Customized Column Data Provider
A column provider for the tree viewer of the Statistics View is needed. Create a new class (as described above) with Name NewColumnDataProvider and Superclass org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider.
A new Java class will be created with the name org.eclipse.linuxtools.ust.sample2.ui.statistics.model.NewColumnDataProvider.
package org.eclipse.linuxtools.ust.sample2.ui.model; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider; public class NewColumnDataProvider extends TmfBaseColumnDataProvider { }
The NewColumnDataProvider extends TmfBaseColumnDataProvider, which implements the interface ITmfColumnDataProvider. An new column has to be created by adding a TmfBaseColumnData to the ColumnData list. For this example change the NewColumnDataProvider as follows:
package org.eclipse.linuxtools.ust.sample2.ui.model; import org.eclipse.jface.viewers.ColumnLabelProvider; import org.eclipse.jface.viewers.Viewer; import org.eclipse.jface.viewers.ViewerComparator; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnData; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfBaseColumnDataProvider; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatistics; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.TmfStatisticsTreeNode; import org.eclipse.swt.SWT; public class NewStatisticsColumnDataProvider extends TmfBaseColumnDataProvider { protected final static String TIME_COUNT_COLUMN = "Longest Latency"; //$NON-NLS-1$ protected final static String TIME_COLUMN_TIP = "Longest Latency for give start event"; //$NON-NLS-1$ public NewStatisticsColumnDataProvider() { super(); fColumnData.add(new TmfBaseColumnData(TIME_COUNT_COLUMN, 125, SWT.LEFT, TIME_COLUMN_TIP, new ColumnLabelProvider() { @Override public String getText(Object element) { TmfStatisticsTreeNode node = (TmfStatisticsTreeNode) element; if (!fFolderLevels.contains(node.getKey())) { TmfStatistics value = node.getValue(); if (value instanceof NewStatistics) { long longValue = ((NewStatistics)node.getValue()).latency; if (longValue != 0) { return String.valueOf(longValue); } return ""; //$NON-NLS-1$ } } return ""; //$NON-NLS-1$ } }, new ViewerComparator() { @Override public int compare(Viewer viewer, Object e1, Object e2) { TmfStatisticsTreeNode n1 = (TmfStatisticsTreeNode) e1; TmfStatisticsTreeNode n2 = (TmfStatisticsTreeNode) e2; TmfStatistics value1 = n1.getValue(); TmfStatistics value2 = n2.getValue(); if (value1 instanceof NewStatistics && value2 instanceof NewStatistics) { return (int) (((NewStatistics) value1).latency - ((NewStatistics) value2).latency); } return 0; } }, null)); // null to indicate that there isn't a percentage provider } }
Implementing a Customized Statistics View
Add a new Eclipse view with the view name New Statistics View and a view class with name NewStatisticsView that extends TmfStatisticsView as described in section Creating a Customized Statistics View.
A new Java class will be created with the name org.eclipse.linuxtools.ust.sample.ui.statistics.NewStatisticsView.
package org.eclipse.linuxtools.ust.sample2.ui; import org.eclipse.linuxtools.tmf.ui.views.statistics.TmfStatisticsView; public class NewStatisticsView extends TmfStatisticsView { public CustomStatisticsView(String viewName) { super(viewName); // TODO Auto-generated constructor stub } public CustomStatisticsView() { // TODO Auto-generated constructor stub } }
At last, override all relevant methods as shown below:
package org.eclipse.linuxtools.ust.sample2.ui; import org.eclipse.linuxtools.tmf.event.TmfTimeRange; import org.eclipse.linuxtools.tmf.experiment.TmfExperiment; import org.eclipse.linuxtools.tmf.ui.views.statistics.TmfStatisticsView; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.AbsTmfStatisticsTree; import org.eclipse.linuxtools.tmf.ui.views.statistics.model.ITmfColumnDataProvider; import org.eclipse.linuxtools.ust.sample2.ui.model.NewStatisticsColumnDataProvider; import org.eclipse.linuxtools.ust.sample2.ui.model.NewStatisticsModel; public class NewStatisticsView extends TmfStatisticsView { public NewStatisticsView(String viewName) { super(viewName); } public NewStatisticsView() { } @Override protected AbsTmfStatisticsTree getStatisticData() { return new NewStatisticsModel(); } @Override protected ITmfColumnDataProvider getColumnDataProvider() { return new NewStatisticsColumnDataProvider(); } @Override protected void requestData(final TmfExperiment<?> experiment, TmfTimeRange timeRange) { // do some initialization super.requestData(experiment, timeRange); } }
Running the Eclipse Application
Now it's time to run the example application. To launch the Example Application select the Overview tab of the MANIFEST.MF file and click on Launch an Eclipse Application. A new Eclipse application window will be shown. In the new window go to Windows -> Show View -> Other... -> Other -> New Statistics View. A new view will open. After parsing a trace the view will display the number of events per event type and longest latency were it is applicable. On the trace level the longest latency of all latencies is shown as well. For an example trace the output looks as follows:
Downloading the tutorial
Use the following link to download the source code of the tutorial: Plug-in of Statistics Tutorial