8 The purpose of '''Trace Compass''' is to facilitate the integration of tracing
9 and monitoring tools into Eclipse, to provide out-of-the-box generic
10 functionalities/views and provide extension mechanisms of the base
11 functionalities for application specific purposes.
13 This guide goes over the internal components of the Trace Compass framework. It
14 should help developers trying to add new capabilities (support for new trace
15 type, new analysis or views, etc.) to the framework. End-users, using the RCP
16 for example, should not have to worry about the concepts explained here.
18 = Implementing a New Trace Type =
20 The framework can easily be extended to support more trace types. To make a new
21 trace type, one must define the following items:
27 * The ''org.eclipse.linuxtools.tmf.core.tracetype'' plug-in extension point
28 * (Optional) The ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension point
30 The '''event type''' must implement an ''ITmfEvent'' or extend a class that
31 implements an ''ITmfEvent''. Typically it will extend ''TmfEvent''. The event
32 type must contain all the data of an event.
34 The '''trace type''' must be of an ''ITmfTrace'' type. The ''TmfTrace'' class
35 will supply many background operations so that the reader only needs to
36 implement certain functions. This includes the ''event aspects'' for events of
37 this trace type. See the section below.
39 The '''trace context''' can be seen as the internals of an iterator. It is
40 required by the trace reader to parse events as it iterates the trace and to
41 keep track of its rank and location. It can have a timestamp, a rank, a file
42 position, or any other element, it should be considered to be ephemeral.
44 The '''trace location''' is an element that is cloned often to store
45 checkpoints, it is generally persistent. It is used to rebuild a context,
46 therefore, it needs to contain enough information to unambiguously point to one
47 and only one event. Finally the ''tracetype'' plug-in extension associates a
48 given trace, non-programmatically to a trace type for use in the UI.
52 In Trace Compass, an ''event aspect'' represents any type of information that
53 can be extracted from a trace event. The simple case is information that is
54 present directly in the event. For example, the timestamp of an event, a field
55 of an LTTng event, or the "payload" that is on the same line of a text trace
56 entry. But it could also be the result of an indirect operation, for example a
57 state system query at the timestamp of the given event (see the section
58 [[#Generic State System]]).
60 All aspects should implement the '''ITmfEventAspect''' interface. The important
61 method in there is ''resolve(ITmfEvent)'', which tells this aspect what to
62 output for a given event. The singleton pattern fits well for pre-defined aspect
65 The aspects defined for a trace type determine the initial columns in the Event
66 Table, as well as the elements on which the trace can be filtered, among other
69 === Base and custom aspects ===
71 Some base aspects are defined in '''TmfTrace#BASE_ASPECTS'''. They use generic
72 methods found in '''ITmfEvent''', so they should be applicable for any event
73 type defined in the framework. If one does not override
74 '''TmfTrace#getEventAspects''', then only the base aspects will be used with
77 Overriding the method does not append to this list, it replaces it. So if you
78 wish to define additional aspects for a new trace type, do not forget to include
79 the BASE_ASPECTS you want to use, if any, within the list.
81 The order of the elements in the returned ''Iterable'' may matter to other
82 components. For instance, the initial ordering of the columns in the Events
85 Defining additional aspects allows to expose more data from the trace events
86 without having to update all the views using the aspects API.
88 === Creating event aspects programmatically ===
90 Another advantage of event aspects is that they can be created programmatically,
91 without having to modify the base trace or event classes. A new analysis
92 applying to a pre-existing trace type may wish to define additional aspects to
95 While the notion of event aspects should not be exposed to users directly, it is
96 possible to create new aspects based on user input. For example, an "event
97 field" dialog could ask the user to enter a field name, which would then create
98 an aspect that would look for the value of a field with this name in every
99 event. The user could then be able to display or filter on this aspect.
101 == Optional Trace Type Attributes ==
103 After defining the trace type as described in the previous chapters it is
104 possible to define optional attributes for the trace type.
106 === Default Editor ===
108 The '''defaultEditor''' attribute of the '''org.eclipse.linuxtools.tmf.ui.tracetypeui'''
109 extension point allows for configuring the editor to use for displaying the
110 events. If omitted, the ''TmfEventsEditor'' is used as default.
112 To configure an editor, first add the '''defaultEditor''' attribute to the trace
113 type in the extension definition. This can be done by selecting the trace type
114 in the plug-in manifest editor. Then click the right mouse button and select
115 '''New -> defaultEditor''' in the context sensitive menu. Then select the newly
116 added attribute. Now you can specify the editor id to use on the right side of
117 the manifest editor. For example, this attribute could be used to implement an
118 extension of the class ''org.eclipse.ui.part.MultiPageEditor''. The first page
119 could use the ''TmfEventsEditor''' to display the events in a table as usual and
120 other pages can display other aspects of the trace.
122 === Events Table Type ===
124 The '''eventsTableType''' attribute of the '''org.eclipse.linuxtools.tmf.ui.tracetypeui'''
125 extension point allows for configuring the events table class to use in the
126 default events editor. If omitted, the default events table will be used.
128 To configure a trace type specific events table, first add the
129 '''eventsTableType''' attribute to the trace type in the extension definition.
130 This can be done by selecting the trace type in the plug-in manifest editor.
131 Then click the right mouse button and select '''New -> eventsTableType''' in the
132 context sensitive menu. Then select the newly added attribute and click on
133 ''class'' on the right side of the manifest editor. The new class wizard will
134 open. The ''superclass'' field will be already filled with the class ''org.eclipse.tracecompass.tmf.ui.viewers.events.TmfEventsTable''.
136 By using this attribute, a table with different columns than the default columns
137 can be defined. See the class
138 ''org.eclipse.tracecompass.internal.gdbtrace.ui.views.events.GdbEventsTable''
139 for an example implementation.
141 == Other Considerations ==
143 Other views and components may provide additional features that are active only
144 when the event or trace type class implements certain additional interfaces.
146 === Collapsing of repetitive events ===
148 By implementing the interface
149 ''org.eclipse.tracecompass.tmf.core.event.collapse.ITmfCollapsibleEvent'' the
150 event table will allow to collapse repetitive events by selecting the menu item
151 '''Collapse Events''' after pressing the right mouse button in the table.
155 * Do not load the whole trace in RAM, it will limit the size of the trace that can be read.
156 * Reuse as much code as possible, it makes the trace format much easier to maintain.
157 * Use Eclipse's editor instead of editing the XML directly.
158 * Do not forget Java supports only signed data types, there may be special care needed to handle unsigned data.
159 * If the support for your trace has custom UI elements (like icons, views, etc.), split the core and UI parts in separate plugins, named identically except for a ''.core'' or ''.ui'' suffix.
160 ** Implement the ''tmf.core.tracetype'' extension in the core plugin, and the ''tmf.ui.tracetypeui'' extension in the UI plugin if applicable.
162 == An Example: Nexus-lite parser ==
164 === Description of the file ===
166 This is a very small subset of the nexus trace format, with some changes to make
167 it easier to read. There is one file. This file starts with 64 Strings
168 containing the event names, then an arbitrarily large number of events. The
169 events are each 64 bits long. the first 32 are the timestamp in microseconds,
170 the second 32 are split into 6 bits for the event type, and 26 for the data
173 The trace type will be made of two parts, part 1 is the event description, it is
174 just 64 strings, comma separated and then a line feed.
177 Startup,Stop,Load,Add, ... ,reserved\n
180 Then there will be the events in this format
183 |style="width: 50%; background-color: #ffffcc;"|timestamp (32 bits)
184 |style="width: 10%; background-color: #ffccff;"|type (6 bits)
185 |style="width: 40%; background-color: #ccffcc;"|payload (26 bits)
187 |style="background-color: #ffcccc;" colspan="3"|64 bits total
190 all events will be the same size (64 bits).
192 === NexusLite Plug-in ===
194 Create a '''New''', '''Project...''', '''Plug-in Project''', set the title to
195 '''com.example.nexuslite''', click '''Next >''' then click on '''Finish'''.
197 Now the structure for the Nexus trace Plug-in is set up.
199 Add a dependency to TMF core and UI by opening the '''MANIFEST.MF''' in
200 '''META-INF''', selecting the '''Dependencies''' tab and '''Add ...'''
201 '''org.eclipse.tracecompass.tmf.core''' and '''org.eclipse.tracecompass.tmf.ui'''.
203 [[Image:images/NTTAddDepend.png]]<br>
204 [[Image:images/NTTSelectProjects.png]]<br>
206 Now the project can access TMF classes.
210 The '''TmfEvent''' class will work for this example. No code required.
214 The trace reader will extend a '''TmfTrace''' class.
216 It will need to implement:
218 * validate (is the trace format valid?)
220 * initTrace (called as the trace is opened
222 * seekEvent (go to a position in the trace and create a context)
224 * getNext (implemented in the base class)
226 * parseEvent (read the next element in the trace)
228 For reference, there is an example implementation of the Nexus Trace file in
229 org.eclipse.tracecompass.tracing.examples.core.trace.nexus.NexusTrace.java.
231 In this example, the '''validate''' function first checks if the file
232 exists, then makes sure that it is really a file, and not a directory. Then we
233 attempt to read the file header, to make sure that it is really a Nexus Trace.
234 If that check passes, we return a TraceValidationStatus with a confidence of 20.
236 Typically, TraceValidationStatus confidences should range from 1 to 100. 1 meaning
237 "there is a very small chance that this trace is of this type", and 100 meaning
238 "it is this type for sure, and cannot be anything else". At run-time, the
239 auto-detection will pick the type which returned the highest confidence. So
240 checks of the type "does the file exist?" should not return a too high
241 confidence. If confidence 0 is returned the auto-detection won't pick this type.
243 Here we used a confidence of 20, to leave "room" for more specific trace types
244 in the Nexus format that could be defined in TMF.
246 The '''initTrace''' function will read the event names, and find where the data
247 starts. After this, the number of events is known, and since each event is 8
248 bytes long according to the specs, the seek is then trivial.
250 The '''seek''' here will just reset the reader to the right location.
252 The '''parseEvent''' method needs to parse and return the current event and
253 store the current location.
255 The '''getNext''' method (in base class) will read the next event and update the
256 context. It calls the '''parseEvent''' method to read the event and update the
257 location. It does not need to be overridden and in this example it is not. The
258 sequence of actions necessary are parse the next event from the trace, create an
259 '''ITmfEvent''' with that data, update the current location, call
260 '''updateAttributes''', update the context then return the event.
262 Traces will typically implement an index, to make seeking faster. The index can
263 be rebuilt every time the trace is opened. Alternatively, it can be saved to
264 disk, to make future openings of the same trace quicker. To do so, the trace
265 object can implement the '''ITmfPersistentlyIndexable''' interface.
267 === Trace Context ===
269 The trace context will be a '''TmfContext'''
271 === Trace Location ===
273 The trace location will be a long, representing the rank in the file. The
274 '''TmfLongLocation''' will be the used, once again, no code is required.
276 === The ''org.eclipse.linuxtools.tmf.core.tracetype'' and ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension points ===
278 One should use the ''tmf.core.tracetype'' extension point in their own plug-in.
279 In this example, the Nexus trace plug-in will be modified.
281 The '''plugin.xml''' file in the ui plug-in needs to be updated if one wants
282 users to access the given event type. It can be updated in the Eclipse plug-in
285 # In Extensions tab, add the '''org.eclipse.linuxtools.tmf.core.tracetype''' extension point.
286 [[Image:images/NTTExtension.png]]<br>
287 [[Image:images/NTTTraceType.png]]<br>
288 [[Image:images/NTTExtensionPoint.png]]<br>
290 # Add in the '''org.eclipse.linuxtools.tmf.ui.tracetype''' extension a new type. To do that, '''right click''' on the extension then in the context menu, go to '''New >''', '''type'''.
292 [[Image:images/NTTAddType.png]]<br>
294 The '''id''' is the unique identifier used to refer to the trace.
296 The '''name''' is the field that shall be displayed when a trace type is selected.
298 The '''trace type''' is the canonical path refering to the class of the trace.
300 The '''event type''' is the canonical path refering to the class of the events of a given trace.
302 The '''category''' (optional) is the container in which this trace type will be stored.
304 # (Optional) To also add UI-specific properties to your trace type, use the '''org.eclipse.linuxtools.tmf.ui.tracetypeui''' extension. To do that, '''right click''' on the extension then in the context menu, go to '''New >''', '''type'''.
306 The '''tracetype''' here is the '''id''' of the
307 ''org.eclipse.linuxtools.tmf.core.tracetype'' mentioned above.
309 The '''icon''' is the image to associate with that trace type.
311 In the end, the extension menu should look like this.
313 [[Image:images/NTTPluginxmlComplete.png]]<br>
317 This tutorial describes how to create a simple view using the TMF framework and the SWTChart library. SWTChart is a library based on SWT that can draw several types of charts including a line chart which we will use in this tutorial. We will create a view containing a line chart that displays time stamps on the X axis and the corresponding event values on the Y axis.
319 This tutorial will cover concepts like:
322 * Signal handling (@TmfSignalHandler)
323 * Data requests (TmfEventRequest)
324 * SWTChart integration
326 '''Note''': Trace Compass 0.1.0 provides base implementations for generating SWTChart viewers and views. For more details please refer to chapter [[#TMF Built-in Views and Viewers]].
328 === Prerequisites ===
330 The tutorial is based on Eclipse 4.4 (Eclipse Luna), Trace Compass 0.1.0 and SWTChart 0.7.0. If you are using TMF from the source repository, SWTChart is already included in the target definition file (see org.eclipse.tracecompass.target). You can also install it manually by using the Orbit update site. http://download.eclipse.org/tools/orbit/downloads/
332 === Creating an Eclipse UI Plug-in ===
334 To create a new project with name org.eclipse.tracecompass.tmf.sample.ui select '''File -> New -> Project -> Plug-in Development -> Plug-in Project'''. <br>
335 [[Image:images/Screenshot-NewPlug-inProject1.png]]<br>
337 [[Image:images/Screenshot-NewPlug-inProject2.png]]<br>
339 [[Image:images/Screenshot-NewPlug-inProject3.png]]<br>
341 === Creating a View ===
343 To open the plug-in manifest, double-click on the MANIFEST.MF file. <br>
344 [[Image:images/SelectManifest.png]]<br>
346 Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.tracecompass.tmf.core'' and press '''OK'''<br>
347 Following the same steps, add ''org.eclipse.tracecompass.tmf.ui'' and ''org.swtchart''.<br>
348 [[Image:images/AddDependencyTmfUi.png]]<br>
350 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>
351 [[Image:images/AddViewExtension1.png]]<br>
353 To create a view, click the right mouse button. Then select '''New -> view'''<br>
354 [[Image:images/AddViewExtension2.png]]<br>
356 A new view entry has been created. Fill in the fields ''id'' and ''name''. For ''class'' click on the '''class hyperlink''' and it will show the New Java Class dialog. Enter the name ''SampleView'', change the superclass to ''TmfView'' and click Finish. This will create the source file and fill the ''class'' field in the process. We use TmfView as the superclass because it provides extra functionality like getting the active trace, pinning and it has support for signal handling between components.<br>
357 [[Image:images/FillSampleViewExtension.png]]<br>
359 This will generate an empty class. Once the quick fixes are applied, the following code is obtained:
362 package org.eclipse.tracecompass.tmf.sample.ui;
364 import org.eclipse.swt.widgets.Composite;
365 import org.eclipse.ui.part.ViewPart;
367 public class SampleView extends TmfView {
369 public SampleView(String viewName) {
371 // TODO Auto-generated constructor stub
375 public void createPartControl(Composite parent) {
376 // TODO Auto-generated method stub
381 public void setFocus() {
382 // TODO Auto-generated method stub
389 This creates an empty view, however the basic structure is now is place.
391 === Implementing a view ===
393 We will start by adding a empty chart then it will need to be populated with the trace data. Finally, we will make the chart more visually pleasing by adjusting the range and formating the time stamps.
395 ==== Adding an Empty Chart ====
397 First, we can add an empty chart to the view and initialize some of its components.
400 private static final String SERIES_NAME = "Series";
401 private static final String Y_AXIS_TITLE = "Signal";
402 private static final String X_AXIS_TITLE = "Time";
403 private static final String FIELD = "value"; // The name of the field that we want to display on the Y axis
404 private static final String VIEW_ID = "org.eclipse.tracecompass.tmf.sample.ui.view";
406 private ITmfTrace currentTrace;
408 public SampleView() {
413 public void createPartControl(Composite parent) {
414 chart = new Chart(parent, SWT.BORDER);
415 chart.getTitle().setVisible(false);
416 chart.getAxisSet().getXAxis(0).getTitle().setText(X_AXIS_TITLE);
417 chart.getAxisSet().getYAxis(0).getTitle().setText(Y_AXIS_TITLE);
418 chart.getSeriesSet().createSeries(SeriesType.LINE, SERIES_NAME);
419 chart.getLegend().setVisible(false);
423 public void setFocus() {
428 The view is prepared. Run the Example. To launch the an Eclipse Application select the ''Overview'' tab and click on '''Launch an Eclipse Application'''<br>
429 [[Image:images/RunEclipseApplication.png]]<br>
431 A new Eclipse application window will show. In the new window go to '''Windows -> Show View -> Other... -> Other -> Sample View'''.<br>
432 [[Image:images/ShowViewOther.png]]<br>
434 You should now see a view containing an empty chart<br>
435 [[Image:images/EmptySampleView.png]]<br>
437 ==== Signal Handling ====
439 We would like to populate the view when a trace is selected. To achieve this, we can use a signal hander which is specified with the '''@TmfSignalHandler''' annotation.
443 public void traceSelected(final TmfTraceSelectedSignal signal) {
448 ==== Requesting Data ====
450 Then we need to actually gather data from the trace. This is done asynchronously using a ''TmfEventRequest''
454 public void traceSelected(final TmfTraceSelectedSignal signal) {
455 // Don't populate the view again if we're already showing this trace
456 if (currentTrace == signal.getTrace()) {
459 currentTrace = signal.getTrace();
461 // Create the request to get data from the trace
463 TmfEventRequest req = new TmfEventRequest(TmfEvent.class,
464 TmfTimeRange.ETERNITY, 0, ITmfEventRequest.ALL_DATA,
465 ITmfEventRequest.ExecutionType.BACKGROUND) {
468 public void handleData(ITmfEvent data) {
469 // Called for each event
470 super.handleData(data);
474 public void handleSuccess() {
475 // Request successful, not more data available
476 super.handleSuccess();
480 public void handleFailure() {
481 // Request failed, not more data available
482 super.handleFailure();
485 ITmfTrace trace = signal.getTrace();
486 trace.sendRequest(req);
490 ==== Transferring Data to the Chart ====
492 The chart expects an array of doubles for both the X and Y axis values. To provide that, we can accumulate each event's time and value in their respective list then convert the list to arrays when all events are processed.
495 TmfEventRequest req = new TmfEventRequest(TmfEvent.class,
496 TmfTimeRange.ETERNITY, 0, ITmfEventRequest.ALL_DATA,
497 ITmfEventRequest.ExecutionType.BACKGROUND) {
499 ArrayList<Double> xValues = new ArrayList<Double>();
500 ArrayList<Double> yValues = new ArrayList<Double>();
503 public void handleData(ITmfEvent data) {
504 // Called for each event
505 super.handleData(data);
506 ITmfEventField field = data.getContent().getField(FIELD);
508 yValues.add((Double) field.getValue());
509 xValues.add((double) data.getTimestamp().getValue());
514 public void handleSuccess() {
515 // Request successful, not more data available
516 super.handleSuccess();
518 final double x[] = toArray(xValues);
519 final double y[] = toArray(yValues);
521 // This part needs to run on the UI thread since it updates the chart SWT control
522 Display.getDefault().asyncExec(new Runnable() {
526 chart.getSeriesSet().getSeries()[0].setXSeries(x);
527 chart.getSeriesSet().getSeries()[0].setYSeries(y);
536 * Convert List<Double> to double[]
538 private double[] toArray(List<Double> list) {
539 double[] d = new double[list.size()];
540 for (int i = 0; i < list.size(); ++i) {
549 ==== Adjusting the Range ====
551 The chart now contains values but they might be out of range and not visible. We can adjust the range of each axis by computing the minimum and maximum values as we add events.
555 ArrayList<Double> xValues = new ArrayList<Double>();
556 ArrayList<Double> yValues = new ArrayList<Double>();
557 private double maxY = -Double.MAX_VALUE;
558 private double minY = Double.MAX_VALUE;
559 private double maxX = -Double.MAX_VALUE;
560 private double minX = Double.MAX_VALUE;
563 public void handleData(ITmfEvent data) {
564 super.handleData(data);
565 ITmfEventField field = data.getContent().getField(FIELD);
567 Double yValue = (Double) field.getValue();
568 minY = Math.min(minY, yValue);
569 maxY = Math.max(maxY, yValue);
572 double xValue = (double) data.getTimestamp().getValue();
574 minX = Math.min(minX, xValue);
575 maxX = Math.max(maxX, xValue);
580 public void handleSuccess() {
581 super.handleSuccess();
582 final double x[] = toArray(xValues);
583 final double y[] = toArray(yValues);
585 // This part needs to run on the UI thread since it updates the chart SWT control
586 Display.getDefault().asyncExec(new Runnable() {
590 chart.getSeriesSet().getSeries()[0].setXSeries(x);
591 chart.getSeriesSet().getSeries()[0].setYSeries(y);
594 if (!xValues.isEmpty() && !yValues.isEmpty()) {
595 chart.getAxisSet().getXAxis(0).setRange(new Range(0, x[x.length - 1]));
596 chart.getAxisSet().getYAxis(0).setRange(new Range(minY, maxY));
598 chart.getAxisSet().getXAxis(0).setRange(new Range(0, 1));
599 chart.getAxisSet().getYAxis(0).setRange(new Range(0, 1));
601 chart.getAxisSet().adjustRange();
609 ==== Formatting the Time Stamps ====
611 To display the time stamps on the X axis nicely, we need to specify a format or else the time stamps will be displayed as ''long''. We use TmfTimestampFormat to make it consistent with the other TMF views. We also need to handle the '''TmfTimestampFormatUpdateSignal''' to make sure that the time stamps update when the preferences change.
615 public void createPartControl(Composite parent) {
618 chart.getAxisSet().getXAxis(0).getTick().setFormat(new TmfChartTimeStampFormat());
621 public class TmfChartTimeStampFormat extends SimpleDateFormat {
622 private static final long serialVersionUID = 1L;
624 public StringBuffer format(Date date, StringBuffer toAppendTo, FieldPosition fieldPosition) {
625 long time = date.getTime();
626 toAppendTo.append(TmfTimestampFormat.getDefaulTimeFormat().format(time));
632 public void timestampFormatUpdated(TmfTimestampFormatUpdateSignal signal) {
633 // Called when the time stamp preference is changed
634 chart.getAxisSet().getXAxis(0).getTick().setFormat(new TmfChartTimeStampFormat());
639 We also need to populate the view when a trace is already selected and the view is opened. We can reuse the same code by having the view send the '''TmfTraceSelectedSignal''' to itself.
643 public void createPartControl(Composite parent) {
646 ITmfTrace trace = getActiveTrace();
648 traceSelected(new TmfTraceSelectedSignal(this, trace));
653 The view is now ready but we need a proper trace to test it. For this example, a trace was generated using LTTng-UST so that it would produce a sine function.<br>
655 [[Image:images/SampleView.png]]<br>
657 In summary, we have implemented a simple TMF view using the SWTChart library. We made use of signals and requests to populate the view at the appropriate time and we formated the time stamps nicely. We also made sure that the time stamp format is updated when the preferences change.
659 == TMF Built-in Views and Viewers ==
661 TMF provides base implementations for several types of views and viewers for generating custom X-Y-Charts, Time Graphs, or Trees. They are well integrated with various TMF features such as reading traces and time synchronization with other views. They also handle mouse events for navigating the trace and view, zooming or presenting detailed information at mouse position. The code can be found in the TMF UI plug-in ''org.eclipse.tracecompass.tmf.ui''. See below for a list of relevant java packages:
664 ** ''org.eclipse.tracecompass.tmf.ui.views'': Common TMF view base classes
666 ** ''org.eclipse.tracecompass.tmf.ui.viewers.xycharts'': Common base classes for X-Y-Chart viewers based on SWTChart
667 ** ''org.eclipse.tracecompass.tmf.ui.viewers.xycharts.barcharts'': Base classes for bar charts
668 ** ''org.eclipse.tracecompass.tmf.ui.viewers.xycharts.linecharts'': Base classes for line charts
670 ** ''org.eclipse.tracecompass.tmf.ui.widgets.timegraph'': Base classes for time graphs e.g. Gantt-charts
672 ** ''org.eclipse.tracecompass.tmf.ui.viewers.tree'': Base classes for TMF specific tree viewers
674 Several features in TMF and the Eclipse LTTng integration are using this framework and can be used as example for further developments:
676 ** ''org.eclipse.tracecompass.internal.lttng2.ust.ui.views.memusage.MemUsageView.java''
677 ** ''org.eclipse.tracecompass.analysis.os.linux.ui.views.cpuusage.CpuUsageView.java''
678 ** ''org.eclipse.tracecompass.tracing.examples.ui.views.histogram.NewHistogramView.java''
680 ** ''org.eclipse.tracecompass.analysis.os.linux.ui.views.controlflow.ControlFlowView.java''
681 ** ''org.eclipse.tracecompass.analysis.os.linux.ui.views.resources.ResourcesView.java''
683 ** ''org.eclipse.tracecompass.tmf.ui.views.statesystem.TmfStateSystemExplorer.java''
684 ** ''org.eclipse.tracecompass.analysis.os.linux.ui.views.cpuusage.CpuUsageComposite.java''
686 == Timing Analysis Views and Viewers ==
688 Trace Compass provides base implementations for timing views and viewers for generating Latency Tables, Scatter Charts, Density Graphs and Statistics Tables. They are well integrated with various Trace Compass features such as reading traces and time synchronization with other views. They also handle mouse events for navigating the trace and view, zooming or presenting detailed information at mouse position. The code can be found in the Analysis Timing plug-in ''org.eclipse.tracecompass.analysis.timing.ui''. See below for a list of relevant java packages:
691 ** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.table'': Base classes for Latency Tables
693 ** ''org.eclipse.tracecompass.tmf.ui.views.tmfChartView.java'': Common base classes for X-Y-Chart viewers based on SWTChart
694 ** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.scatter'': Base classes for Scatter Charts
696 ** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.density'': Base classes for Density Graphs
698 ** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.statistics'': Base classes for Statistics Tables
700 Several features in Trace Compass are using this framework and can be used as example for further development:
703 ** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyView.java''
704 ** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternLatencyTableView.java''
706 ** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyScatterView.java''
707 ** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternScatterGraphView.java''
709 ** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyDensityView.java''
710 ** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternDensityView.java''
713 ** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.statistics.SystemCallLatencyStatisticsView.java''
714 ** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternStatisticsView.java''
716 = Component Interaction =
718 TMF provides a mechanism for different components to interact with each other using signals. The signals can carry information that is specific to each signal.
720 The TMF Signal Manager handles registration of components and the broadcasting of signals to their intended receivers.
722 Components can register as VIP receivers which will ensure they will receive the signal before non-VIP receivers.
724 == Sending Signals ==
726 In order to send a signal, an instance of the signal must be created and passed as argument to the signal manager to be dispatched. Every component that can handle the signal will receive it. The receivers do not need to be known by the sender.
729 TmfExampleSignal signal = new TmfExampleSignal(this, ...);
730 TmfSignalManager.dispatchSignal(signal);
733 If the sender is an instance of the class TmfComponent, the broadcast method can be used:
736 TmfExampleSignal signal = new TmfExampleSignal(this, ...);
740 == Receiving Signals ==
742 In order to receive any signal, the receiver must first be registered with the signal manager. The receiver can register as a normal or VIP receiver.
745 TmfSignalManager.register(this);
746 TmfSignalManager.registerVIP(this);
749 If the receiver is an instance of the class TmfComponent, it is automatically registered as a normal receiver in the constructor.
751 When the receiver is destroyed or disposed, it should deregister itself from the signal manager.
754 TmfSignalManager.deregister(this);
757 To actually receive and handle any specific signal, the receiver must use the @TmfSignalHandler annotation and implement a method that will be called when the signal is broadcast. The name of the method is irrelevant.
761 public void example(TmfExampleSignal signal) {
766 The source of the signal can be used, if necessary, by a component to filter out and ignore a signal that was broadcast by itself when the component is also a receiver of the signal but only needs to handle it when it was sent by another component or another instance of the component.
768 == Signal Throttling ==
770 It is possible for a TmfComponent instance to buffer the dispatching of signals so that only the last signal queued after a specified delay without any other signal queued is sent to the receivers. All signals that are preempted by a newer signal within the delay are discarded.
772 The signal throttler must first be initialized:
775 final int delay = 100; // in ms
776 TmfSignalThrottler throttler = new TmfSignalThrottler(this, delay);
779 Then the sending of signals should be queued through the throttler:
782 TmfExampleSignal signal = new TmfExampleSignal(this, ...);
783 throttler.queue(signal);
786 When the throttler is no longer needed, it should be disposed:
792 == Signal Reference ==
794 The following is a list of built-in signals defined in the framework.
796 === TmfStartSynchSignal ===
800 This signal is used to indicate the start of broadcasting of a signal. Internally, the data provider will not fire event requests until the corresponding TmfEndSynchSignal signal is received. This allows coalescing of requests triggered by multiple receivers of the broadcast signal.
804 Sent by TmfSignalManager before dispatching a signal to all receivers.
808 Received by TmfDataProvider.
810 === TmfEndSynchSignal ===
814 This signal is used to indicate the end of broadcasting of a signal. Internally, the data provider fire all pending event requests that were received and buffered since the corresponding TmfStartSynchSignal signal was received. This allows coalescing of requests triggered by multiple receivers of the broadcast signal.
818 Sent by TmfSignalManager after dispatching a signal to all receivers.
822 Received by TmfDataProvider.
824 === TmfTraceOpenedSignal ===
828 This signal is used to indicate that a trace has been opened in an editor.
832 Sent by a TmfEventsEditor instance when it is created.
836 Received by TmfTrace, TmfExperiment, TmfTraceManager and every view that shows trace data. Components that show trace data should handle this signal.
838 === TmfTraceSelectedSignal ===
842 This signal is used to indicate that a trace has become the currently selected trace.
846 Sent by a TmfEventsEditor instance when it receives focus. Components can send this signal to make a trace editor be brought to front.
850 Received by TmfTraceManager and every view that shows trace data. Components that show trace data should handle this signal.
852 === TmfTraceClosedSignal ===
856 This signal is used to indicate that a trace editor has been closed.
860 Sent by a TmfEventsEditor instance when it is disposed.
864 Received by TmfTraceManager and every view that shows trace data. Components that show trace data should handle this signal.
866 === TmfTraceRangeUpdatedSignal ===
870 This signal is used to indicate that the valid time range of a trace has been updated. This triggers indexing of the trace up to the end of the range. In the context of streaming, this end time is considered a safe time up to which all events are guaranteed to have been completely received. For non-streaming traces, the end time is set to infinity indicating that all events can be read immediately. Any processing of trace events that wants to take advantage of request coalescing should be triggered by this signal.
874 Sent by TmfExperiment and non-streaming TmfTrace. Streaming traces should send this signal in the TmfTrace subclass when a new safe time is determined by a specific implementation.
878 Received by TmfTrace, TmfExperiment and components that process trace events. Components that need to process trace events should handle this signal.
880 === TmfTraceUpdatedSignal ===
884 This signal is used to indicate that new events have been indexed for a trace.
888 Sent by TmfCheckpointIndexer when new events have been indexed and the number of events has changed.
892 Received by components that need to be notified of a new trace event count.
894 === TmfSelectionRangeUpdatedSignal ===
898 This signal is used to indicate that a new time or time range has been
899 selected. It contains a begin and end time. If a single time is selected then
900 the begin and end time are the same.
904 Sent by any component that allows the user to select a time or time range.
908 Received by any component that needs to be notified of the currently selected time or time range.
910 === TmfWindowRangeUpdatedSignal ===
914 This signal is used to indicate that a new time range window has been set.
918 Sent by any component that allows the user to set a time range window.
922 Received by any component that needs to be notified of the current visible time range window.
924 === TmfEventFilterAppliedSignal ===
928 This signal is used to indicate that a filter has been applied to a trace.
932 Sent by TmfEventsTable when a filter is applied.
936 Received by any component that shows trace data and needs to be notified of applied filters.
938 === TmfEventSearchAppliedSignal ===
942 This signal is used to indicate that a search has been applied to a trace.
946 Sent by TmfEventsTable when a search is applied.
950 Received by any component that shows trace data and needs to be notified of applied searches.
952 === TmfTimestampFormatUpdateSignal ===
956 This signal is used to indicate that the timestamp format preference has been updated.
960 Sent by TmfTimestampFormat when the default timestamp format preference is changed.
964 Received by any component that needs to refresh its display for the new timestamp format.
966 === TmfStatsUpdatedSignal ===
970 This signal is used to indicate that the statistics data model has been updated.
974 Sent by statistic providers when new statistics data has been processed.
978 Received by statistics viewers and any component that needs to be notified of a statistics update.
980 === TmfPacketStreamSelected ===
984 This signal is used to indicate that the user has selected a packet stream to analyze.
988 Sent by the Stream List View when the user selects a new packet stream.
992 Received by views that analyze packet streams.
994 === TmfStartAnalysisSignal ===
998 This signal is used to indicate that an analysis has started.
1002 Sent by an analysis module when it starts to execute the analyis.
1006 Received by components that need to be notified of the start of an analysis
1007 or that need to receive the analysis module.
1009 === TmfCpuSelectedSignal ===
1013 This signal is used to indicate that the user has selected a CPU core.
1017 Sent by any component that allows the user to select a CPU.
1021 Received by viewers that show information specific to a selected CPU.
1023 === TmfThreadSelectedSignal ===
1027 This signal is used to indicate that the user has selected a thread.
1031 Sent by any component that allows the user to select a thread.
1035 Received by viewers that show information specific to a selected thread.
1037 === TmfSymbolProviderUpdatedSignal ===
1041 This signal is used to indicate that the user has updated the symbol mapping.
1045 Sent by symbol providers or managers when more information is available.
1049 Received by viewers that show information specific to mapped symbol, typically a function call.
1051 === TmfTraceSynchronizedSignal ===
1055 This signal is used to indicate that trace synchronization has been completed.
1059 Sent by the experiment after trace synchronization.
1063 Received by any component that needs to be notified of trace synchronization.
1065 === TmfMarkerEventSourceUpdatedSignal ===
1069 This signal is used to indicate that a marker event source has been updated.
1073 Sent by a component that has triggered a change in a marker event source.
1077 Received by any component that needs to refresh the markers due to the change in marker event source.
1081 TMF has built-in Eclipse tracing support for the debugging of signal interaction between components. To enable it, open the '''Run/Debug Configuration...''' dialog, select a configuration, click the '''Tracing''' tab, select the plug-in '''org.eclipse.tracecompass.tmf.core''', and check the '''signal''' item.
1083 All signals sent and received will be logged to the file TmfTrace.log located in the Eclipse home directory.
1085 = Generic State System =
1089 The Generic State System is a utility available in TMF to track different states
1090 over the duration of a trace. It works by first sending some or all events of
1091 the trace into a state provider, which defines the state changes for a given
1092 trace type. Once built, views and analysis modules can then query the resulting
1093 database of states (called "state history") to get information.
1095 For example, let's suppose we have the following sequence of events in a kernel
1098 10 s, sys_open, fd = 5, file = /home/user/myfile
1100 15 s, sys_read, fd = 5, size=32
1102 20 s, sys_close, fd = 5
1104 Now let's say we want to implement an analysis module which will track the
1105 amount of bytes read and written to each file. Here, of course the sys_read is
1106 interesting. However, by just looking at that event, we have no information on
1107 which file is being read, only its fd (5) is known. To get the match
1108 fd5 = /home/user/myfile, we have to go back to the sys_open event which happens
1111 But since we don't know exactly where this sys_open event is, we will have to go
1112 back to the very start of the trace, and look through events one by one! This is
1113 obviously not efficient, and will not scale well if we want to analyze many
1114 similar patterns, or for very large traces.
1116 A solution in this case would be to use the state system to keep track of the
1117 amount of bytes read/written to every *filename* (instead of every file
1118 descriptor, like we get from the events). Then the module could ask the state
1119 system "what is the amount of bytes read for file "/home/user/myfile" at time
1120 16 s", and it would return the answer "32" (assuming there is no other read
1121 than the one shown).
1123 == High-level components ==
1125 The State System infrastructure is composed of 3 parts:
1126 * The state provider
1127 * The central state system
1128 * The storage backend
1130 The state provider is the customizable part. This is where the mapping from
1131 trace events to state changes is done. This is what you want to implement for
1132 your specific trace type and analysis type. It's represented by the
1133 ITmfStateProvider interface (with a threaded implementation in
1134 AbstractTmfStateProvider, which you can extend).
1136 The core of the state system is exposed through the ITmfStateSystem and
1137 ITmfStateSystemBuilder interfaces. The former allows only read-only access and
1138 is typically used for views doing queries. The latter also allows writing to the
1139 state history, and is typically used by the state provider.
1141 Finally, each state system has its own separate backend. This determines how the
1142 intervals, or the "state history", are saved (in RAM, on disk, etc.) You can
1143 select the type of backend at construction time in the TmfStateSystemFactory.
1147 Before we dig into how to use the state system, we should go over some useful
1152 An attribute is the smallest element of the model that can be in any particular
1153 state. When we refer to the "full state", in fact it means we are interested in
1154 the state of every single attribute of the model.
1156 === Attribute Tree ===
1158 Attributes in the model can be placed in a tree-like structure, a bit like files
1159 and directories in a file system. However, note that an attribute can always
1160 have both a value and sub-attributes, so they are like files and directories at
1161 the same time. We are then able to refer to every single attribute with its
1164 For example, in the attribute tree for Linux kernel traces, we use the following
1165 attributes, among others:
1183 In this model, the attribute "Processes/1000/PPID" refers to the PPID of process
1184 with PID 1000. The attribute "CPUs/0/Status" represents the status (running,
1185 idle, etc.) of CPU 0. "Processes/1000/PPID" and "Processes/1001/PPID" are two
1186 different attribute, even though their base name is the same: the whole path is
1187 the unique identifier.
1189 The value of each attribute can change over the duration of the trace,
1190 independently of the other ones, and independently of its position in the tree.
1192 The tree-like organization is optional, all attributes could be at the same
1193 level. But it's possible to put them in a tree, and it helps make things
1198 In addition to a given path, each attribute also has a unique integer
1199 identifier, called the "quark". To continue with the file system analogy, this
1200 is like the inode number. When a new attribute is created, a new unique quark
1201 will be assigned automatically. They are assigned incrementally, so they will
1202 normally be equal to their order of creation, starting at 0.
1204 Methods are offered to get the quark of an attribute from its path. The API
1205 methods for inserting state changes and doing queries normally use quarks
1206 instead of paths. This is to encourage users to cache the quarks and re-use
1207 them, which avoids re-walking the attribute tree over and over, which avoids
1208 unneeded hashing of strings.
1212 The path and quark of an attribute will remain constant for the whole duration
1213 of the trace. However, the value carried by the attribute will change. The value
1214 of a specific attribute at a specific time is called the state value.
1216 In the TMF implementation, state values can be integers, longs, doubles, or strings.
1217 There is also a "null value" type, which is used to indicate that no particular
1218 value is active for this attribute at this time, but without resorting to a
1221 Any other type of value could be used, as long as the backend knows how to store
1224 Note that the TMF implementation also forces every attribute to always carry the
1225 same type of state value. This is to make it simpler for views, so they can
1226 expect that an attribute will always use a given type, without having to check
1227 every single time. Null values are an exception, they are always allowed for all
1228 attributes, since they can safely be "unboxed" into all types.
1230 === State change ===
1232 A state change is the element that is inserted in the state system. It consists
1234 * a timestamp (the time at which the state change occurs)
1235 * an attribute (the attribute whose value will change)
1236 * a state value (the new value that the attribute will carry)
1238 It's not an object per se in the TMF implementation (it's represented by a
1239 function call in the state provider). Typically, the state provider will insert
1240 zero, one or more state changes for every trace event, depending on its event
1243 Note, we use "timestamp" here, but it's in fact a generic term that could be
1244 referred to as "index". For example, if a given trace type has no notion of
1245 timestamp, the event rank could be used.
1247 In the TMF implementation, the timestamp is a long (64-bit integer).
1249 === State interval ===
1251 State changes are inserted into the state system, but state intervals are the
1252 objects that come out on the other side. Those are stocked in the storage
1253 backend. A state interval represents a "state" of an attribute we want to track.
1254 When doing queries on the state system, intervals are what is returned. The
1255 components of a state interval are:
1261 The start and end times represent the time range of the state. The state value
1262 is the same as the state value in the state change that started this interval.
1263 The interval also keeps a reference to its quark, although you normally know
1264 your quark in advance when you do queries.
1266 === State history ===
1268 The state history is the name of the container for all the intervals created by
1269 the state system. The exact implementation (how the intervals are stored) is
1270 determined by the storage backend that is used.
1272 Some backends will use a state history that is persistent on disk, others do not.
1273 When loading a trace, if a history file is available and the backend supports
1274 it, it will be loaded right away, skipping the need to go through another
1277 === Construction phase ===
1279 Before we can query a state system, we need to build the state history first. To
1280 do so, trace events are sent one-by-one through the state provider, which in
1281 turn sends state changes to the central component, which then creates intervals
1282 and stores them in the backend. This is called the construction phase.
1284 Note that the state system needs to receive its events into chronological order.
1285 This phase will end once the end of the trace is reached.
1287 Also note that it is possible to query the state system while it is being build.
1288 Any timestamp between the start of the trace and the current end time of the
1289 state system (available with ITmfStateSystem#getCurrentEndTime()) is a valid
1290 timestamp that can be queried.
1294 As mentioned previously, when doing queries on the state system, the returned
1295 objects will be state intervals. In most cases it's the state *value* we are
1296 interested in, but since the backend has to instantiate the interval object
1297 anyway, there is no additional cost to return the interval instead. This way we
1298 also get the start and end times of the state "for free".
1300 There are two types of queries that can be done on the state system:
1302 ==== Full queries ====
1304 A full query means that we want to retrieve the whole state of the model for one
1305 given timestamp. As we remember, this means "the state of every single attribute
1306 in the model". As parameter we only need to pass the timestamp (see the API
1307 methods below). The return value will be an array of intervals, where the offset
1308 in the array represents the quark of each attribute.
1310 ==== Single queries ====
1312 In other cases, we might only be interested in the state of one particular
1313 attribute at one given timestamp. For these cases it's better to use a
1314 single query. For a single query. we need to pass both a timestamp and a
1315 quark in parameter. The return value will be a single interval, representing
1316 the state that this particular attribute was at that time.
1318 Single queries are typically faster than full queries (but once again, this
1319 depends on the backend that is used), but not by much. Even if you only want the
1320 state of say 10 attributes out of 200, it could be faster to use a full query
1321 and only read the ones you need. Single queries should be used for cases where
1322 you only want one attribute per timestamp (for example, if you follow the state
1323 of the same attribute over a time range).
1326 == Relevant interfaces/classes ==
1328 This section will describe the public interface and classes that can be used if
1329 you want to use the state system.
1331 === Main classes in org.eclipse.tracecompass.tmf.core.statesystem ===
1333 ==== ITmfStateProvider / AbstractTmfStateProvider ====
1335 ITmfStateProvider is the interface you have to implement to define your state
1336 provider. This is where most of the work has to be done to use a state system
1337 for a custom trace type or analysis type.
1339 For first-time users, it's recommended to extend AbstractTmfStateProvider
1340 instead. This class takes care of all the initialization mumbo-jumbo, and also
1341 runs the event handler in a separate thread. You will only need to implement
1342 eventHandle, which is the call-back that will be called for every event in the
1345 For an example, you can look at StatsStateProvider in the TMF tree, or at the
1346 small example below.
1348 ==== TmfStateSystemFactory ====
1350 Once you have defined your state provider, you need to tell your trace type to
1351 build a state system with this provider during its initialization. This consists
1352 of overriding TmfTrace#buildStateSystems() and in there of calling the method in
1353 TmfStateSystemFactory that corresponds to the storage backend you want to use
1354 (see the section [[#Comparison of state system backends]]).
1356 You will have to pass in parameter the state provider you want to use, which you
1357 should have defined already. Each backend can also ask for more configuration
1360 You must then call registerStateSystem(id, statesystem) to make your state
1361 system visible to the trace objects and the views. The ID can be any string of
1362 your choosing. To access this particular state system, the views or modules will
1363 need to use this ID.
1365 Also, don't forget to call super.buildStateSystems() in your implementation,
1366 unless you know for sure you want to skip the state providers built by the
1369 You can look at how LttngKernelTrace does it for an example. It could also be
1370 possible to build a state system only under certain conditions (like only if the
1371 trace contains certain event types).
1374 ==== ITmfStateSystem ====
1376 ITmfStateSystem is the main interface through which views or analysis modules
1377 will access the state system. It offers a read-only view of the state system,
1378 which means that no states can be inserted, and no attributes can be created.
1379 Calling TmfTrace#getStateSystems().get(id) will return you a ITmfStateSystem
1380 view of the requested state system. The main methods of interest are:
1382 ===== getQuarkAbsolute()/getQuarkRelative() =====
1384 Those are the basic quark-getting methods. The goal of the state system is to
1385 return the state values of given attributes at given timestamps. As we've seen
1386 earlier, attributes can be described with a file-system-like path. The goal of
1387 these methods is to convert from the path representation of the attribute to its
1390 Since quarks are created on-the-fly, there is no guarantee that the same
1391 attributes will have the same quark for two traces of the same type. The views
1392 should always query their quarks when dealing with a new trace or a new state
1393 provider. Beyond that however, quarks should be cached and reused as much as
1394 possible, to avoid potentially costly string re-hashing.
1396 getQuarkAbsolute() takes a variable amount of Strings in parameter, which
1397 represent the full path to the attribute. Some of them can be constants, some
1398 can come programmatically, often from the event's fields.
1400 getQuarkRelative() is to be used when you already know the quark of a certain
1401 attribute, and want to access on of its sub-attributes. Its first parameter is
1402 the origin quark, followed by a String varagrs which represent the relative path
1403 to the final attribute.
1405 These two methods will throw an AttributeNotFoundException if trying to access
1406 an attribute that does not exist in the model.
1408 These methods also imply that the view has the knowledge of how the attribute
1409 tree is organized. This should be a reasonable hypothesis, since the same
1410 analysis plugin will normally ship both the state provider and the view, and
1411 they will have been written by the same person. In other cases, it's possible to
1412 use getSubAttributes() to explore the organization of the attribute tree first.
1414 ===== optQuarkAbsolute()/optQuarkRelative() =====
1416 These two methods are similar to their counterparts getQuarkAbsolute() and
1417 getQuarkRelative(). The only difference is that if the referenced attribute does
1418 not exist, the value ITmfStateSystem#INVALID_ATTRIBUTE (-2) is returned instead
1419 of throwing an exception.
1421 These methods should be used when the presence of the referenced attribute is
1422 known to be optional, to avoid the performance cost of generating exceptions.
1424 ===== getQuarks() =====
1426 This method (with or without a starting node quark) takes an attribute path
1427 array which may contain wildcard "*" or parent ".." elements, and returns the
1428 list of matching attribute quarks. If no matching attribute is found, an empty
1431 ===== waitUntilBuilt() =====
1433 This is a simple method used to block the caller until the construction phase of
1434 this state system is done. If the view prefers to wait until all information is
1435 available before starting to do queries (to get all known attributes right away,
1436 for example), this is the guy to call.
1438 ===== queryFullState() =====
1440 This is the method to do full queries. As mentioned earlier, you only need to
1441 pass a target timestamp in parameter. It will return a List of state intervals,
1442 in which the offset corresponds to the attribute quark. This will represent the
1443 complete state of the model at the requested time.
1445 ===== querySingleState() =====
1447 The method to do single queries. You pass in parameter both a timestamp and an
1448 attribute quark. This will return the single state matching this
1449 timestamp/attribute pair.
1451 Other methods are available, you are encouraged to read their Javadoc and see if
1452 they can be potentially useful.
1454 ==== ITmfStateSystemBuilder ====
1456 ITmfStateSystemBuilder is the read-write interface to the state system. It
1457 extends ITmfStateSystem itself, so all its methods are available. It then adds
1458 methods that can be used to write to the state system, either by creating new
1459 attributes of inserting state changes.
1461 It is normally reserved for the state provider and should not be visible to
1462 external components. However it will be available in AbstractTmfStateProvider,
1463 in the field 'ss'. That way you can call ss.modifyAttribute() etc. in your state
1464 provider to write to the state.
1466 The main methods of interest are:
1468 ===== getQuark*AndAdd() =====
1470 getQuarkAbsoluteAndAdd() and getQuarkRelativeAndAdd() work exactly like their
1471 non-AndAdd counterparts in ITmfStateSystem. The difference is that the -AndAdd
1472 versions will not throw any exception: if the requested attribute path does not
1473 exist in the system, it will be created, and its newly-assigned quark will be
1476 When in a state provider, the -AndAdd version should normally be used (unless
1477 you know for sure the attribute already exist and don't want to create it
1478 otherwise). This means that there is no need to define the whole attribute tree
1479 in advance, the attributes will be created on-demand.
1481 ===== modifyAttribute() =====
1483 This is the main state-change-insertion method. As was explained before, a state
1484 change is defined by a timestamp, an attribute and a state value. Those three
1485 elements need to be passed to modifyAttribute as parameters.
1487 Other state change insertion methods are available (increment-, push-, pop- and
1488 removeAttribute()), but those are simply convenience wrappers around
1489 modifyAttribute(). Check their Javadoc for more information.
1491 ===== closeHistory() =====
1493 When the construction phase is done, do not forget to call closeHistory() to
1494 tell the backend that no more intervals will be received. Depending on the
1495 backend type, it might have to save files, close descriptors, etc. This ensures
1496 that a persistent file can then be re-used when the trace is opened again.
1498 If you use the AbstractTmfStateProvider, it will call closeHistory()
1499 automatically when it reaches the end of the trace.
1501 === Other relevant interfaces ===
1503 ==== ITmfStateValue ====
1505 This is the interface used to represent state values. Those are used when
1506 inserting state changes in the provider, and is also part of the state intervals
1507 obtained when doing queries.
1509 The abstract TmfStateValue class contains the factory methods to create new
1510 state values of either int, long, double or string types. To retrieve the real
1511 object inside the state value, one can use the .unbox* methods.
1513 Note: Do not instantiate null values manually, use TmfStateValue.nullValue()
1515 ==== ITmfStateInterval ====
1517 This is the interface to represent the state intervals, which are stored in the
1518 state history backend, and are returned when doing state system queries. A very
1519 simple implementation is available in TmfStateInterval. Its methods should be
1524 The following exceptions, found in o.e.t.statesystem.core.exceptions, are related to
1525 state system activities.
1527 ==== AttributeNotFoundException ====
1529 This is thrown by getQuarkRelative() and getQuarkAbsolute() (but not by the
1530 -AndAdd versions!) when passing an attribute path that is not present in the
1531 state system. This is to ensure that no new attribute is created when using
1532 these versions of the methods.
1534 Views can expect some attributes to be present, but they should handle these
1535 exceptions for when the attributes end up not being in the state system (perhaps
1536 this particular trace didn't have a certain type of events, etc.)
1538 ==== StateValueTypeException ====
1540 This exception will be thrown when trying to unbox a state value into a type
1541 different than its own. You should always check with ITmfStateValue#getType()
1542 beforehand if you are not sure about the type of a given state value.
1544 ==== TimeRangeException ====
1546 This exception is thrown when trying to do a query on the state system for a
1547 timestamp that is outside of its range. To be safe, you should check with
1548 ITmfStateSystem#getStartTime() and #getCurrentEndTime() for the current valid
1549 range of the state system. This is especially important when doing queries on
1550 a state system that is currently being built.
1552 ==== StateSystemDisposedException ====
1554 This exception is thrown when trying to access a state system that has been
1555 disposed, with its dispose() method. This can potentially happen at shutdown,
1556 since Eclipse is not always consistent with the order in which the components
1560 == Comparison of state system backends ==
1562 As we have seen in section [[#High-level components]], the state system needs
1563 a storage backend to save the intervals. Different implementations are
1564 available when building your state system from TmfStateSystemFactory.
1566 Do not confuse full/single queries with full/partial history! All backend types
1567 should be able to handle any type of queries defined in the ITmfStateSystem API,
1568 unless noted otherwise.
1570 === Full history ===
1572 Available with TmfStateSystemFactory#newFullHistory(). The full history uses a
1573 History Tree data structure, which is an optimized structure store state
1574 intervals on disk. Once built, it can respond to queries in a ''log(n)'' manner.
1576 You need to specify a file at creation time, which will be the container for
1577 the history tree. Once it's completely built, it will remain on disk (until you
1578 delete the trace from the project). This way it can be reused from one session
1579 to another, which makes subsequent loading time much faster.
1581 This the backend used by the LTTng kernel plugin. It offers good scalability and
1582 performance, even at extreme sizes (it's been tested with traces of sizes up to
1583 500 GB). Its main downside is the amount of disk space required: since every
1584 single interval is written to disk, the size of the history file can quite
1585 easily reach and even surpass the size of the trace itself.
1587 === Null history ===
1589 Available with TmfStateSystemFactory#newNullHistory(). As its name implies the
1590 null history is in fact an absence of state history. All its query methods will
1591 return null (see the Javadoc in NullBackend).
1593 Obviously, no file is required, and almost no memory space is used.
1595 It's meant to be used in cases where you are not interested in past states, but
1596 only in the "ongoing" one. It can also be useful for debugging and benchmarking.
1598 === In-memory history ===
1600 Available with TmfStateSystemFactory#newInMemHistory(). This is a simple wrapper
1601 using a TreeSet to store all state intervals in memory. The implementation at
1602 the moment is quite simple, it will perform a binary search on entries when
1603 doing queries to find the ones that match.
1605 The advantage of this method is that it's very quick to build and query, since
1606 all the information resides in memory. However, you are limited to 2^31 entries
1607 (roughly 2 billions), and depending on your state provider and trace type, that
1608 can happen really fast!
1610 There are no safeguards, so if you bust the limit you will end up with
1611 ArrayOutOfBoundsException's everywhere. If your trace or state history can be
1612 arbitrarily big, it's probably safer to use a Full History instead.
1614 === Partial history ===
1616 Available with TmfStateSystemFactory#newPartialHistory(). The partial history is
1617 a more advanced form of the full history. Instead of writing all state intervals
1618 to disk like with the full history, we only write a small fraction of them, and
1619 go back to read the trace to recreate the states in-between.
1621 It has a big advantage over a full history in terms of disk space usage. It's
1622 very possible to reduce the history tree file size by a factor of 1000, while
1623 keeping query times within a factor of two. Its main downside comes from the
1624 fact that you cannot do efficient single queries with it (they are implemented
1625 by doing full queries underneath).
1627 This makes it a poor choice for views like the Control Flow view, where you do
1628 a lot of range queries and single queries. However, it is a perfect fit for
1629 cases like statistics, where you usually do full queries already, and you store
1630 lots of small states which are very easy to "compress".
1632 However, it can't really be used until bug 409630 is fixed.
1634 == State System Operations ==
1636 TmfStateSystemOperations is a static class that implements additional
1637 statistical operations that can be performed on attributes of the state system.
1639 These operations require that the attribute be one of the numerical values
1640 (int, long or double).
1642 The speed of these operations can be greatly improved for large data sets if
1643 the attribute was inserted in the state system as a mipmap attribute. Refer to
1644 the [[#Mipmap feature | Mipmap feature]] section.
1646 ===== queryRangeMax() =====
1648 This method returns the maximum numerical value of an attribute in the
1649 specified time range. The attribute must be of type int, long or double.
1650 Null values are ignored. The returned value will be of the same state value
1651 type as the base attribute, or a null value if there is no state interval
1652 stored in the given time range.
1654 ===== queryRangeMin() =====
1656 This method returns the minimum numerical value of an attribute in the
1657 specified time range. The attribute must be of type int, long or double.
1658 Null values are ignored. The returned value will be of the same state value
1659 type as the base attribute, or a null value if there is no state interval
1660 stored in the given time range.
1662 ===== queryRangeAverage() =====
1664 This method returns the average numerical value of an attribute in the
1665 specified time range. The attribute must be of type int, long or double.
1666 Each state interval value is weighted according to time. Null values are
1667 counted as zero. The returned value will be a double primitive, which will
1668 be zero if there is no state interval stored in the given time range.
1672 Here is a small example of code that will use the state system. For this
1673 example, let's assume we want to track the state of all the CPUs in a LTTng
1674 kernel trace. To do so, we will watch for the "sched_switch" event in the state
1675 provider, and will update an attribute indicating if the associated CPU should
1676 be set to "running" or "idle".
1678 We will use an attribute tree that looks like this:
1692 The second-level attributes will be named from the information available in the
1693 trace events. Only the "Status" attributes will carry a state value (this means
1694 we could have just used "1", "2", "3",... directly, but we'll do it in a tree
1695 for the example's sake).
1697 Also, we will use integer state values to represent "running" or "idle", instead
1698 of saving the strings that would get repeated every time. This will help in
1699 reducing the size of the history file.
1701 First we will define a state provider in MyStateProvider. Then, we define an
1702 analysis module that takes care of creating the state provider. The analysis
1703 module will also contain code that can query the state system.
1705 === State Provider ===
1708 import static org.eclipse.tracecompass.common.core.NonNullUtils.checkNotNull;
1709 import org.eclipse.jdt.annotation.NonNull;
1710 import org.eclipse.tracecompass.statesystem.core.exceptions.AttributeNotFoundException;
1711 import org.eclipse.tracecompass.statesystem.core.exceptions.StateValueTypeException;
1712 import org.eclipse.tracecompass.statesystem.core.exceptions.TimeRangeException;
1713 import org.eclipse.tracecompass.statesystem.core.statevalue.ITmfStateValue;
1714 import org.eclipse.tracecompass.statesystem.core.statevalue.TmfStateValue;
1715 import org.eclipse.tracecompass.tmf.core.event.ITmfEvent;
1716 import org.eclipse.tracecompass.tmf.core.statesystem.AbstractTmfStateProvider;
1717 import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
1718 import org.eclipse.tracecompass.tmf.ctf.core.event.CtfTmfEvent;
1721 * Example state system provider.
1723 * @author Alexandre Montplaisir
1725 public class MyStateProvider extends AbstractTmfStateProvider {
1727 /** State value representing the idle state */
1728 public static ITmfStateValue IDLE = TmfStateValue.newValueInt(0);
1730 /** State value representing the running state */
1731 public static ITmfStateValue RUNNING = TmfStateValue.newValueInt(1);
1737 * The trace to which this state provider is associated
1739 public MyStateProvider(@NonNull ITmfTrace trace) {
1740 super(trace, "Example"); //$NON-NLS-1$
1742 * The second parameter here is not important, it's only used to name a
1743 * thread internally.
1748 public int getVersion() {
1750 * If the version of an existing file doesn't match the version supplied
1751 * in the provider, a rebuild of the history will be forced.
1757 public MyStateProvider getNewInstance() {
1758 return new MyStateProvider(getTrace());
1762 protected void eventHandle(ITmfEvent ev) {
1764 * AbstractStateChangeInput should have already checked for the correct
1767 CtfTmfEvent event = (CtfTmfEvent) ev;
1769 final long ts = event.getTimestamp().getValue();
1770 Integer nextTid = ((Long) event.getContent().getField("next_tid").getValue()).intValue();
1774 if (event.getType().getName().equals("sched_switch")) {
1775 ITmfStateSystemBuilder ss = checkNotNull(getStateSystemBuilder());
1776 int quark = ss.getQuarkAbsoluteAndAdd("CPUs", String.valueOf(event.getCPU()), "Status");
1777 ITmfStateValue value;
1783 ss.modifyAttribute(ts, value, quark);
1786 } catch (TimeRangeException e) {
1788 * This should not happen, since the timestamp comes from a trace
1791 throw new IllegalStateException(e);
1792 } catch (AttributeNotFoundException e) {
1794 * This should not happen either, since we're only accessing a quark
1797 throw new IllegalStateException(e);
1798 } catch (StateValueTypeException e) {
1800 * This wouldn't happen here, but could potentially happen if we try
1801 * to insert mismatching state value types in the same attribute.
1803 e.printStackTrace();
1811 === Analysis module definition ===
1814 import static org.eclipse.tracecompass.common.core.NonNullUtils.checkNotNull;
1816 import java.util.List;
1818 import org.eclipse.tracecompass.statesystem.core.exceptions.AttributeNotFoundException;
1819 import org.eclipse.tracecompass.statesystem.core.exceptions.StateSystemDisposedException;
1820 import org.eclipse.tracecompass.statesystem.core.exceptions.TimeRangeException;
1821 import org.eclipse.tracecompass.statesystem.core.interval.ITmfStateInterval;
1822 import org.eclipse.tracecompass.statesystem.core.statevalue.ITmfStateValue;
1823 import org.eclipse.tracecompass.tmf.core.statesystem.ITmfStateProvider;
1824 import org.eclipse.tracecompass.tmf.core.statesystem.TmfStateSystemAnalysisModule;
1825 import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
1828 * Class showing examples of a StateSystemAnalysisModule with state system queries.
1830 * @author Alexandre Montplaisir
1832 public class MyStateSystemAnalysisModule extends TmfStateSystemAnalysisModule {
1835 protected ITmfStateProvider createStateProvider() {
1836 ITmfTrace trace = checkNotNull(getTrace());
1837 return new MyStateProvider(trace);
1841 protected StateSystemBackendType getBackendType() {
1842 return StateSystemBackendType.FULL;
1846 * Example method of querying one attribute in the state system.
1848 * We pass it a cpu and a timestamp, and it returns us if that cpu was
1849 * executing a process (true/false) at that time.
1854 * The timestamp of the query
1855 * @return True if the CPU was running, false otherwise
1857 public boolean cpuIsRunning(int cpu, long timestamp) {
1859 int quark = getStateSystem().getQuarkAbsolute("CPUs", String.valueOf(cpu), "Status");
1860 ITmfStateValue value = getStateSystem().querySingleState(timestamp, quark).getStateValue();
1862 if (value.equals(MyStateProvider.RUNNING)) {
1867 * Since at this level we have no guarantee on the contents of the state
1868 * system, it's important to handle these cases correctly.
1870 } catch (AttributeNotFoundException e) {
1872 * Handle the case where the attribute does not exist in the state
1873 * system (no CPU with this number, etc.)
1875 } catch (TimeRangeException e) {
1877 * Handle the case where 'timestamp' is outside of the range of the
1880 } catch (StateSystemDisposedException e) {
1882 * Handle the case where the state system is being disposed. If this
1883 * happens, it's normally when shutting down, so the view can just
1884 * return immediately and wait it out.
1892 * Example method of using a full query.
1894 * We pass it a timestamp, and it returns us how many CPUs were executing a
1895 * process at that moment.
1898 * The target timestamp
1899 * @return The amount of CPUs that were running at that time
1901 public int getNbRunningCpus(long timestamp) {
1905 /* Get the list of the quarks we are interested in. */
1906 List<Integer> quarks = getStateSystem().getQuarks("CPUs", "*", "Status");
1909 * Get the full state at our target timestamp (it's better than
1910 * doing an arbitrary number of single queries).
1912 List<ITmfStateInterval> state = getStateSystem().queryFullState(timestamp);
1914 /* Look at the value of the state for each quark */
1915 for (Integer quark : quarks) {
1916 ITmfStateValue value = state.get(quark).getStateValue();
1917 if (value.equals(MyStateProvider.RUNNING)) {
1922 } catch (TimeRangeException e) {
1924 * Handle the case where 'timestamp' is outside of the range of the
1927 } catch (StateSystemDisposedException e) {
1928 /* Handle the case where the state system is being disposed. */
1935 == Mipmap feature ==
1937 The mipmap feature allows attributes to be inserted into the state system with
1938 additional computations performed to automatically store sub-attributes that
1939 can later be used for statistical operations. The mipmap has a resolution which
1940 represents the number of state attribute changes that are used to compute the
1941 value at the next mipmap level.
1943 The supported mipmap features are: max, min, and average. Each one of these
1944 features requires that the base attribute be a numerical state value (int, long
1945 or double). An attribute can be mipmapped for one or more of the features at
1948 To use a mipmapped attribute in queries, call the corresponding methods of the
1949 static class [[#State System Operations | TmfStateSystemOperations]].
1951 === AbstractTmfMipmapStateProvider ===
1953 AbstractTmfMipmapStateProvider is an abstract provider class that allows adding
1954 features to a specific attribute into a mipmap tree. It extends AbstractTmfStateProvider.
1956 If a provider wants to add mipmapped attributes to its tree, it must extend
1957 AbstractTmfMipmapStateProvider and call modifyMipmapAttribute() in the event
1958 handler, specifying one or more mipmap features to compute. Then the structure
1959 of the attribute tree will be :
1963 | |- <mipmapFeature> (min/max/avg)
1968 | | |- n (maximum mipmap level)
1969 | |- <mipmapFeature> (min/max/avg)
1974 | | |- n (maximum mipmap level)
1978 = UML2 Sequence Diagram Framework =
1980 The purpose of the UML2 Sequence Diagram Framework of TMF is to provide a framework for generation of UML2 sequence diagrams. It provides
1981 *UML2 Sequence diagram drawing capabilities (i.e. lifelines, messages, activations, object creation and deletion)
1982 *a generic, re-usable Sequence Diagram View
1983 *Eclipse Extension Point for the creation of sequence diagrams
1984 *callback hooks for searching and filtering within the Sequence Diagram View
1986 The following chapters describe the Sequence Diagram Framework as well as a reference implementation and its usage.
1988 == TMF UML2 Sequence Diagram Extensions ==
1990 In the UML2 Sequence Diagram Framework an Eclipse extension point is defined so that other plug-ins can contribute code to create sequence diagram.
1992 '''Identifier''': org.eclipse.linuxtools.tmf.ui.uml2SDLoader<br>
1993 '''Description''': This extension point aims to list and connect any UML2 Sequence Diagram loader.<br>
1994 '''Configuration Markup''':<br>
1997 <!ELEMENT extension (uml2SDLoader)+>
1999 point CDATA #REQUIRED
2005 *point - A fully qualified identifier of the target extension point.
2006 *id - An optional identifier of the extension instance.
2007 *name - An optional name of the extension instance.
2010 <!ELEMENT uml2SDLoader EMPTY>
2011 <!ATTLIST uml2SDLoader
2013 name CDATA #REQUIRED
2014 class CDATA #REQUIRED
2015 view CDATA #REQUIRED
2016 default (true | false)
2019 *id - A unique identifier for this uml2SDLoader. This is not mandatory as long as the id attribute cannot be retrieved by the provider plug-in. The class attribute is the one on which the underlying algorithm relies.
2020 *name - An name of the extension instance.
2021 *class - The implementation of this UML2 SD viewer loader. The class must implement org.eclipse.tracecompass.tmf.ui.views.uml2sd.load.IUml2SDLoader.
2022 *view - The view ID of the view that this loader aims to populate. Either org.eclipse.tracecompass.tmf.ui.views.uml2sd.SDView itself or a extension of org.eclipse.tracecompass.tmf.ui.views.uml2sd.SDView.
2023 *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.
2026 == Management of the Extension Point ==
2028 The TMF UI plug-in is responsible for evaluating each contribution to the extension point.
2031 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 | Using one Sequence Diagram View with Multiple Loaders]])
2033 == Sequence Diagram View ==
2035 For this extension point a Sequence Diagram View has to be defined as well. The Sequence Diagram View class implementation is provided by the plug-in ''org.eclipse.tracecompass.tmf.ui'' (''org.eclipse.tracecompass.tmf.ui.views.uml2sd.SDView'') and can be used as is or can also be sub-classed. For that, a view extension has to be added to the ''plugin.xml''.
2037 === Supported Widgets ===
2039 The loader class provides a frame containing all the UML2 widgets to be displayed. The following widgets exist:
2043 *Synchronous Message
2044 *Asynchronous Message
2045 *Synchronous Message Return
2046 *Asynchronous Message Return
2049 For a lifeline, a category can be defined. The lifeline category defines icons, which are displayed in the lifeline header.
2053 The Sequence Diagram View allows the user to zoom in, zoom out and reset the zoom factor.
2057 It is possible to print the whole sequence diagram as well as part of it.
2059 === Key Bindings ===
2061 *SHIFT+ALT+ARROW-DOWN - to scroll down within sequence diagram one view page at a time
2062 *SHIFT+ALT+ARROW-UP - to scroll up within sequence diagram one view page at a time
2063 *SHIFT+ALT+ARROW-RIGHT - to scroll right within sequence diagram one view page at a time
2064 *SHIFT+ALT+ARROW-LEFT - to scroll left within sequence diagram one view page at a time
2065 *SHIFT+ALT+ARROW-HOME - to jump to the beginning of the selected message if not already visible in page
2066 *SHIFT+ALT+ARROW-END - to jump to the end of the selected message if not already visible in page
2067 *CTRL+F - to open find dialog if either the basic or extended find provider is defined (see [[#Using the Find Provider Interface | Using the Find Provider Interface]])
2068 *CTRL+P - to open print dialog
2072 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:<br>
2073 [[Image:images/SeqDiagramPref.png]] <br>
2074 After changing the preferences select '''OK'''.
2076 === Callback hooks ===
2078 The Sequence Diagram View provides several callback hooks so that extension can provide application specific functionality. The following interfaces can be provided:
2079 * Basic find provider or extended find Provider<br> For finding within the sequence diagram
2080 * Basic filter provider and extended Filter Provider<br> For filtering within the sequnce diagram.
2081 * Basic paging provider or advanced paging provider<br> For scalability reasons, used to limit number of displayed messages
2082 * Properies provider<br> To provide properties of selected elements
2083 * Collapse provider <br> To collapse areas of the sequence diagram
2087 This tutorial describes how to create a UML2 Sequence Diagram Loader extension and use this loader in the in Eclipse.
2089 === Prerequisites ===
2091 The tutorial is based on Eclipse 4.4 (Eclipse Luna) and TMF 3.0.0.
2093 === Creating an Eclipse UI Plug-in ===
2095 To create a new project with name org.eclipse.tracecompass.tmf.sample.ui select '''File -> New -> Project -> Plug-in Development -> Plug-in Project'''. <br>
2096 [[Image:images/Screenshot-NewPlug-inProject1.png]]<br>
2098 [[Image:images/Screenshot-NewPlug-inProject2.png]]<br>
2100 [[Image:images/Screenshot-NewPlug-inProject3.png]]<br>
2102 === Creating a Sequence Diagram View ===
2104 To open the plug-in manifest, double-click on the MANIFEST.MF file. <br>
2105 [[Image:images/SelectManifest.png]]<br>
2107 Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-ins ''org.eclipse.tracecompass.tmf.ui'' and ''org.eclipse.tracecompass.tmf.core'' and then press '''OK'''<br>
2108 [[Image:images/AddDependencyTmfUi.png]]<br>
2110 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>
2111 [[Image:images/AddViewExtension1.png]]<br>
2113 To create a Sequence Diagram View, click the right mouse button. Then select '''New -> view'''<br>
2114 [[Image:images/AddViewExtension2.png]]<br>
2116 A new view entry has been created. Fill in the fields ''id'', ''name'' and ''class''. Note that for ''class'' the SD view implementation (''org.eclipse.tracecompass.tmf.ui.views.SDView'') of the TMF UI plug-in is used.<br>
2117 [[Image:images/FillSampleSeqDiagram.png]]<br>
2119 The view is prepared. Run the Example. To launch the an Eclipse Application select the ''Overview'' tab and click on '''Launch an Eclipse Application'''<br>
2120 [[Image:images/RunEclipseApplication.png]]<br>
2122 A new Eclipse application window will show. In the new window go to '''Windows -> Show View -> Other... -> Other -> Sample Sequence Diagram'''.<br>
2123 [[Image:images/ShowViewOther.png]]<br>
2125 The Sequence Diagram View will open with an blank page.<br>
2126 [[Image:images/BlankSampleSeqDiagram.png]]<br>
2128 Close the Example Application.
2130 === Defining the uml2SDLoader Extension ===
2132 After defining the Sequence Diagram View it's time to create the ''uml2SDLoader'' Extension. <br>
2134 To create the loader extension, change to the Extensions tab and select '''Add...''' of the ''All Extension'' section. A new dialog box will open. Find the extension ''org.eclipse.linuxtools.tmf.ui.uml2SDLoader'' and press '''Finish'''.<br>
2135 [[Image:images/AddTmfUml2SDLoader.png]]<br>
2137 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 | Creating a Sequence Diagram View]]. <br>
2138 [[Image:images/FillSampleLoader.png]]<br>
2140 Then click on ''class'' (see above) to open the new class dialog box. Fill in the relevant fields and select '''Finish'''. <br>
2141 [[Image:images/NewSampleLoaderClass.png]]<br>
2143 A new Java class will be created which implements the interface ''org.eclipse.tracecompass.tmf.ui.views.uml2sd.load.IUml2SDLoader''.<br>
2146 package org.eclipse.tracecompass.tmf.sample.ui;
2148 import org.eclipse.tracecompass.tmf.ui.views.uml2sd.SDView;
2149 import org.eclipse.tracecompass.tmf.ui.views.uml2sd.load.IUml2SDLoader;
2151 public class SampleLoader implements IUml2SDLoader {
2153 public SampleLoader() {
2154 // TODO Auto-generated constructor stub
2158 public void dispose() {
2159 // TODO Auto-generated method stub
2164 public String getTitleString() {
2165 // TODO Auto-generated method stub
2170 public void setViewer(SDView arg0) {
2171 // TODO Auto-generated method stub
2176 === Implementing the Loader Class ===
2178 Next is to implement the methods of the IUml2SDLoader interface method. The following code snippet shows how to create the major sequence diagram elements. Please note that no time information is stored.<br>
2181 package org.eclipse.tracecompass.tmf.sample.ui;
2183 import org.eclipse.tracecompass.tmf.ui.views.uml2sd.SDView;
2184 import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.AsyncMessage;
2185 import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.AsyncMessageReturn;
2186 import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.EllipsisMessage;
2187 import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.ExecutionOccurrence;
2188 import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.Frame;
2189 import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.Lifeline;
2190 import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.Stop;
2191 import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.SyncMessage;
2192 import org.eclipse.tracecompass.tmf.ui.views.uml2sd.core.SyncMessageReturn;
2193 import org.eclipse.tracecompass.tmf.ui.views.uml2sd.load.IUml2SDLoader;
2195 public class SampleLoader implements IUml2SDLoader {
2197 private SDView fSdView;
2199 public SampleLoader() {
2203 public void dispose() {
2207 public String getTitleString() {
2208 return "Sample Diagram";
2212 public void setViewer(SDView arg0) {
2217 private void createFrame() {
2219 Frame testFrame = new Frame();
2220 testFrame.setName("Sample Frame");
2226 Lifeline lifeLine1 = new Lifeline();
2227 lifeLine1.setName("Object1");
2228 testFrame.addLifeLine(lifeLine1);
2230 Lifeline lifeLine2 = new Lifeline();
2231 lifeLine2.setName("Object2");
2232 testFrame.addLifeLine(lifeLine2);
2236 * Create Sync Message
2238 // Get new occurrence on lifelines
2239 lifeLine1.getNewEventOccurrence();
2241 // Get Sync message instances
2242 SyncMessage start = new SyncMessage();
2243 start.setName("Start");
2244 start.setEndLifeline(lifeLine1);
2245 testFrame.addMessage(start);
2248 * Create Sync Message
2250 // Get new occurrence on lifelines
2251 lifeLine1.getNewEventOccurrence();
2252 lifeLine2.getNewEventOccurrence();
2254 // Get Sync message instances
2255 SyncMessage syn1 = new SyncMessage();
2256 syn1.setName("Sync Message 1");
2257 syn1.setStartLifeline(lifeLine1);
2258 syn1.setEndLifeline(lifeLine2);
2259 testFrame.addMessage(syn1);
2262 * Create corresponding Sync Message Return
2265 // Get new occurrence on lifelines
2266 lifeLine1.getNewEventOccurrence();
2267 lifeLine2.getNewEventOccurrence();
2269 SyncMessageReturn synReturn1 = new SyncMessageReturn();
2270 synReturn1.setName("Sync Message Return 1");
2271 synReturn1.setStartLifeline(lifeLine2);
2272 synReturn1.setEndLifeline(lifeLine1);
2273 synReturn1.setMessage(syn1);
2274 testFrame.addMessage(synReturn1);
2277 * Create Activations (Execution Occurrence)
2279 ExecutionOccurrence occ1 = new ExecutionOccurrence();
2280 occ1.setStartOccurrence(start.getEventOccurrence());
2281 occ1.setEndOccurrence(synReturn1.getEventOccurrence());
2282 lifeLine1.addExecution(occ1);
2283 occ1.setName("Activation 1");
2285 ExecutionOccurrence occ2 = new ExecutionOccurrence();
2286 occ2.setStartOccurrence(syn1.getEventOccurrence());
2287 occ2.setEndOccurrence(synReturn1.getEventOccurrence());
2288 lifeLine2.addExecution(occ2);
2289 occ2.setName("Activation 2");
2292 * Create Sync Message
2294 // Get new occurrence on lifelines
2295 lifeLine1.getNewEventOccurrence();
2296 lifeLine2.getNewEventOccurrence();
2298 // Get Sync message instances
2299 AsyncMessage asyn1 = new AsyncMessage();
2300 asyn1.setName("Async Message 1");
2301 asyn1.setStartLifeline(lifeLine1);
2302 asyn1.setEndLifeline(lifeLine2);
2303 testFrame.addMessage(asyn1);
2306 * Create corresponding Sync Message Return
2309 // Get new occurrence on lifelines
2310 lifeLine1.getNewEventOccurrence();
2311 lifeLine2.getNewEventOccurrence();
2313 AsyncMessageReturn asynReturn1 = new AsyncMessageReturn();
2314 asynReturn1.setName("Async Message Return 1");
2315 asynReturn1.setStartLifeline(lifeLine2);
2316 asynReturn1.setEndLifeline(lifeLine1);
2317 asynReturn1.setMessage(asyn1);
2318 testFrame.addMessage(asynReturn1);
2324 // Get new occurrence on lifelines
2325 lifeLine1.getNewEventOccurrence();
2327 EllipsisMessage info = new EllipsisMessage();
2328 info.setName("Object deletion");
2329 info.setStartLifeline(lifeLine2);
2330 testFrame.addNode(info);
2335 Stop stop = new Stop();
2336 stop.setLifeline(lifeLine2);
2337 stop.setEventOccurrence(lifeLine2.getNewEventOccurrence());
2338 lifeLine2.addNode(stop);
2340 fSdView.setFrame(testFrame);
2345 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'''<br>
2346 [[Image:images/SampleDiagram1.png]] <br>
2348 === Adding time information ===
2350 To add time information in sequence diagram the timestamp has to be set for each message. The sequence diagram framework uses the ''TmfTimestamp'' class of plug-in ''org.eclipse.tracecompass.tmf.core''. Use ''setTime()'' on each message ''SyncMessage'' since start and end time are the same. For each ''AsyncMessage'' set start and end time separately by using methods ''setStartTime'' and ''setEndTime''. For example: <br>
2353 private void createFrame() {
2355 start.setTime(TmfTimestamp.create(1000, -3));
2356 syn1.setTime(TmfTimestamp.create(1005, -3));
2357 synReturn1.setTime(TmfTimestamp.create(1050, -3));
2358 asyn1.setStartTime(TmfTimestamp.create(1060, -3));
2359 asyn1.setEndTime(TmfTimestamp.create(1070, -3));
2360 asynReturn1.setStartTime(TmfTimestamp.create(1060, -3));
2361 asynReturn1.setEndTime(TmfTimestamp.create(1070, -3));
2366 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. <br>
2368 [[Image:images/SampleDiagramTimeComp.png]] <br>
2370 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.
2372 [[Image:images/SampleDiagramSyncMessage.png]] <br>
2373 [[Image:images/SampleDiagramAsyncMessage.png]] <br>
2375 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 ''AsyncMessage'' the end time is used for the delta calculation.<br>
2376 [[Image:images/SampleDiagramMessageDelta.png]] <br>
2378 === Default Coolbar and Menu Items ===
2380 The Sequence Diagram View comes with default coolbar and menu items. By default, each sequence diagram shows the following actions:
2385 * Configure Min Max (drop-down menu only)
2386 * Navigation -> Show the node end (drop-down menu only)
2387 * Navigation -> Show the node start (drop-down menu only)
2389 [[Image:images/DefaultCoolbarMenu.png]]<br>
2391 === Implementing Optional Callbacks ===
2393 The following chapters describe how to use all supported provider interfaces.
2395 ==== Using the Paging Provider Interface ====
2397 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.
2399 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.
2402 public class SampleLoader implements IUml2SDLoader, ISDPagingProvider {
2404 private int page = 0;
2407 public void dispose() {
2408 if (fSdView != null) {
2409 fSdView.resetProviders();
2414 public void setViewer(SDView arg0) {
2416 fSdView.setSDPagingProvider(this);
2420 private void createSecondFrame() {
2421 Frame testFrame = new Frame();
2422 testFrame.setName("SecondFrame");
2423 Lifeline lifeline = new Lifeline();
2424 lifeline.setName("LifeLine 0");
2425 testFrame.addLifeLine(lifeline);
2426 lifeline = new Lifeline();
2427 lifeline.setName("LifeLine 1");
2428 testFrame.addLifeLine(lifeline);
2429 for (int i = 1; i < 5; i++) {
2430 SyncMessage message = new SyncMessage();
2431 message.autoSetStartLifeline(testFrame.getLifeline(0));
2432 message.autoSetEndLifeline(testFrame.getLifeline(0));
2433 message.setName((new StringBuilder("Message ")).append(i).toString());
2434 testFrame.addMessage(message);
2436 SyncMessageReturn messageReturn = new SyncMessageReturn();
2437 messageReturn.autoSetStartLifeline(testFrame.getLifeline(0));
2438 messageReturn.autoSetEndLifeline(testFrame.getLifeline(0));
2440 testFrame.addMessage(messageReturn);
2441 messageReturn.setName((new StringBuilder("Message return ")).append(i).toString());
2442 ExecutionOccurrence occ = new ExecutionOccurrence();
2443 occ.setStartOccurrence(testFrame.getSyncMessage(i - 1).getEventOccurrence());
2444 occ.setEndOccurrence(testFrame.getSyncMessageReturn(i - 1).getEventOccurrence());
2445 testFrame.getLifeline(0).addExecution(occ);
2447 fSdView.setFrame(testFrame);
2451 public boolean hasNextPage() {
2456 public boolean hasPrevPage() {
2461 public void nextPage() {
2463 createSecondFrame();
2467 public void prevPage() {
2473 public void firstPage() {
2479 public void lastPage() {
2481 createSecondFrame();
2488 When running the example application, new actions will be shown in the coolbar and the coolbar menu. <br>
2490 [[Image:images/PageProviderAdded.png]]
2493 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.
2496 ==== Using the Find Provider Interface ====
2498 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 criteria as regular expressions. This find criteria can be used to execute the find. Find criteria a persisted in the Eclipse workspace.
2500 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.
2502 Only on at a time can be active. If the extended find provder is defined it obsoletes the basic find provider.
2504 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.
2507 public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider {
2511 public void dispose() {
2512 if (fSdView != null) {
2513 fSdView.resetProviders();
2518 public void setViewer(SDView arg0) {
2520 fSdView.setSDPagingProvider(this);
2521 fSdView.setSDFindProvider(this);
2526 public boolean isNodeSupported(int nodeType) {
2528 case ISDGraphNodeSupporter.LIFELINE:
2529 case ISDGraphNodeSupporter.SYNCMESSAGE:
2539 public String getNodeName(int nodeType, String loaderClassName) {
2541 case ISDGraphNodeSupporter.LIFELINE:
2543 case ISDGraphNodeSupporter.SYNCMESSAGE:
2544 return "Sync Message";
2550 public boolean find(Criteria criteria) {
2551 Frame frame = fSdView.getFrame();
2552 if (criteria.isLifeLineSelected()) {
2553 for (int i = 0; i < frame.lifeLinesCount(); i++) {
2554 if (criteria.matches(frame.getLifeline(i).getName())) {
2555 fSdView.getSDWidget().moveTo(frame.getLifeline(i));
2560 if (criteria.isSyncMessageSelected()) {
2561 for (int i = 0; i < frame.syncMessageCount(); i++) {
2562 if (criteria.matches(frame.getSyncMessage(i).getName())) {
2563 fSdView.getSDWidget().moveTo(frame.getSyncMessage(i));
2572 public void cancel() {
2573 // reset find parameters
2579 When running the example application, the find action will be shown in the coolbar and the coolbar menu. <br>
2580 [[Image:images/FindProviderAdded.png]]
2582 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. <br>
2583 [[Image:images/FindDialog.png]]<br>
2585 Note that the find dialog will be opened by typing the key shortcut CRTL+F.
2587 ==== Using the Filter Provider Interface ====
2589 For filtering of sequence diagram elements two interfaces exist. One basic for filtering and one for extended filtering. The basic filtering comes with two dialog for entering filter criteria as regular expressions and one for selecting the filter to be used. Multiple filters can be active at a time. Filter criteria are persisted in the Eclipse workspace.
2591 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. <br>
2592 Note that no example implementation of ''filter()'' is provided.
2596 public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider {
2600 public void dispose() {
2601 if (fSdView != null) {
2602 fSdView.resetProviders();
2607 public void setViewer(SDView arg0) {
2609 fSdView.setSDPagingProvider(this);
2610 fSdView.setSDFindProvider(this);
2611 fSdView.setSDFilterProvider(this);
2616 public boolean filter(List<FilterCriteria> list) {
2623 When running the example application, the filter action will be shown in the coolbar menu. <br>
2624 [[Image:images/HidePatternsMenuItem.png]]
2626 To filter select the '''Hide Patterns...''' of the coolbar menu. A new dialog box will open. <br>
2627 [[Image:images/DialogHidePatterns.png]]
2629 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''''. <br>
2630 [[Image:images/DialogHidePatterns.png]] <br>
2632 Now back at the Hide Pattern dialog. Select one or more filter and select '''OK'''.
2634 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.
2636 ==== Using the Extended Action Bar Provider Interface ====
2638 The extended action bar provider can be used to add customized actions to the Sequence Diagram View.
2639 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. <br>
2642 public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider, ISDExtendedActionBarProvider {
2646 public void dispose() {
2647 if (fSdView != null) {
2648 fSdView.resetProviders();
2653 public void setViewer(SDView arg0) {
2655 fSdView.setSDPagingProvider(this);
2656 fSdView.setSDFindProvider(this);
2657 fSdView.setSDFilterProvider(this);
2658 fSdView.setSDExtendedActionBarProvider(this);
2663 public void supplementCoolbarContent(IActionBars iactionbars) {
2664 Action action = new Action("Refresh") {
2667 System.out.println("Refreshing...");
2670 iactionbars.getMenuManager().add(action);
2671 iactionbars.getToolBarManager().add(action);
2677 When running the example application, all new actions will be added to the coolbar and coolbar menu according to the implementation of ''supplementCoolbarContent()''<br>.
2678 For the example above the coolbar and coolbar menu will look as follows.
2680 [[Image:images/SupplCoolbar.png]]
2682 ==== Using the Properties Provider Interface====
2684 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. <br>
2686 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.
2688 Please refer to the following Eclipse articles for more information about properties and tabed properties.
2689 *[http://www.eclipse.org/articles/Article-Properties-View/properties-view.html | Take control of your properties]
2690 *[http://www.eclipse.org/articles/Article-Tabbed-Properties/tabbed_properties_view.html | The Eclipse Tabbed Properties View]
2692 ==== Using the Collapse Provider Interface ====
2694 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.
2696 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.
2698 ==== Using the Selection Provider Service ====
2700 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.
2703 public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider, ISDExtendedActionBarProvider, ISelectionListener {
2707 public void dispose() {
2708 if (fSdView != null) {
2709 PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().removePostSelectionListener(this);
2710 fSdView.resetProviders();
2715 public String getTitleString() {
2716 return "Sample Diagram";
2720 public void setViewer(SDView arg0) {
2722 PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().addPostSelectionListener(this);
2723 fSdView.setSDPagingProvider(this);
2724 fSdView.setSDFindProvider(this);
2725 fSdView.setSDFilterProvider(this);
2726 fSdView.setSDExtendedActionBarProvider(this);
2732 public void selectionChanged(IWorkbenchPart part, ISelection selection) {
2733 ISelection sel = PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().getSelection();
2734 if (sel != null && (sel instanceof StructuredSelection)) {
2735 StructuredSelection stSel = (StructuredSelection) sel;
2736 if (stSel.getFirstElement() instanceof BaseMessage) {
2737 BaseMessage syncMsg = ((BaseMessage) stSel.getFirstElement());
2738 System.out.println("Message '" + syncMsg.getName() + "' selected.");
2747 === Printing a Sequence Diagram ===
2749 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. <br>
2751 [[Image:images/PrintDialog.png]] <br>
2753 Fill in all the relevant information, select '''Printer...''' to choose the printer and the press '''OK'''.
2755 === Using one Sequence Diagram View with Multiple Loaders ===
2757 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:
2760 public class OpenSDView extends AbstractHandler {
2762 public Object execute(ExecutionEvent event) throws ExecutionException {
2764 IWorkbenchPage persp = TmfUiPlugin.getDefault().getWorkbench().getActiveWorkbenchWindow().getActivePage();
2765 SDView view = (SDView) persp.showView("org.eclipse.linuxtools.ust.examples.ui.componentinteraction");
2766 LoadersManager.getLoadersManager().createLoader("org.eclipse.tracecompass.tmf.ui.views.uml2sd.impl.TmfUml2SDSyncLoader", view);
2767 } catch (PartInitException e) {
2768 throw new ExecutionException("PartInitException caught: ", e);
2775 === Downloading the Tutorial ===
2777 Use the following link to download the source code of the tutorial [https://wiki.eclipse.org/images/7/79/SamplePluginTC.zip Plug-in of Tutorial].
2779 == Integration of Tracing and Monitoring Framework with Sequence Diagram Framework ==
2781 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.
2783 === Reference Implementation ===
2785 A Sequence Diagram View Extension is defined in the plug-in TMF UI as well as a uml2SDLoader Extension with the reference loader.
2787 [[Image:images/ReferenceExtensions.png]]
2789 === Used Sequence Diagram Features ===
2791 Besides the default features of the Sequence Diagram Framework, the reference implementation uses the following additional features:
2797 ==== Advanced paging ====
2799 The reference loader implements the interface ''ISDAdvancedPagingProvider'' interface. Please refer to section [[#Using the Paging Provider Interface | Using the Paging Provider Interface]] for more details about the advanced paging feature.
2801 ==== Basic finding ====
2803 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 | Using the Find Provider Interface]] for more details about the basic find feature.
2805 ==== Basic filtering ====
2807 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 | Using the Filter Provider Interface]] for more details about the basic filter feature.
2809 ==== Selection Service ====
2811 The reference loader implements the interface ''ISelectionListener'' interface. When an interaction is selected a ''TmfTimeSynchSignal'' is broadcast (see [[#TMF Signal Framework | TMF Signal Framework]]). Please also refer to section [[#Using the Selection Provider Service | Using the Selection Provider Service]] for more details about the selection service and .
2813 === Used TMF Features ===
2815 The reference implementation uses the following features of TMF:
2816 *TMF Experiment and Trace for accessing traces
2817 *Event Request Framework to request TMF events from the experiment and respective traces
2818 *Signal Framework for broadcasting and receiving TMF signals for synchronization purposes
2820 ==== TMF Experiment and Trace for accessing traces ====
2822 The reference loader uses TMF Experiments to access traces and to request data from the traces.
2824 ==== TMF Event Request Framework ====
2826 The reference loader use the TMF Event Request Framework to request events from the experiment and its traces.
2828 When opening a trace (which is triggered by signal ''TmfTraceSelectedSignal'') or when opening the Sequence Diagram View after a trace had been opened previously, a TMF background request is initiated to index the trace and to fill in the first page of the sequence diagram. The purpose of the indexing is to store time ranges for pages with 10000 messages per page. This allows quickly to move to certain pages in a trace without having to re-parse from the beginning. The request is called indexing request.
2830 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.
2832 A third type of event request is issued for finding specific data across pages.
2834 ==== TMF Signal Framework ====
2836 The reference loader extends the class ''TmfComponent''. By doing that the loader is registered as a TMF signal handler for sending and receiving TMF signals. The loader implements signal handlers for the following TMF signals:
2837 *''TmfTraceSelectedSignal''
2838 This signal indicates that a trace or experiment was selected. When receiving this signal the indexing request is initiated and the first page is displayed after receiving the relevant information.
2839 *''TmfTraceClosedSignal''
2840 This signal indicates that a trace or experiment was closed. When receiving this signal the loader resets its data and a blank page is loaded in the Sequence Diagram View.
2841 *''TmfTimeSynchSignal''
2842 This signal is used to indicate that a new time or time range has been selected. It contains a begin and end time. If a single time is selected then the begin and end time are the same. When receiving this signal the corresponding message matching the begin time is selected in the Sequence Diagram View. If necessary, the page is changed.
2843 *''TmfRangeSynchSignal''
2844 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.
2846 Besides acting on receiving signals, the reference loader is also sending signals. A ''TmfTimeSynchSignal'' is broadcasted with the timestamp 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''.
2848 === Supported Traces ===
2850 The reference implementation is able to analyze traces from a single component that traces the interaction with 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.<br>
2852 Note that combined traces of multiple components, that contain the trace information about the same interactions are not supported in the reference implementation!
2854 === Trace Format ===
2856 The reference implementation in class ''TmfUml2SDSyncLoader'' in package ''org.eclipse.tracecompass.tmf.ui.views.uml2sd.impl'' analyzes events from type ''ITmfEvent'' and creates events type ''ITmfSyncSequenceDiagramEvent'' if the ''ITmfEvent'' contains all relevant information information. The parsing algorithm looks like as follows:
2860 * @param tmfEvent Event to parse for sequence diagram event details
2861 * @return sequence diagram event if details are available else null
2863 protected ITmfSyncSequenceDiagramEvent getSequenceDiagramEvent(ITmfEvent tmfEvent){
2864 //type = .*RECEIVE.* or .*SEND.*
2865 //content = sender:<sender name>:receiver:<receiver name>,signal:<signal name>
2866 String eventType = tmfEvent.getType().toString();
2867 if (eventType.contains(Messages.TmfUml2SDSyncLoader_EventTypeSend) || eventType.contains(Messages.TmfUml2SDSyncLoader_EventTypeReceive)) {
2868 Object sender = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncLoader_FieldSender);
2869 Object receiver = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncLoader_FieldReceiver);
2870 Object name = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncLoader_FieldSignal);
2871 if ((sender instanceof ITmfEventField) && (receiver instanceof ITmfEventField) && (name instanceof ITmfEventField)) {
2872 ITmfSyncSequenceDiagramEvent sdEvent = new TmfSyncSequenceDiagramEvent(tmfEvent,
2873 ((ITmfEventField) sender).getValue().toString(),
2874 ((ITmfEventField) receiver).getValue().toString(),
2875 ((ITmfEventField) name).getValue().toString());
2884 The analysis looks for event type Strings containing ''SEND'' and ''RECEIVE''. If event type matches these key words, the analyzer will look for strings ''sender'', ''receiver'' and ''signal'' in the event fields of type ''ITmfEventField''. If all the data is found a sequence diagram event can be created using this information. Note that Sync Messages are assumed, which means start and end time are the same.
2886 === How to use the Reference Implementation ===
2888 An example CTF (Common Trace Format) trace is provided that contains trace events with sequence diagram information. To download the reference trace, use the following link: [https://wiki.eclipse.org/images/3/35/ReferenceTrace.zip Reference Trace].
2890 Run an Eclipse application with Trace Compass 0.1.0 or later installed. To open the Reference Sequence Diagram View, select '''Windows -> Show View -> Other... -> Tracing -> Sequence Diagram''' <br>
2891 [[Image:images/ShowTmfSDView.png]]<br>
2893 A blank Sequence Diagram View will open.
2895 Then import the reference trace to the '''Project Explorer''' using the '''Import Trace Package...''' menu option.<br>
2896 [[Image:images/ImportTracePackage.png]]
2898 Next, open the trace by double-clicking on the trace element in the '''Project Explorer'''. The trace will be opened and the Sequence Diagram view will be filled.
2899 [[Image:images/ReferenceSeqDiagram.png]]<br>
2901 Now the reference implementation can be explored. To demonstrate the view features try the following things:
2902 *Select a message in the Sequence diagram. As result the corresponding event will be selected in the Events View.
2903 *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.
2904 *In the Events View, press key ''End''. As result, the Sequence Diagram view will jump to the last page.
2905 *In the Events View, press key ''Home''. As result, the Sequence Diagram view will jump to the first page.
2906 *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.
2907 * 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.<br>
2909 === Extending the Reference Loader ===
2911 In some case it might be necessary to change the implementation of the analysis of each ''TmfEvent'' for the generation of ''Sequence Diagram Events''. For that just extend the class ''TmfUml2SDSyncLoader'' and overwrite the method ''protected ITmfSyncSequenceDiagramEvent getSequenceDiagramEvent(ITmfEvent tmfEvent)'' with your own implementation.
2916 CTF is a format used to store traces. It is self defining, binary and made to be easy to write to.
2917 Before going further, the full specification of the CTF file format can be found at http://www.efficios.com/ .
2919 For the purpose of the reader some basic description will be given. A CTF trace typically is made of several files all in the same folder.
2921 These files can be split into two types :
2926 The metadata is either raw text or packetized text. It is TSDL encoded. it contains a description of the type of data in the event streams. It can grow over time if new events are added to a trace but it will never overwrite what is already there.
2928 === Event Streams ===
2929 The event streams are a file per stream per cpu. These streams are binary and packet based. The streams store events and event information (ie lost events) The event data is stored in headers and field payloads.
2931 So if you have two streams (channels) "channel1" and "channel2" and 4 cores, you will have the following files in your trace directory: "channel1_0" , "channel1_1" , "channel1_2" , "channel1_3" , "channel2_0" , "channel2_1" , "channel2_2" & "channel2_3"
2933 == Reading a trace ==
2934 In order to read a CTF trace, two steps must be done.
2935 * The metadata must be read to know how to read the events.
2936 * the events must be read.
2938 The metadata is a written in a subset of the C language called TSDL. To read it, first it is depacketized (if it is not in plain text) then the raw text is parsed by an antlr grammar. The parsing is done in two phases. There is a lexer (CTFLexer.g) which separated the metatdata text into tokens. The tokens are then pattern matched using the parser (CTFParser.g) to form an AST. This AST is walked through using "IOStructGen.java" to populate streams and traces in trace parent object.
2940 When the metadata is loaded and read, the trace object will be populated with 3 items:
2941 * the event definitions available per stream: a definition is a description of the datatype.
2942 * the event declarations available per stream: this will save declaration creation on a per event basis. They will all be created in advance, just not populated.
2943 * the beginning of a packet index.
2945 Now all the trace readers for the event streams have everything they need to read a trace. They will each point to one file, and read the file from packet to packet. Every time the trace reader changes packet, the index is updated with the new packet's information. The readers are in a priority queue and sorted by timestamp. This ensures that the events are read in a sequential order. They are also sorted by file name so that in the eventuality that two events occur at the same time, they stay in the same order.
2947 == Seeking in a trace ==
2948 The reason for maintaining an index is to speed up seeks. In the case that a user wishes to seek to a certain timestamp, they just have to find the index entry that contains the timestamp, and go there to iterate in that packet until the proper event is found. this will reduce the searches time by an order of 8000 for a 256k packet size (kernel default).
2950 == Interfacing to TMF ==
2951 The trace can be read easily now but the data is still awkward to extract.
2954 A location in a given trace, it is currently the timestamp of a trace and the index of the event. The index shows for a given timestamp if it is the first second or nth element.
2957 The CtfTmfTrace is a wrapper for the standard CTF trace that allows it to perform the following actions:
2958 * '''initTrace()''' create a trace
2959 * '''validateTrace()''' is the trace a CTF trace?
2960 * '''getLocationRatio()''' how far in the trace is my location?
2961 * '''seekEvent()''' sets the cursor to a certain point in a trace.
2962 * '''readNextEvent()''' reads the next event and then advances the cursor
2963 * '''getTraceProperties()''' gets the 'env' structures of the metadata
2966 The CtfIterator is a wrapper to the CTF file reader. It behaves like an iterator on a trace. However, it contains a file pointer and thus cannot be duplicated too often or the system will run out of file handles. To alleviate the situation, a pool of iterators is created at the very beginning and stored in the CtfTmfTrace. They can be retried by calling the GetIterator() method.
2968 === CtfIteratorManager ===
2969 Since each CtfIterator will have a file reader, the OS will run out of handles if too many iterators are spawned. The solution is to use the iterator manager. This will allow the user to get an iterator. If there is a context at the requested position, the manager will return that one, if not, a context will be selected at random and set to the correct location. Using random replacement minimizes contention as it will settle quickly at a new balance point.
2971 === CtfTmfContext ===
2972 The CtfTmfContext implements the ITmfContext type. It is the CTF equivalent of TmfContext. It has a CtfLocation and points to an iterator in the CtfTmfTrace iterator pool as well as the parent trace. it is made to be cloned easily and not affect system resources much. Contexts behave much like C file pointers (FILE*) but they can be copied until one runs out of RAM.
2974 === CtfTmfTimestamp ===
2975 The CtfTmfTimestamp take a CTF time (normally a long int) and outputs the time formats it as a TmfTimestamp, allowing it to be compared to other timestamps. The time is stored with the UTC offset already applied. It also features a simple toString() function that allows it to output the time in more Human readable ways: "yyyy/mm/dd/hh:mm:ss.nnnnnnnnn ns" for example. An additional feature is the getDelta() function that allows two timestamps to be substracted, showing the time difference between A and B.
2978 The CtfTmfEvent is an ITmfEvent that is used to wrap event declarations and event definitions from the CTF side into easier to read and parse chunks of information. It is a final class with final fields made to be newed very often without incurring performance costs. Most of the information is already available. It should be noted that one type of event can appear called "lost event" these are synthetic events that do not exist in the trace. They will not appear in other trace readers such as babeltrace.
2981 There are other helper files that format given events for views, they are simpler and the architecture does not depend on them.
2984 For the moment live CTF trace reading is not supported.
2986 = Event matching and trace synchronization =
2988 Event matching consists in taking an event from a trace and linking it to another event in a possibly different trace. The example that comes to mind is matching network packets sent from one traced machine to another traced machine. These matches can be used to synchronize traces.
2990 Trace synchronization consists in taking traces, taken on different machines, with a different time reference, and finding the formula to transform the timestamps of some of the traces, so that they all have the same time reference.
2992 == Event matching interfaces ==
2994 Here's a description of the major parts involved in event matching. These classes are all in the ''org.eclipse.tracecompass.tmf.core.event.matching'' package:
2996 * '''ITmfEventMatching''': Controls the event matching process
2997 * '''ITmfMatchEventDefinition''': Describes how events are matched
2998 * '''IMatchProcessingUnit''': Processes the matched events
3000 == Implementation details and how to extend it ==
3002 === ITmfEventMatching interface and derived classes ===
3004 This interface controls the event matching itself. Their only public method is ''matchEvents''. The implementing classes needs to manage how to setup the traces, and any initialization or finalization procedures.
3006 The is one concrete implementation of this interface: '''TmfEventMatching'''. It makes a request on the traces and match events where a ''cause'' event can be uniquely matched with a ''effect'' event. It creates a '''TmfEventDependency''' between the source and destination events. The dependency is added to the processing unit.
3008 To match events requiring other mechanisms (for instance, a series of events can be matched with another series of events), one would need to add another class either implementing '''ITmfEventMatching'''. It would most probably also require a new '''ITmfMatchEventDefinition''' implementation.
3010 === ITmfMatchEventDefinition interface and its derived classes ===
3012 These are the classes that describe how to actually match specific events together.
3014 The '''canMatchTrace''' method will tell if a definition is compatible with a given trace.
3016 The '''getEventKey''' method will return a key for an event that uniquely identifies this event and will match the key from another event.
3018 The '''getDirection''' method indicates whether this event is a ''cause'' or ''effect'' event to be matched with one from the opposite direction.
3020 As examples, two concrete network match definitions have been implemented in the ''org.eclipse.tracecompass.internal.lttng2.kernel.core.event.matching'' package for two compatible methods of matching TCP packets (See the Trace Compass User Guide on ''trace synchronization'' for information on those matching methods). Each one tells which events need to be present in the metadata of a CTF trace for this matching method to be applicable. It also returns the field values from each event that will uniquely match 2 events together.
3022 Each '''IMatchEventDefinition''' needs to be registered to the '''TmfEventMatching''' class using the following code for example
3025 TmfEventMatching.registerMatchObject(new TcpEventMatching());
3028 === IMatchProcessingUnit interface and derived classes ===
3030 While matching events is an exercise in itself, it's what to do with the match that really makes this functionality interesting. This is the job of the '''IMatchProcessingUnit''' interface.
3032 '''TmfEventMatches''' provides a default implementation that only stores the matches to count them. When a new match is obtained, the ''addMatch'' is called with the match and the processing unit can do whatever needs to be done with it.
3034 A match processing unit can be an analysis in itself. For example, trace synchronization is done through such a processing unit. One just needs to set the processing unit in the TmfEventMatching constructor.
3038 === Using network packets matching in an analysis ===
3040 This example shows how one can create a processing unit inline to create a link between two events. In this example, the code already uses an event request, so there is no need here to call the ''matchEvents'' method, that will only create another request.
3043 class MyAnalysis extends TmfAbstractAnalysisModule {
3045 private TmfNetworkEventMatching tcpMatching;
3049 protected void executeAnalysis() {
3051 IMatchProcessingUnit matchProcessing = new IMatchProcessingUnit() {
3053 public void matchingEnded() {
3057 public void init(ITmfTrace[] fTraces) {
3061 public int countMatches() {
3066 public void addMatch(TmfEventDependency match) {
3067 log.debug("we got a tcp match! " + match.getSourceEvent().getContent() + " " + match.getDestinationEvent().getContent());
3068 TmfEvent source = match.getSourceEvent();
3069 TmfEvent destination = match.getDestinationEvent();
3070 /* Create a link between the two events */
3074 ITmfTrace[] traces = { getTrace() };
3075 tcpMatching = new TmfEventMatching(traces, matchProcessing);
3076 tcpMatching.initMatching();
3078 MyEventRequest request = new MyEventRequest(this, i);
3079 getTrace().sendRequest(request);
3082 public void analyzeEvent(TmfEvent event) {
3084 tcpMatching.matchEvent(event, 0);
3092 class MyEventRequest extends TmfEventRequest {
3094 private final MyAnalysis analysis;
3096 MyEventRequest(MyAnalysis analysis, int traceno) {
3097 super(CtfTmfEvent.class,
3098 TmfTimeRange.ETERNITY,
3100 TmfDataRequest.ALL_DATA,
3101 ITmfDataRequest.ExecutionType.FOREGROUND);
3102 this.analysis = analysis;
3106 public void handleData(final ITmfEvent event) {
3107 super.handleData(event);
3108 if (event != null) {
3109 analysis.analyzeEvent(event);
3115 === Match events from UST traces ===
3117 Suppose a client-server application is instrumented using LTTng-UST. Traces are collected on the server and some clients on different machines. The traces can be synchronized using network event matching.
3119 The following metadata describes the events:
3123 name = "myapp:send";
3128 integer { size = 32; align = 8; signed = 1; encoding = none; base = 10; } _sendto;
3129 integer { size = 64; align = 8; signed = 1; encoding = none; base = 10; } _messageid;
3130 integer { size = 64; align = 8; signed = 1; encoding = none; base = 10; } _data;
3135 name = "myapp:receive";
3140 integer { size = 32; align = 8; signed = 1; encoding = none; base = 10; } _from;
3141 integer { size = 64; align = 8; signed = 1; encoding = none; base = 10; } _messageid;
3142 integer { size = 64; align = 8; signed = 1; encoding = none; base = 10; } _data;
3147 One would need to write an event match definition for those 2 events as follows:
3150 public class MyAppUstEventMatching implements ITmfMatchEventDefinition {
3152 public class MyEventMatchingKey implements IEventMatchingKey {
3154 private static final HashFunction HF = checkNotNull(Hashing.goodFastHash(32));
3155 private final int fTo;
3156 private final long fId;
3158 public MyEventMatchingKey(int to, long id) {
3164 public int hashCode() {
3165 return HF.newHasher()
3167 .putLong(fId).hash().asInt();
3171 public boolean equals(@Nullable Object o) {
3172 if (o instanceof MyEventMatchingKey) {
3173 MyEventMatchingKey key = (MyEventMatchingKey) o;
3174 return (key.fTo == fTo &&
3183 public Direction getDirection(ITmfEvent event) {
3184 String evname = event.getType().getName();
3185 if (evname.equals("myapp:receive")) {
3186 return Direction.EFFECT;
3187 } else if (evname.equals("myapp:send")) {
3188 return Direction.CAUSE;
3194 public IEventMatchingKey getEventKey(ITmfEvent event) {
3195 IEventMatchingKey key;
3197 if (evname.equals("myapp:receive")) {
3198 key = new MyEventMatchingKey(event.getContent().getField("from").getValue(),
3199 event.getContent().getField("messageid").getValue());
3201 key = new MyEventMatchingKey(event.getContent().getField("sendto").getValue(),
3202 event.getContent().getField("messageid").getValue());
3209 public boolean canMatchTrace(ITmfTrace trace) {
3210 Set<String> events = ImmutableSet.of("myapp:receive", "myapp:send");
3211 if (!(trace instanceof ITmfTraceWithPreDefinedEvents)) {
3214 ITmfTraceWithPreDefinedEvents ktrace = (ITmfTraceWithPreDefinedEvents) trace;
3216 Set<String> traceEvents = TmfEventTypeCollectionHelper.getEventName(ktrace.getContainedEventTypes());
3217 traceEvents.retainAll(events);
3218 return !traceEvents.isEmpty();
3224 The following code will have to be run before the trace synchronization takes place, for example in the Activator of the plugin:
3227 TmfEventMatching.registerMatchObject(new MyAppUstEventMatching());
3230 Now, only adding the traces in an experiment and clicking the '''Synchronize traces''' menu item will synchronize the traces using the new definition for event matching.
3232 == Trace synchronization ==
3234 Trace synchronization classes and interfaces are located in the ''org.eclipse.tracecompass.tmf.core.synchronization'' package.
3236 === Synchronization algorithm ===
3238 Synchronization algorithms are used to synchronize traces from events matched between traces. After synchronization, traces taken on different machines with different time references see their timestamps modified such that they all use the same time reference (typically, the time of at least one of the traces). With traces from different machines, it is impossible to have perfect synchronization, so the result is a best approximation that takes network latency into account.
3240 The abstract class '''SynchronizationAlgorithm''' is a processing unit for matches. New synchronization algorithms must extend this one, it already contains the functions to get the timestamp transforms for different traces.
3242 The ''fully incremental convex hull'' synchronization algorithm is the default synchronization algorithm.
3244 While the synchronization system provisions for more synchronization algorithms, there is not yet a way to select one, the experiment's trace synchronization uses the default algorithm. To test a new synchronization algorithm, the synchronization should be called directly like this:
3247 SynchronizationAlgorithm syncAlgo = new MyNewSynchronizationAlgorithm();
3248 syncAlgo = SynchronizationManager.synchronizeTraces(syncFile, traces, syncAlgo, true);
3251 === Timestamp transforms ===
3253 Timestamp transforms are the formulae used to transform the timestamps from a trace into the reference time. The '''ITmfTimestampTransform''' is the interface to implement to add a new transform.
3255 The following classes implement this interface:
3257 * '''TmfTimestampTransform''': default transform. It cannot be instantiated, it has a single static object ''TmfTimestampTransform.IDENTITY'', which returns the original timestamp.
3258 * '''TmfConstantTransform''': simply applies an offset to the timestamp, so the formula would be: ''f(t) = t + c'' where ''c'' is the offset to apply.
3259 * '''TmfTimestampTransformLinear''': transforms the timestamp using a linear formula: ''f(t) = at + b'', where ''a'' and ''b'' are computed by the synchronization algorithm.
3261 These classes are not accessible directly, to create any timestamp transform, one needs to use one of the methods from the '''TimestampTransformFactory''' utility class.
3263 One could extend the interface for other timestamp transforms, for instance to have a transform where the formula would change over the course of the trace.
3267 Here's a list of features not yet implemented that would enhance trace synchronization and event matching:
3269 * Ability to select a synchronization algorithm
3270 * Implement the minimum spanning tree algorithm by Masoume Jabbarifar (article on the subject not published yet) to automatically select the best reference trace
3271 * Instead of having the timestamp transforms per trace, have the timestamp transform as part of an experiment context, so that the trace's specific analysis, like the state system, are in the original trace, but are transformed only when needed for an experiment analysis.
3272 * Add more views to display the synchronization information (only textual statistics are available for now)
3274 = Analysis Framework =
3276 Analysis modules are useful to tell the user exactly what can be done with a trace. The analysis framework provides an easy way to access and execute the modules and open the various outputs available.
3278 Analyses can have parameters they can use in their code. They also have outputs registered to them to display the results from their execution.
3280 == Creating a new module ==
3282 All analysis modules must implement the '''IAnalysisModule''' interface from the o.e.l.tmf.core project. An abstract class, '''TmfAbstractAnalysisModule''', provides a good base implementation. It is strongly suggested to use it as a superclass of any new analysis.
3286 This example shows how to add a simple analysis module for an LTTng kernel trace with two parameters. It also specifies two mandatory events by overriding '''getAnalysisRequirements'''. The analysis requirements are further explained in the section [[#Providing requirements to analyses]].
3289 public class MyLttngKernelAnalysis extends TmfAbstractAnalysisModule {
3291 public static final String PARAM1 = "myparam";
3292 public static final String PARAM2 = "myotherparam";
3295 public Iterable<TmfAnalysisRequirement> getAnalysisRequirements() {
3297 // initialize the requirement: events
3298 Set<@NonNull String> requiredEvents = ImmutableSet.of("sched_switch", "sched_wakeup");
3299 TmfAbstractAnalysisRequirement eventsReq = new TmfAnalysisEventRequirement(requiredEvents, PriorityLevel.MANDATORY);
3301 return ImmutableList.of(eventsReq);
3305 protected void canceling() {
3306 /* The job I am running in is being cancelled, let's clean up */
3310 protected boolean executeAnalysis(final IProgressMonitor monitor) {
3312 * I am running in an Eclipse job, and I already know I can execute
3315 * In the end, I will return true if I was successfully completed or
3316 * false if I was either interrupted or something wrong occurred.
3318 Object param1 = getParameter(PARAM1);
3319 int param2 = (Integer) getParameter(PARAM2);
3323 public Object getParameter(String name) {
3324 Object value = super.getParameter(name);
3325 /* Make sure the value of param2 is of the right type. For sake of
3326 simplicity, the full parameter format validation is not presented
3328 if ((value != null) && name.equals(PARAM2) && (value instanceof String)) {
3329 return Integer.parseInt((String) value);
3337 === Available base analysis classes and interfaces ===
3339 The following are available as base classes for analysis modules. They also extend the abstract '''TmfAbstractAnalysisModule'''
3341 * '''TmfStateSystemAnalysisModule''': A base analysis module that builds one state system. A module extending this class only needs to provide a state provider and the type of state system backend to use. All state systems should now use this base class as it also contains all the methods to actually create the state sytem with a given backend.
3343 The following interfaces can optionally be implemented by analysis modules if they use their functionalities. For instance, some utility views, like the State System Explorer, may have access to the module's data through these interfaces.
3345 * '''ITmfAnalysisModuleWithStateSystems''': Modules implementing this have one or more state systems included in them. For example, a module may "hide" 2 state system modules for its internal workings. By implementing this interface, it tells that it has state systems and can return them if required.
3347 === How it works ===
3349 Analyses are managed through the '''TmfAnalysisManager'''. The analysis manager is a singleton in the application and keeps track of all available analysis modules, with the help of '''IAnalysisModuleHelper'''. It can be queried to get the available analysis modules, either all of them or only those for a given tracetype. The helpers contain the non-trace specific information on an analysis module: its id, its name, the tracetypes it applies to, etc.
3351 When a trace is opened, the helpers for the applicable analysis create new instances of the analysis modules. The analysis are then kept in a field of the trace and can be executed automatically or on demand.
3353 The analysis is executed by calling the '''IAnalysisModule#schedule()''' method. This method makes sure the analysis is executed only once and, if it is already running, it won't start again. The analysis itself is run inside an Eclipse job that can be cancelled by the user or the application. The developer must consider the progress monitor that comes as a parameter of the '''executeAnalysis()''' method, to handle the proper cancellation of the processing. The '''IAnalysisModule#waitForCompletion()''' method will block the calling thread until the analysis is completed. The method will return whether the analysis was successfully completed or if it was cancelled.
3355 A running analysis can be cancelled by calling the '''IAnalysisModule#cancel()''' method. This will set the analysis as done, so it cannot start again unless it is explicitly reset. This is done by calling the protected method '''resetAnalysis'''.
3357 == Telling TMF about the analysis module ==
3359 Now that the analysis module class exists, it is time to hook it to the rest of TMF so that it appears under the traces in the project explorer. The way to do so is to add an extension of type ''org.eclipse.linuxtools.tmf.core.analysis'' to a plugin, either through the ''Extensions'' tab of the Plug-in Manifest Editor or by editing directly the plugin.xml file.
3361 The following code shows what the resulting plugin.xml file should look like.
3365 point="org.eclipse.linuxtools.tmf.core.analysis">
3367 id="my.lttng.kernel.analysis.id"
3368 name="My LTTng Kernel Analysis"
3369 analysis_module="my.plugin.package.MyLttngKernelAnalysis"
3376 name="myotherparam">
3378 class="org.eclipse.tracecompass.lttng2.kernel.core.trace.LttngKernelTrace">
3384 This defines an analysis module where the ''analysis_module'' attribute corresponds to the module class and must implement IAnalysisModule. This module has 2 parameters: ''myparam'' and ''myotherparam'' which has default value of 3. The ''tracetype'' element tells which tracetypes this analysis applies to. There can be many tracetypes. Also, the ''automatic'' attribute of the module indicates whether this analysis should be run when the trace is opened, or wait for the user's explicit request.
3386 Note that with these extension points, it is possible to use the same module class for more than one analysis (with different ids and names). That is a desirable behavior. For instance, a third party plugin may add a new tracetype different from the one the module is meant for, but on which the analysis can run. Also, different analyses could provide different results with the same module class but with different default values of parameters.
3388 == Attaching outputs and views to the analysis module ==
3390 Analyses will typically produce outputs the user can examine. Outputs can be a text dump, a .dot file, an XML file, a view, etc. All output types must implement the '''IAnalysisOutput''' interface.
3392 An output can be registered to an analysis module at any moment by calling the '''IAnalysisModule#registerOutput()''' method. Analyses themselves may know what outputs are available and may register them in the analysis constructor or after analysis completion.
3394 The various concrete output types are:
3396 * '''TmfAnalysisViewOutput''': It takes a view ID as parameter and, when selected, opens the view.
3398 === Using the extension point to add outputs ===
3400 Analysis outputs can also be hooked to an analysis using the same extension point ''org.eclipse.linuxtools.tmf.core.analysis'' in the plugin.xml file. Outputs can be matched either to a specific analysis identified by an ID, or to all analysis modules extending or implementing a given class or interface.
3402 The following code shows how to add a view output to the analysis defined above directly in the plugin.xml file. This extension does not have to be in the same plugin as the extension defining the analysis. Typically, an analysis module can be defined in a core plugin, along with some outputs that do not require UI elements. Other outputs, like views, who need UI elements, will be defined in a ui plugin.
3406 point="org.eclipse.linuxtools.tmf.core.analysis">
3408 class="org.eclipse.tracecompass.tmf.ui.analysis.TmfAnalysisViewOutput"
3409 id="my.plugin.package.ui.views.myView">
3411 id="my.lttng.kernel.analysis.id">
3415 class="org.eclipse.tracecompass.tmf.ui.analysis.TmfAnalysisViewOutput"
3416 id="my.plugin.package.ui.views.myMoreGenericView">
3417 <analysisModuleClass
3418 class="my.plugin.package.core.MyAnalysisModuleClass">
3419 </analysisModuleClass>
3424 == Providing help for the module ==
3426 For now, the only way to provide a meaningful help message to the user is by overriding the '''IAnalysisModule#getHelpText()''' method and return a string that will be displayed in a message box.
3428 What still needs to be implemented is for a way to add a full user/developer documentation with mediawiki text file for each module and automatically add it to Eclipse Help. Clicking on the Help menu item of an analysis module would open the corresponding page in the help.
3430 == Using analysis parameter providers ==
3432 An analysis may have parameters that can be used during its execution. Default values can be set when describing the analysis module in the plugin.xml file, or they can use the '''IAnalysisParameterProvider''' interface to provide values for parameters. '''TmfAbstractAnalysisParamProvider''' provides an abstract implementation of this interface, that automatically notifies the module of a parameter change.
3434 === Example parameter provider ===
3436 The following example shows how to have a parameter provider listen to a selection in the LTTng kernel Control Flow view and send the thread id to the analysis.
3439 public class MyLttngKernelParameterProvider extends TmfAbstractAnalysisParamProvider {
3441 private ControlFlowEntry fCurrentEntry = null;
3443 private static final String NAME = "My Lttng kernel parameter provider"; //$NON-NLS-1$
3445 private ISelectionListener selListener = new ISelectionListener() {
3447 public void selectionChanged(IWorkbenchPart part, ISelection selection) {
3448 if (selection instanceof IStructuredSelection) {
3449 Object element = ((IStructuredSelection) selection).getFirstElement();
3450 if (element instanceof ControlFlowEntry) {
3451 ControlFlowEntry entry = (ControlFlowEntry) element;
3452 setCurrentThreadEntry(entry);
3461 public MyLttngKernelParameterProvider() {
3467 public String getName() {
3472 public Object getParameter(String name) {
3473 if (fCurrentEntry == null) {
3476 if (name.equals(MyLttngKernelAnalysis.PARAM1)) {
3477 return fCurrentEntry.getThreadId();
3483 public boolean appliesToTrace(ITmfTrace trace) {
3484 return (trace instanceof LttngKernelTrace);
3487 private void setCurrentThreadEntry(ControlFlowEntry entry) {
3488 if (!entry.equals(fCurrentEntry)) {
3489 fCurrentEntry = entry;
3490 this.notifyParameterChanged(MyLttngKernelAnalysis.PARAM1);
3494 private void registerListener() {
3495 final IWorkbench wb = PlatformUI.getWorkbench();
3497 final IWorkbenchPage activePage = wb.getActiveWorkbenchWindow().getActivePage();
3499 /* Add the listener to the control flow view */
3500 view = activePage.findView(ControlFlowView.ID);
3502 view.getSite().getWorkbenchWindow().getSelectionService().addPostSelectionListener(selListener);
3503 view.getSite().getWorkbenchWindow().getPartService().addPartListener(partListener);
3510 === Register the parameter provider to the analysis ===
3512 To have the parameter provider class register to analysis modules, it must first register through the analysis manager. It can be done in a plugin's activator as follows:
3516 public void start(BundleContext context) throws Exception {
3518 TmfAnalysisManager.registerParameterProvider("my.lttng.kernel.analysis.id", MyLttngKernelParameterProvider.class)
3522 where '''MyLttngKernelParameterProvider''' will be registered to analysis ''"my.lttng.kernel.analysis.id"''. When the analysis module is created, the new module will register automatically to the singleton parameter provider instance. Only one module is registered to a parameter provider at a given time, the one corresponding to the currently selected trace.
3524 == Providing requirements to analyses ==
3526 === Analysis requirement provider API ===
3528 A requirement defines the needs of an analysis. For example, an analysis could need an event named ''"sched_switch"'' in order to be properly executed. The requirements are represented by extending the class '''TmfAbstractAnalysisRequirement'''. Since '''IAnalysisModule''' extends the '''IAnalysisRequirementProvider''' interface, all analysis modules must provide their requirements. If the analysis module extends '''TmfAbstractAnalysisModule''', it has the choice between overriding the requirements getter ('''IAnalysisRequirementProvider#getAnalysisRequirements()''') or not, since the abstract class returns an empty collection by default (no requirements).
3530 === Requirement values ===
3532 Each concrete analysis requirement class will define how a requirement is verified on a given trace.
3533 When creating a requirement, the developer will specify a set of values for that class.
3534 With an 'event' type requirement, a trace generator like the LTTng Control could automatically
3535 enable the required events.
3536 Another point we have to take into consideration is the priority level when creating a requirement object.
3537 The enum '''TmfAbstractAnalysisRequirement#PriorityLevel''' gives the choice
3538 between '''PriorityLevel#OPTIONAL''', '''PriorityLevel#ALL_OR_NOTHING''',
3539 '''PriorityLevel#AT_LEAST_ONE''' or '''PriorityLevel#MANDATORY'''. That way, we
3540 can tell if an analysis can run without a value or not.
3543 To create a requirement one has the choice to extend the abstract class
3544 '''TmfAbstractAnalysisRequirement''' or use the existing implementations:
3545 '''TmfAnalysisEventRequirement''' (will verify the presence of events identified by name),
3546 '''TmfAnalysisEventFieldRequirement''' (will verify the presence of fields for some or all events) or
3547 '''TmfCompositeAnalysisRequirement''' (join requirements together with one of the priority levels).
3549 Moreover, information can be added to requirements. That way, the developer can explicitly give help details at the requirement level instead of at the analysis level (which would just be a general help text). To add information to a requirement, the method '''TmfAnalysisRequirement#addInformation()''' must be called. Adding information is not mandatory.
3551 === Example of providing requirements ===
3553 In this example, we will implement a method that initializes a requirement object
3554 and return it in the '''IAnalysisRequirementProvider#getAnalysisRequirements()'''
3555 getter. The example method will return a set with three requirements.
3556 The first one will indicate a mandatory event needed by a specific analysis,
3557 the second one will tell an optional event name and the third will indicate
3558 mandatory event fields for the given event type.
3560 Note that in LTTng event contexts are considered as event fields. Using the
3561 '''TmfAnalysisEventFieldRequirement''' it's possible to define requirements
3562 on event contexts (see 3rd requirement in example below).
3566 public @NonNull Iterable<@NonNull TmfAbstractAnalysisRequirement> getAnalysisRequirements() {
3568 /* Requirement on event name */
3569 Set<@NonNull String> requiredEvents = ImmutableSet.of("sched_wakeup");
3570 TmfAbstractAnalysisRequirement eventsReq1 = new TmfAnalysisEventRequirement(requiredEvents, PriorityLevel.MANDATORY);
3572 requiredEvents = ImmutableSet.of("sched_switch");
3573 TmfAbstractAnalysisRequirement eventsReq2 = new TmfAnalysisEventRequirement(requiredEvents, PriorityLevel.OPTIONAL);
3575 /* An information about the events */
3576 eventsReq2.addInformation("The event sched_wakeup is optional because it's not properly handled by this analysis yet.");
3578 /* Requirement on event fields */
3579 Set<@NonNull String> requiredEventFields = ImmutableSet.of("context._procname", "context._ip");
3580 TmfAbstractAnalysisRequirement eventFieldRequirement = new TmfAnalysisEventFieldRequirement(
3582 requiredEventFields,
3583 PriorityLevel.MANDATORY);
3585 Set<TmfAbstractAnalysisRequirement> requirements = ImmutableSet.of(eventsReq1, eventsReq2, eventFieldRequirement);
3586 return requirements;
3593 Here's a list of features not yet implemented that would improve the analysis module user experience:
3595 * Implement help using the Eclipse Help facility (without forgetting an eventual command line request)
3596 * The abstract class '''TmfAbstractAnalysisModule''' executes an analysis as a job, but nothing compels a developer to do so for an analysis implementing the '''IAnalysisModule''' interface. We should force the execution of the analysis as a job, either from the trace itself or using the TmfAnalysisManager or by some other mean.
3597 * Views and outputs are often registered by the analysis themselves (forcing them often to be in the .ui packages because of the views), because there is no other easy way to do so. We should extend the analysis extension point so that .ui plugins or other third-party plugins can add outputs to a given analysis that resides in the core.
3598 * Improve the user experience with the analysis:
3599 ** Allow the user to select which analyses should be available, per trace or per project.
3600 ** Allow the user to view all available analyses even though he has no imported traces.
3601 ** Allow the user to generate traces for a given analysis, or generate a template to generate the trace that can be sent as parameter to the tracer.
3602 ** Give the user a visual status of the analysis: not executed, in progress, completed, error.
3603 ** Give a small screenshot of the output as icon for it.
3604 ** Allow to specify parameter values from the GUI.
3605 * Add the possibility for an analysis requirement to be composed of another requirement.
3606 * Generate a trace session from analysis requirements.
3609 The TMF remote API is based on the remote services implementation of the Eclipse PTP project. It comes with a built-in SSH implementation based JSch as well as with support for a local connection. The purpose of this API is to provide a programming interface to the PTP remote services implementation for connection handling, command-line execution and file transfer handling. It provides utility functions to simplify repetitive tasks.
3611 The TMF Remote API can be used for remote trace control, fetching of traces from a remote host into the Eclipse Tracing project or uploading files to the remote host. For example, the LTTng tracer control feature uses the TMF remote API to control an LTTng host remotely and to download corresponding traces.
3613 In the following chapters the relevant classes and features of the TMF remote API is described.
3617 To use the TMF remote API one has to add the relevant plug-in dependencies to a plug-in project. To create a plug-in project see chapter [[#Creating an Eclipse UI Plug-in]].
3619 To add plug-in dependencies double-click on the MANIFEST.MF file. Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.tracecompass.tmf.remote.core'' and press '''OK'''. Follow the same steps, add ''org.eclipse.remote.core''. If UI elements are needed in the plug-in also add ''org.eclipse.tracecompass.tmf.remote.ui'' and ''org.eclipse.remote.ui''.
3621 == TmfRemoteConnectionFactory ==
3622 This class is a utility class for creating ''IRemoteConnection'' instances of PTP programatically. It also provides access methods to the OSGI remote services of PTP.
3624 === Accessing the remote services manager (OSGI service) ===
3625 The main entry point into the PTP remote services system is the ''IRemoteServicesManager'' OSGI service. It provides a list of connection types and the global list of all connections.
3627 To access an OSGI service, use the method '''getService()''' of the '''TmfRemoteConnectionFactory''' class:
3630 IRemoteServicesManager manager = TmfRemoteConnectionFactory.getService(IRemoteServicesManager.class);
3633 === Obtaining a IRemoteConnection ===
3634 To obtain an '''IRemoteConnection''' instance use the method '''TmfRemoteConnectionFactory.getRemoteConnection(String remoteServicesId, String name)''', where ''remoteServicesId'' is the ID of service ID for the connection, and ''name'' the name of the connection. For built-in SSH the ''remoteServicesId'' is "org.eclipse.remote.JSch".
3637 IRemoteConnection connection = TmfRemoteConnectionFactory.getRemoteConnection("org.eclipse.remote.JSch", "My Connection");
3640 Note that the connection needs to be created beforehand using the Remote Connection wizard implementation ('''Window -> Preferences -> Remote Development -> Remote Connection''') in the Eclipse application that executes this plug-in. For more information about creating connections using the Remote Connections feature of PTP refer to [http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.ptp.doc.user%2Fhtml%2FremoteTools.html&anchor=remote link]. Alternatively it can be created programmatically using the corresponding API of TMF ([[#Creating an IRemoteConnection instance]]).
3642 To obtain an '''IRemoteConnection''' instance use method '''TmfRemoteConnectionFactory.getLocalConnection()'''.
3644 IRemoteConnection connection = TmfRemoteConnectionFactory.getLocalConnection();
3647 === Creating an IRemoteConnection instance ===
3648 It is possible to create an '''IRemoteConnection''' instance programmatically using the '''TmfRemoteConnectionFactory'''. Right now only build-in SSH or Local connection is supported.
3650 To create an '''IRemoteConnection''' instance use the method '''createConnection(URI hostURI, String name)''' of class '''TmfRemoteConnectionFactory''', where ''hostURI'' is the URI of the remote connection, and ''name'' the name of the connection. For a built-in SSH use:
3652 import org.eclipse.remote.core.IRemoteConnection;
3655 URI hostUri = URIUtil.fromString("ssh://userID@127.0.0.1:22");
3656 IRemoteConnection connection = TmfRemoteConnectionFactory.createConnection(hostUri, "MyHost");
3657 } catch (URISyntaxException e) {
3658 return new Status(IStatus.ERROR, "my.plugin.id", "URI syntax error", e);
3659 } catch (RemoteConnectionException e) {
3660 return new Status(IStatus.ERROR, "my.plugin.id", "Connection cannot be created", e);
3665 Note that if a connection already exists with the given name then this connection will be returned.
3667 === Providing a connection factory ===
3668 Right now only build-in SSH or Local connection of PTP is supported. If one wants to provide another connection factory with a different remote service implementation use the interface '''IConnectionFactory''' to implement a new connection factory class. Then, register the new factory to '''TmfRemoteConnectionFactory''' using method '''registerConnectionFactory(String connectionTypeId, IConnectionFactory factory)''', where ''connectionTypeId'' is a unique ID and ''factory'' is the corresponding connection factory implementation.
3670 == RemoteSystemProxy ==
3671 The purpose of the RemoteSystemProxy is to handle the connection state of '''IRemoteConnection''' (connect/disconnect). Before opening a connection it checks if the connection had been open previously. If it was open, disconnecting the proxy will not close the connection. This is useful if multiple components using the same connection at the same time for different features (e.g. Tracer Control and remote fetching of traces) without impacting each other.
3673 === Creating a RemoteSystemProxy ===
3674 Once one has an '''IRemoteConnection''' instance a '''RemoteSystemProxy''' can be constructed by:
3676 // Get local connection (for example)
3677 IRemoteConnection connection = TmfRemoteConnectionFactory.getLocalConnection();
3678 RemoteSystemProxy proxy = new RemoteSystemProxy(connection);
3681 === Opening the remote connection ===
3682 To open the connection call method '''connect()''':
3687 This will open the connection. If the connection has been previously opened then it will immediately return.
3689 === Closing the remote connection ===
3690 To close the connection call method '''disconnect()''':
3695 Note: This will close the connection if the connection was opened by this proxy. Otherwise it will stay open.
3697 === Disposing the remote connection ===
3698 If a remote system proxy is not needed anymore the proxy instance needs to be disposed by calling method '''dispose()'''. This may close the connection if the connection was opened by this proxy. Otherwise it will stay open.
3704 === Checking the connection state ===
3706 To check the connection state use method '''isConnected()''' of the '''RemoteSystemProxy''' class.
3709 if (proxy.isConnected()) {
3715 === Retrieving the IRemoteConnection instance ===
3716 To retrieve the '''IRemoteConnection''' instance use the '''getRemoteConnection()''' method of the '''RemoteSystemProxy''' class. Using this instance relevant features of the remote connection implementation can be accessed, for example remote file service ('''IRemoteFileService''') or remote process service ('''IRemoteProcessService''').
3719 import org.eclipse.remote.core.IRemoteConnection;
3720 import org.eclipse.remote.core.IRemoteFileService;
3722 IRemoteRemoteConnection connection = proxy.getRemoteConnection();
3723 IRemoteFileService fileService = connection.getService(IRemoteFileService.class);
3724 if (fileService != null) {
3725 // do something (e.g. download or upload a file)
3730 import org.eclipse.remote.core.IRemoteConnection;
3731 import org.eclipse.remote.core.IRemoteFileService;
3733 IRemoteRemoteConnection connection = proxy.getRemoteConnection();
3734 IRemoteFileService processService = connection.getService(IRemoteProcessService.class);
3735 if (processService != null) {
3736 // do something (e.g. execute command)
3740 === Obtaining a command shell ===
3741 The TMF remote API provides a Command shell implementation to execute remote command-line commands. To obtain a command-line shell use the RemoteSystemProxy.
3744 import org.eclipse.remote.core.IRemoteConnection;
3745 import org.eclipse.remote.core.IRemoteFileService;
3746 import org.eclipse.tracecompass.tmf.remote.core.shell.ICommandShell
3748 ICommandShell shell = proxy.createCommandShell();
3749 ICommandInput command = fCommandShell.createCommand();
3752 ICommandResult result = shell.executeCommand(command, new NullProgressMonitor);
3753 System.out.println("Return value: " result.getResult());
3754 for (String line : result.getOutput()) {
3755 System.out.println(line);
3757 for (String line : result.getErrorOutput()) {
3758 System.err.println(line);
3763 Note that the shell needs to be disposed if not needed anymore.
3765 Note for creating a command with parameters using the '''CommandInput''' class, add the command and each parameter separately instead of using one single String.
3767 = Performance Tests =
3769 Performance testing allows to calculate some metrics (CPU time, Memory Usage, etc) that some part of the code takes during its execution. These metrics can then be used as is for information on the system's execution, or they can be compared either with other execution scenarios, or previous runs of the same scenario, for instance, after some optimization has been done on the code.
3771 For automatic performance metric computation, we use the ''org.eclipse.test.performance'' plugin, provided by the Eclipse Test Feature.
3773 == Add performance tests ==
3777 Performance tests are unit tests and they are added to the corresponding unit tests plugin. To separate performance tests from unit tests, a separate source folder, typically named ''perf'', is added to the plug-in.
3779 Tests are to be added to a package under the ''perf'' directory, the package name would typically match the name of the package it is testing. For each package, a class named '''AllPerfTests''' would list all the performance tests classes inside this package. And like for unit tests, a class named '''AllPerfTests''' for the plug-in would list all the packages' '''AllPerfTests''' classes.
3781 When adding performance tests for the first time in a plug-in, the plug-in's '''AllPerfTests''' class should be added to the global list of performance tests, found in package ''org.eclipse.tracecompass.alltests'', in class '''RunAllPerfTests'''. This will ensure that performance tests for the plug-in are run along with the other performance tests
3785 TMF is using the org.eclipse.test.performance framework for performance tests. Using this, performance metrics are automatically taken and, if many runs of the tests are run, average and standard deviation are automatically computed. Results can optionally be stored to a database for later use.
3787 Here is an example of how to use the test framework in a performance test:
3790 public class AnalysisBenchmark {
3792 private static final String TEST_ID = "org.eclipse.linuxtools#LTTng kernel analysis";
3793 private static final CtfTmfTestTrace testTrace = CtfTmfTestTrace.TRACE2;
3794 private static final int LOOP_COUNT = 10;
3800 public void testTrace() {
3801 assumeTrue(testTrace.exists());
3803 /** Create a new performance meter for this scenario */
3804 Performance perf = Performance.getDefault();
3805 PerformanceMeter pm = perf.createPerformanceMeter(TEST_ID);
3807 /** Optionally, tag this test for summary or global summary on a given dimension */
3808 perf.tagAsSummary(pm, "LTTng Kernel Analysis", Dimension.CPU_TIME);
3809 perf.tagAsGlobalSummary(pm, "LTTng Kernel Analysis", Dimension.CPU_TIME);
3811 /** The test will be run LOOP_COUNT times */
3812 for (int i = 0; i < LOOP_COUNT; i++) {
3814 /** Start each run of the test with new objects to avoid different code paths */
3815 try (IAnalysisModule module = new KernelAnalysis();
3816 LttngKernelTrace trace = new LttngKernelTrace()) {
3817 module.setId("test");
3818 trace.initTrace(null, testTrace.getPath(), CtfTmfEvent.class);
3819 module.setTrace(trace);
3821 /** The analysis execution is being tested, so performance metrics
3822 * are taken before and after the execution */
3824 TmfTestHelper.executeAnalysis(module);
3828 * Delete the supplementary files, so next iteration rebuilds
3831 File suppDir = new File(TmfTraceManager.getSupplementaryFileDir(trace));
3832 for (File file : suppDir.listFiles()) {
3836 } catch (TmfAnalysisException | TmfTraceException e) {
3837 fail(e.getMessage());
3841 /** Once the test has been run many times, committing the results will
3842 * calculate average, standard deviation, and, if configured, save the
3843 * data to a database */
3850 For more information, see [http://wiki.eclipse.org/Performance/Automated_Tests The Eclipse Performance Test How-to]
3852 Some rules to help write performance tests are explained in section [[#ABC of performance testing | ABC of performance testing]].
3854 === Run a performance test ===
3856 Performance tests are unit tests, so, just like unit tests, they can be run by right-clicking on a performance test class and selecting ''Run As'' -> ''Junit Plug-in Test''.
3858 By default, if no database has been configured, results will be displayed in the Console at the end of the test.
3860 Here is the sample output from the test described in the previous section. It shows all the metrics that have been calculated during the test.
3863 Scenario 'org.eclipse.linuxtools#LTTng kernel analysis' (average over 10 samples):
3864 System Time: 3.04s (95% in [2.77s, 3.3s]) Measurable effect: 464ms (1.3 SDs) (required sample size for an effect of 5% of mean: 94)
3865 Used Java Heap: -1.43M (95% in [-33.67M, 30.81M]) Measurable effect: 57.01M (1.3 SDs) (required sample size for an effect of 5% of stdev: 6401)
3866 Working Set: 14.43M (95% in [-966.01K, 29.81M]) Measurable effect: 27.19M (1.3 SDs) (required sample size for an effect of 5% of stdev: 6400)
3867 Elapsed Process: 3.04s (95% in [2.77s, 3.3s]) Measurable effect: 464ms (1.3 SDs) (required sample size for an effect of 5% of mean: 94)
3868 Kernel time: 621ms (95% in [586ms, 655ms]) Measurable effect: 60ms (1.3 SDs) (required sample size for an effect of 5% of mean: 39)
3869 CPU Time: 6.06s (95% in [5.02s, 7.09s]) Measurable effect: 1.83s (1.3 SDs) (required sample size for an effect of 5% of mean: 365)
3870 Hard Page Faults: 0 (95% in [0, 0]) Measurable effect: 0 (1.3 SDs) (required sample size for an effect of 5% of stdev: 6400)
3871 Soft Page Faults: 9.27K (95% in [3.28K, 15.27K]) Measurable effect: 10.6K (1.3 SDs) (required sample size for an effect of 5% of mean: 5224)
3872 Text Size: 0 (95% in [0, 0])
3873 Data Size: 0 (95% in [0, 0])
3874 Library Size: 32.5M (95% in [-12.69M, 77.69M]) Measurable effect: 79.91M (1.3 SDs) (required sample size for an effect of 5% of stdev: 6401)
3877 Results from performance tests can be saved automatically to a derby database. Derby can be run either in embedded mode, locally on a machine, or on a server. More information on setting up derby for performance tests can be found here: [http://wiki.eclipse.org/Performance/Automated_Tests The Eclipse Performance Test How-to]. The following documentation will show how to configure an Eclipse run configuration to store results on a derby database located on a server.
3879 Note that to store results in a derby database, the ''org.apache.derby'' plug-in must be available within your Eclipse. Since it is an optional dependency, it is not included in the target definition. It can be installed via the '''Orbit''' repository, in ''Help'' -> ''Install new software...''. If the '''Orbit''' repository is not listed, click on the latest one from [http://download.eclipse.org/tools/orbit/downloads/] and copy the link under ''Orbit Build Repository''.
3881 To store the data to a database, it needs to be configured in the run configuration. In ''Run'' -> ''Run configurations..'', under ''Junit Plug-in Test'', find the run configuration that corresponds to the test you wish to run, or create one if it is not present yet.
3883 In the ''Arguments'' tab, in the box under ''VM Arguments'', add on separate lines the following information
3886 -Declipse.perf.dbloc=//javaderby.dorsal.polymtl.ca
3887 -Declipse.perf.config=build=mybuild;host=myhost;config=linux;jvm=1.7
3890 The ''eclipse.perf.dbloc'' parameter is the url (or filename) of the derby database. The database is by default named ''perfDB'', with username and password ''guest''/''guest''. If the database does not exist, it will be created, initialized and populated.
3892 The ''eclipse.perf.config'' parameter identifies a '''variation''': It typically identifies the build on which is it run (commitId and/or build date, etc), the machine (host) on which it is run, the configuration of the system (for example Linux or Windows), the jvm etc. That parameter is a list of ';' separated key-value pairs. To be backward-compatible with the Eclipse Performance Tests Framework, the 4 keys mentioned above are mandatory, but any key-value pairs can be used.
3894 == ABC of performance testing ==
3896 Here follow some rules to help design good and meaningful performance tests.
3898 === Determine what to test ===
3900 For tests to be significant, it is important to choose what exactly is to be tested and make sure it is reproducible every run. To limit the amount of noise caused by the TMF framework, the performance test code should be tweaked so that only the method under test is run. For instance, a trace should not be "opened" (by calling the ''traceOpened()'' method) to test an analysis, since the ''traceOpened'' method will also trigger the indexing and the execution of all applicable automatic analysis.
3902 For each code path to test, multiple scenarios can be defined. For instance, an analysis could be run on different traces, with different sizes. The results will show how the system scales and/or varies depending on the objects it is executed on.
3904 The number of '''samples''' used to compute the results is also important. The code to test will typically be inside a '''for''' loop that runs exactly the same code each time for a given number of times. All objects used for the test must start in the same state at each iteration of the loop. For instance, any trace used during an execution should be disposed of at the end of the loop, and any supplementary file that may have been generated in the run should be deleted.
3906 Before submitting a performance test to the code review, you should run it a few times (with results in the Console) and see if the standard deviation is not too large and if the results are reproducible.
3908 === Metrics descriptions and considerations ===
3910 CPU time: CPU time represent the total time spent on CPU by the current process, for the time of the test execution. It is the sum of the time spent by all threads. On one hand, it is more significant than the elapsed time, since it should be the same no matter how many CPU cores the computer has. But since it calculates the time of every thread, one has to make sure that only threads related to what is being tested are executed during that time, or else the results will include the times of those other threads. For an application like TMF, it is hard to control all the threads, and empirically, it is found to vary a lot more than the system time from one run to the other.
3912 System time (Elapsed time): The time between the start and the end of the execution. It will vary depending on the parallelization of the threads and the load of the machine.
3914 Kernel time: Time spent in kernel mode
3916 Used Java Heap: It is the difference between the memory used at the beginning of the execution and at the end. This metric may be useful to calculate the overall size occupied by the data generated by the test run, by forcing a garbage collection before taking the metrics at the beginning and at the end of the execution. But it will not show the memory used throughout the execution. There can be a large standard deviation. The reason for this is that when benchmarking methods that trigger tasks in different threads, like signals and/or analysis, these other threads might be in various states at each run of the test, which will impact the memory usage calculated. When using this metric, either make sure the method to test does not trigger external threads or make sure you wait for them to finish.
3920 == Adding a protocol ==
3922 Supporting a new network protocol in TMF is straightforward. Minimal effort is required to support new protocols. In this tutorial, the UDP protocol will be added to the list of supported protocols.
3924 === Architecture ===
3926 All the TMF pcap-related code is divided in three projects (not considering the tests plugins):
3927 * '''org.eclipse.tracecompass.pcap.core''', which contains the parser that will read pcap files and constructs the different packets from a ByteBuffer. It also contains means to build packet streams, which are conversation (list of packets) between two endpoints. To add a protocol, almost all of the work will be in that project.
3928 * '''org.eclipse.tracecompass.tmf.pcap.core''', which contains TMF-specific concepts and act as a wrapper between TMF and the pcap parsing library. It only depends on org.eclipse.tracecompass.tmf.core and org.eclipse.tracecompass.pcap.core. To add a protocol, one file must be edited in this project.
3929 * '''org.eclipse.tracecompass.tmf.pcap.ui''', which contains all TMF pcap UI-specific concepts, such as the views and perspectives. No work is needed in that project.
3931 === UDP Packet Structure ===
3933 The UDP is a transport-layer protocol that does not guarantee message delivery nor in-order message reception. A UDP packet (datagram) has the following [http://en.wikipedia.org/wiki/User_Datagram_Protocol#Packet_structure structure]:
3935 {| class="wikitable" style="margin: 0 auto; text-align: center;"
3937 ! style="border-bottom:none; border-right:none;"| ''Offsets''
3938 ! style="border-left:none;"| Octet
3944 ! style="border-top: none" | Octet
3945 ! <tt>Bit</tt>!!<tt> 0</tt>!!<tt> 1</tt>!!<tt> 2</tt>!!<tt> 3</tt>!!<tt> 4</tt>!!<tt> 5</tt>!!<tt> 6</tt>!!<tt> 7</tt>!!<tt> 8</tt>!!<tt> 9</tt>!!<tt>10</tt>!!<tt>11</tt>!!<tt>12</tt>!!<tt>13</tt>!!<tt>14</tt>!!<tt>15</tt>!!<tt>16</tt>!!<tt>17</tt>!!<tt>18</tt>!!<tt>19</tt>!!<tt>20</tt>!!<tt>21</tt>!!<tt>22</tt>!!<tt>23</tt>!!<tt>24</tt>!!<tt>25</tt>!!<tt>26</tt>!!<tt>27</tt>!!<tt>28</tt>!!<tt>29</tt>!!<tt>30</tt>!!<tt>31</tt>
3949 | colspan="16" style="background:#fdd;"| Source port || colspan="16"| Destination port
3953 | colspan="16"| Length || colspan="16" style="background:#fdd;"| Checksum
3956 Knowing that, we can define an UDPPacket class that contains those fields.
3958 === Creating the UDPPacket ===
3960 First, in org.eclipse.tracecompass.pcap.core, create a new package named '''org.eclipse.tracecompass.pcap.core.protocol.name''' with name being the name of the new protocol. In our case name is udp so we create the package '''org.eclipse.tracecompass.pcap.core.protocol.udp'''. All our work is going in this package.
3962 In this package, we create a new class named UDPPacket that extends Packet. All new protocol must define a packet type that extends the abstract class Packet. We also add different fields:
3963 * ''Packet'' '''fChildPacket''', which is the packet encapsulated by this UDP packet, if it exists. This field will be initialized by findChildPacket().
3964 * ''ByteBuffer'' '''fPayload''', which is the payload of this packet. Basically, it is the UDP packet without its header.
3965 * ''int'' '''fSourcePort''', which is an unsigned 16-bits field, that contains the source port of the packet (see packet structure).
3966 * ''int'' '''fDestinationPort''', which is an unsigned 16-bits field, that contains the destination port of the packet (see packet structure).
3967 * ''int'' '''fTotalLength''', which is an unsigned 16-bits field, that contains the total length (header + payload) of the packet.
3968 * ''int'' '''fChecksum''', which is an unsigned 16-bits field, that contains a checksum to verify the integrity of the data.
3969 * ''UDPEndpoint'' '''fSourceEndpoint''', which contains the source endpoint of the UDPPacket. The UDPEndpoint class will be created later in this tutorial.
3970 * ''UDPEndpoint'' '''fDestinationEndpoint''', which contains the destination endpoint of the UDPPacket.
3971 * ''ImmutableMap<String, String>'' '''fFields''', which is a map that contains all the packet fields (see in data structure) which assign a field name with its value. Those values will be displayed on the UI.
3973 We also create the UDPPacket(PcapFile file, @Nullable Packet parent, ByteBuffer packet) constructor. The parameters are:
3974 * ''PcapFile'' '''file''', which is the pcap file to which this packet belongs.
3975 * ''Packet'' '''parent''', which is the packet encasulating this UDPPacket
3976 * ''ByteBuffer'' '''packet''', which is a ByteBuffer that contains all the data necessary to initialize the fields of this UDPPacket. We will retrieve bytes from it during object construction.
3978 The following class is obtained:
3981 package org.eclipse.tracecompass.pcap.core.protocol.udp;
3983 import java.nio.ByteBuffer;
3984 import java.util.Map;
3986 import org.eclipse.tracecompass.internal.pcap.core.endpoint.ProtocolEndpoint;
3987 import org.eclipse.tracecompass.internal.pcap.core.packet.BadPacketException;
3988 import org.eclipse.tracecompass.internal.pcap.core.packet.Packet;
3990 public class UDPPacket extends Packet {
3992 private final @Nullable Packet fChildPacket;
3993 private final @Nullable ByteBuffer fPayload;
3995 private final int fSourcePort;
3996 private final int fDestinationPort;
3997 private final int fTotalLength;
3998 private final int fChecksum;
4000 private @Nullable UDPEndpoint fSourceEndpoint;
4001 private @Nullable UDPEndpoint fDestinationEndpoint;
4003 private @Nullable ImmutableMap<String, String> fFields;
4006 * Constructor of the UDP Packet class.
4009 * The file that contains this packet.
4011 * The parent packet of this packet (the encapsulating packet).
4013 * The entire packet (header and payload).
4014 * @throws BadPacketException
4015 * Thrown when the packet is erroneous.
4017 public UDPPacket(PcapFile file, @Nullable Packet parent, ByteBuffer packet) throws BadPacketException {
4018 super(file, parent, PcapProtocol.UDP);
4019 // TODO Auto-generated constructor stub
4024 public Packet getChildPacket() {
4025 // TODO Auto-generated method stub
4030 public ByteBuffer getPayload() {
4031 // TODO Auto-generated method stub
4036 public boolean validate() {
4037 // TODO Auto-generated method stub
4042 protected Packet findChildPacket() throws BadPacketException {
4043 // TODO Auto-generated method stub
4048 public ProtocolEndpoint getSourceEndpoint() {
4049 // TODO Auto-generated method stub
4054 public ProtocolEndpoint getDestinationEndpoint() {
4055 // TODO Auto-generated method stub
4060 public Map<String, String> getFields() {
4061 // TODO Auto-generated method stub
4066 public String getLocalSummaryString() {
4067 // TODO Auto-generated method stub
4072 protected String getSignificationString() {
4073 // TODO Auto-generated method stub
4078 public boolean equals(Object obj) {
4079 // TODO Auto-generated method stub
4084 public int hashCode() {
4085 // TODO Auto-generated method stub
4092 Now, we implement the constructor. It is done in four steps:
4093 * We initialize fSourceEndpoint, fDestinationEndpoint and fFields to null, since those are lazy-loaded. This allows faster construction of the packet and thus faster parsing.
4094 * We initialize fSourcePort, fDestinationPort, fTotalLength, fChecksum using ByteBuffer packet. Thanks to the packet data structure, we can simply retrieve packet.getShort() to get the value. Since there is no unsigned in Java, special care is taken to avoid negative number. We use the utility method ConversionHelper.unsignedShortToInt() to convert it to an integer, and initialize the fields.
4095 * Now that the header is parsed, we take the rest of the ByteBuffer packet to initialize the payload, if there is one. To do this, we simply generate a new ByteBuffer starting from the current position.
4096 * We initialize the field fChildPacket using the method findChildPacket()
4098 The following constructor is obtained:
4100 public UDPPacket(PcapFile file, @Nullable Packet parent, ByteBuffer packet) throws BadPacketException {
4101 super(file, parent, Protocol.UDP);
4103 // The endpoints and fFields are lazy loaded. They are defined in the get*Endpoint()
4105 fSourceEndpoint = null;
4106 fDestinationEndpoint = null;
4109 // Initialize the fields from the ByteBuffer
4110 packet.order(ByteOrder.BIG_ENDIAN);
4113 fSourcePort = ConversionHelper.unsignedShortToInt(packet.getShort());
4114 fDestinationPort = ConversionHelper.unsignedShortToInt(packet.getShort());
4115 fTotalLength = ConversionHelper.unsignedShortToInt(packet.getShort());
4116 fChecksum = ConversionHelper.unsignedShortToInt(packet.getShort());
4118 // Initialize the payload
4119 if (packet.array().length - packet.position() > 0) {
4120 byte[] array = new byte[packet.array().length - packet.position()];
4123 ByteBuffer payload = ByteBuffer.wrap(array);
4124 payload.order(ByteOrder.BIG_ENDIAN);
4125 payload.position(0);
4132 fChildPacket = findChildPacket();
4137 Then, we implement the following methods:
4138 * ''public Packet'' '''getChildPacket()''': simple getter of fChildPacket
4139 * ''public ByteBuffer'' '''getPayload()''': simple getter of fPayload
4140 * ''public boolean'' '''validate()''': method that checks if the packet is valid. In our case, the packet is valid if the retrieved checksum fChecksum and the real checksum (that we can compute using the fields and payload of UDPPacket) are the same.
4141 * ''protected Packet'' '''findChildPacket()''': method that create a new packet if a encapsulated protocol is found. For instance, based on the fDestinationPort, it could determine what the encapsulated protocol is and creates a new packet object.
4142 * ''public ProtocolEndpoint'' '''getSourceEndpoint()''': method that initializes and returns the source endpoint.
4143 * ''public ProtocolEndpoint'' '''getDestinationEndpoint()''': method that initializes and returns the destination endpoint.
4144 * ''public Map<String, String>'' '''getFields()''': method that initializes and returns the map containing the fields matched to their value.
4145 * ''public String'' '''getLocalSummaryString()''': method that returns a string summarizing the most important fields of the packet. There is no need to list all the fields, just the most important one. This will be displayed on UI.
4146 * ''protected String'' '''getSignificationString()''': method that returns a string describing the meaning of the packet. If there is no particular meaning, it is possible to return getLocalSummaryString().
4147 * public boolean'' '''equals(Object obj)''': Object's equals method.
4148 * public int'' '''hashCode()''': Object's hashCode method.
4150 We get the following code:
4153 public @Nullable Packet getChildPacket() {
4154 return fChildPacket;
4158 public @Nullable ByteBuffer getPayload() {
4163 * Getter method that returns the UDP Source Port.
4165 * @return The source Port.
4167 public int getSourcePort() {
4172 * Getter method that returns the UDP Destination Port.
4174 * @return The destination Port.
4176 public int getDestinationPort() {
4177 return fDestinationPort;
4183 * See http://www.iana.org/assignments/service-names-port-numbers/service-
4184 * names-port-numbers.xhtml or
4185 * http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers
4188 protected @Nullable Packet findChildPacket() throws BadPacketException {
4189 // When more protocols are implemented, we can simply do a switch on the fDestinationPort field to find the child packet.
4190 // For instance, if the destination port is 80, then chances are the HTTP protocol is encapsulated. We can create a new HTTP
4191 // packet (after some verification that it is indeed the HTTP protocol).
4192 ByteBuffer payload = fPayload;
4193 if (payload == null) {
4197 return new UnknownPacket(getPcapFile(), this, payload);
4201 public boolean validate() {
4202 // Not yet implemented. ATM, we consider that all packets are valid.
4203 // TODO Implement it. We can compute the real checksum and compare it to fChecksum.
4208 public UDPEndpoint getSourceEndpoint() {
4210 UDPEndpoint endpoint = fSourceEndpoint;
4211 if (endpoint == null) {
4212 endpoint = new UDPEndpoint(this, true);
4214 fSourceEndpoint = endpoint;
4215 return fSourceEndpoint;
4219 public UDPEndpoint getDestinationEndpoint() {
4220 @Nullable UDPEndpoint endpoint = fDestinationEndpoint;
4221 if (endpoint == null) {
4222 endpoint = new UDPEndpoint(this, false);
4224 fDestinationEndpoint = endpoint;
4225 return fDestinationEndpoint;
4229 public Map<String, String> getFields() {
4230 ImmutableMap<String, String> map = fFields;
4232 @SuppressWarnings("null")
4233 @NonNull ImmutableMap<String, String> newMap = ImmutableMap.<String, String> builder()
4234 .put("Source Port", String.valueOf(fSourcePort)) //$NON-NLS-1$
4235 .put("Destination Port", String.valueOf(fDestinationPort)) //$NON-NLS-1$
4236 .put("Length", String.valueOf(fTotalLength) + " bytes") //$NON-NLS-1$ //$NON-NLS-2$
4237 .put("Checksum", String.format("%s%04x", "0x", fChecksum)) //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
4246 public String getLocalSummaryString() {
4247 return "Src Port: " + fSourcePort + ", Dst Port: " + fDestinationPort; //$NON-NLS-1$ //$NON-NLS-2$
4251 protected String getSignificationString() {
4252 return "Source Port: " + fSourcePort + ", Destination Port: " + fDestinationPort; //$NON-NLS-1$ //$NON-NLS-2$
4256 public int hashCode() {
4257 final int prime = 31;
4259 result = prime * result + fChecksum;
4260 final Packet child = fChildPacket;
4261 if (child != null) {
4262 result = prime * result + child.hashCode();
4264 result = prime * result;
4266 result = prime * result + fDestinationPort;
4267 final ByteBuffer payload = fPayload;
4268 if (payload != null) {
4269 result = prime * result + payload.hashCode();
4271 result = prime * result;
4273 result = prime * result + fSourcePort;
4274 result = prime * result + fTotalLength;
4279 public boolean equals(@Nullable Object obj) {
4286 if (getClass() != obj.getClass()) {
4289 UDPPacket other = (UDPPacket) obj;
4290 if (fChecksum != other.fChecksum) {
4293 final Packet child = fChildPacket;
4294 if (child != null) {
4295 if (!child.equals(other.fChildPacket)) {
4299 if (other.fChildPacket != null) {
4303 if (fDestinationPort != other.fDestinationPort) {
4306 final ByteBuffer payload = fPayload;
4307 if (payload != null) {
4308 if (!payload.equals(other.fPayload)) {
4312 if (other.fPayload != null) {
4316 if (fSourcePort != other.fSourcePort) {
4319 if (fTotalLength != other.fTotalLength) {
4326 The UDPPacket class is implemented. We now have the define the UDPEndpoint.
4328 === Creating the UDPEndpoint ===
4330 For the UDP protocol, an endpoint will be its source or its destination port, depending if it is the source endpoint or destination endpoint. Knowing that, we can create our UDPEndpoint class.
4332 We create in our package a new class named UDPEndpoint that extends ProtocolEndpoint. We also add a field: fPort, which contains the source or destination port. We finally add a constructor public ExampleEndpoint(Packet packet, boolean isSourceEndpoint):
4333 * ''Packet'' '''packet''': the packet to build the endpoint from.
4334 * ''boolean'' '''isSourceEndpoint''': whether the endpoint is the source endpoint or destination endpoint.
4336 We obtain the following unimplemented class:
4339 package org.eclipse.tracecompass.pcap.core.protocol.udp;
4341 import org.eclipse.tracecompass.internal.pcap.core.endpoint.ProtocolEndpoint;
4342 import org.eclipse.tracecompass.internal.pcap.core.packet.Packet;
4344 public class UDPEndpoint extends ProtocolEndpoint {
4346 private final int fPort;
4348 public UDPEndpoint(Packet packet, boolean isSourceEndpoint) {
4349 super(packet, isSourceEndpoint);
4350 // TODO Auto-generated constructor stub
4354 public int hashCode() {
4355 // TODO Auto-generated method stub
4360 public boolean equals(Object obj) {
4361 // TODO Auto-generated method stub
4366 public String toString() {
4367 // TODO Auto-generated method stub
4374 For the constructor, we simply initialize fPort. If isSourceEndpoint is true, then we take packet.getSourcePort(), else we take packet.getDestinationPort().
4378 * Constructor of the {@link UDPEndpoint} class. It takes a packet to get
4379 * its endpoint. Since every packet has two endpoints (source and
4380 * destination), the isSourceEndpoint parameter is used to specify which
4384 * The packet that contains the endpoints.
4385 * @param isSourceEndpoint
4386 * Whether to take the source or the destination endpoint of the
4389 public UDPEndpoint(UDPPacket packet, boolean isSourceEndpoint) {
4390 super(packet, isSourceEndpoint);
4391 fPort = isSourceEndpoint ? packet.getSourcePort() : packet.getDestinationPort();
4395 Then we implement the methods:
4396 * ''public int'' '''hashCode()''': method that returns an integer based on the fields value. In our case, it will return an integer depending on fPort, and the parent endpoint that we can retrieve with getParentEndpoint().
4397 * ''public boolean'' '''equals(Object obj)''': method that returns true if two objects are equals. In our case, two UDPEndpoints are equal if they both have the same fPort and have the same parent endpoint that we can retrieve with getParentEndpoint().
4398 * ''public String'' '''toString()''': method that returns a description of the UDPEndpoint as a string. In our case, it will be a concatenation of the string of the parent endpoint and fPort as a string.
4402 public int hashCode() {
4403 final int prime = 31;
4405 ProtocolEndpoint endpoint = getParentEndpoint();
4406 if (endpoint == null) {
4409 result = endpoint.hashCode();
4411 result = prime * result + fPort;
4416 public boolean equals(@Nullable Object obj) {
4420 if (!(obj instanceof UDPEndpoint)) {
4424 UDPEndpoint other = (UDPEndpoint) obj;
4427 boolean localEquals = (fPort == other.fPort);
4432 // Check above layers.
4433 ProtocolEndpoint endpoint = getParentEndpoint();
4434 if (endpoint != null) {
4435 return endpoint.equals(other.getParentEndpoint());
4441 public String toString() {
4442 ProtocolEndpoint endpoint = getParentEndpoint();
4443 if (endpoint == null) {
4444 @SuppressWarnings("null")
4445 @NonNull String ret = String.valueOf(fPort);
4448 return endpoint.toString() + '/' + fPort;
4452 === Registering the UDP protocol ===
4454 The last step is to register the new protocol. There are three places where the protocol has to be registered. First, the parser has to know that a new protocol has been added. This is defined in the enum org.eclipse.tracecompass.internal.pcap.core.protocol.PcapProtocol. Simply add the protocol name here, along with a few arguments:
4455 * ''String'' '''longname''', which is the long version of name of the protocol. In our case, it is "User Datagram Protocol".
4456 * ''String'' '''shortName''', which is the shortened name of the protocol. In our case, it is "UDP".
4457 * ''Layer'' '''layer''', which is the layer to which the protocol belongs in the OSI model. In our case, this is the layer 4.
4458 * ''boolean'' '''supportsStream''', which defines whether or not the protocol supports packet streams. In our case, this is set to true.
4460 Thus, the following line is added in the PcapProtocol enum:
4462 UDP("User Datagram Protocol", "udp", Layer.LAYER_4, true),
4465 Also, TMF has to know about the new protocol. This is defined in org.eclipse.tracecompass.internal.tmf.pcap.core.protocol.TmfPcapProtocol. We simply add it, with a reference to the corresponding protocol in PcapProtocol. Thus, the following line is added in the TmfPcapProtocol enum:
4467 UDP(PcapProtocol.UDP),
4470 You will also have to update the ''ProtocolConversion'' class to register the protocol in the switch statements. Thus, for UDP, we add:
4473 return TmfPcapProtocol.UDP;
4478 return PcapProtocol.UDP;
4481 Finally, all the protocols that could be the parent of the new protocol (in our case, IPv4 and IPv6) have to be notified of the new protocol. This is done by modifying the findChildPacket() method of the packet class of those protocols. For instance, in IPv4Packet, we add a case in the switch statement of findChildPacket, if the Protocol number matches UDP's protocol number at the network layer:
4484 protected @Nullable Packet findChildPacket() throws BadPacketException {
4485 ByteBuffer payload = fPayload;
4486 if (payload == null) {
4490 switch (fIpDatagramProtocol) {
4491 case IPProtocolNumberHelper.PROTOCOL_NUMBER_TCP:
4492 return new TCPPacket(getPcapFile(), this, payload);
4493 case IPProtocolNumberHelper.PROTOCOL_NUMBER_UDP:
4494 return new UDPPacket(getPcapFile(), this, payload);
4496 return new UnknownPacket(getPcapFile(), this, payload);
4501 The new protocol has been added. Running TMF should work just fine, and the new protocol is now recognized.
4503 == Adding stream-based views ==
4505 To add a stream-based View, simply monitor the TmfPacketStreamSelectedSignal in your view. It contains the new stream that you can retrieve with signal.getStream(). You must then make an event request to the current trace to get the events, and use the stream to filter the events of interest. Therefore, you must also monitor TmfTraceOpenedSignal, TmfTraceClosedSignal and TmfTraceSelectedSignal. Examples of stream-based views include a view that represents the packets as a sequence diagram, or that shows the TCP connection state based on the packets SYN/ACK/FIN/RST flags. A (very very very early) draft of such a view can be found at https://git.eclipse.org/r/#/c/31054/.
4509 * Add more protocols. At the moment, only four protocols are supported. The following protocols would need to be implemented: ARP, SLL, WLAN, USB, IPv6, ICMP, ICMPv6, IGMP, IGMPv6, SCTP, DNS, FTP, HTTP, RTP, SIP, SSH and Telnet. Other VoIP protocols would be nice.
4510 * Add a network graph view. It would be useful to produce graphs that are meaningful to network engineers, and that they could use (for presentation purpose, for instance). We could use the XML-based analysis to do that!
4511 * Add a Stream Diagram view. This view would represent a stream as a Sequence Diagram. It would be updated when a TmfNewPacketStreamSignal is thrown. It would be easy to see the packet exchange and the time delta between each packet. Also, when a packet is selected in the Stream Diagram, it should be selected in the event table and its content should be shown in the Properties View. See https://git.eclipse.org/r/#/c/31054/ for a draft of such a view.
4512 * Make adding protocol more "plugin-ish", via extension points for instance. This would make it easier to support new protocols, without modifying the source code.
4513 * Control dumpcap directly from eclipse, similar to how LTTng is controlled in the Control View.
4514 * Support pcapng. See: http://www.winpcap.org/ntar/draft/PCAP-DumpFileFormat.html for the file format.
4515 * Add SWTBOT tests to org.eclipse.tracecompass.tmf.pcap.ui
4516 * Add a Raw Viewer, similar to Wireshark. We could use the “Show Raw” in the event editor to do that.
4517 * Externalize strings in org.eclipse.tracecompass.pcap.core. At the moment, all the strings are hardcoded. It would be good to externalize them all.
4521 Markers are annotations that are defined with a time range, a color, a category and an optional label. The markers are displayed in the time graph of any view that extends ''AbstractTimeGraphView''. The markers are drawn as a line or a region (in case the time range duration is not zero) of the given color, which can have an alpha value to use transparency. The markers can be drawn in the foreground (above time graph states) or in the background (below time graph states). An optional label can be drawn in the the time scale area.
4523 The developer can add trace-specific markers and/or view-specific markers.
4525 == Trace-specific markers ==
4527 Trace-specific markers can be added by registering an ''IAdapterFactory'' with the TmfTraceAdapterManager. The adapter factory must provide adapters of the ''IMarkerEventSource'' class for a given ''ITmfTrace'' object. The adapter factory can be registered for traces of a certain class (which will include sub-classes of the given class) or it can be registered for traces of a certain trace type id (as defined in the ''org.eclipse.linuxtools.tmf.core.tracetype'' extension point).
4529 The adapter factory can be registered in the ''Activator'' of the plug-in that introduces it, in the ''start()'' method, and unregistered in the ''stop()'' method.
4531 It is recommended to extend the ''AbstractTmfTraceAdapterFactory'' class when creating the adapter factory. This will ensure that a single instance of the adapter is created for a specific trace and reused by all components that need the adapter, and that the adapter is disposed when the trace is closed.
4533 The adapter implementing the ''IMarkerEventSource'' interface must provide two methods:
4535 * ''getMarkerCategories()'' returns a list of category names which will be displayed to the user, who can then enable or disable markers on a per-category basis.
4537 * ''getMarkerList()'' returns a list of markers instances of class ''IMarkerEvent'' for the given category and time range. The resolution can be used to limit the number of markers returned for the current zoom level, and the progress monitor can be checked for early cancellation of the marker computation.
4539 The trace-specific markers for a particular trace will appear in all views extending ''AbstractTimeGraphView'' when that trace (or an experiment containing that trace) is selected.
4541 An example of a trace-specific markers implementation can be seen by examining classes ''LostEventsMarkerEventSourceFactory'', ''LostEventsMarkerEventSource'' and ''Activator'' in the ''org.eclipse.tracecompass.tmf.ui'' plug-in.
4543 == View-specific markers ==
4545 View-specific markers can by added in sub-classes of ''AbstractTimeGraphView'' by implementing the following two methods:
4547 * ''getViewMarkerCategories()'' returns a list of category names which will be displayed to the user, who can then enable or disable markers on a per-category basis.
4549 * ''getViewMarkerList()'' returns a list of markers instances of class ''IMarkerEvent'' for the given time range. The resolution can be used to limit the number of markers returned for the current zoom level, and the progress monitor can be checked for early cancellation of the marker computation.
4551 = Virtual Machine Analysis =
4553 Virtualized environment are becoming more popular and understanding them can be challenging as machines share resources (CPU, disks, memory, etc), but from their point of view, they are running on bare metal. Tracing all the machines (guests and hosts) in a virtualized environment allows information to be correlated between all the nodes to better understand the system. See the User documentation for more info on this analysis.
4555 The virtual machine analysis has been implemented in the following plugins:
4557 * '''org.eclipse.tracecompass.lttng2.kernel.core''' contains the virtual machine analysis itself, the model of the virtualized environment, as well as its implementation for different hypervisors.
4558 * '''org.eclipse.tracecompass.lttng2.kernel.ui''' contains the views for the analysis.
4560 == Adding support for an hypervisor ==
4562 Supporting a new hypervisor in Trace Compass requires implementing the model for this new hypervisor. The following sections will describe for each part of the model what has to be considered, what information we need to have, etc. Note that each hypervisor will require some work and investigation. The information might already be available as a single tracepoint for some, while other may require many tracepoints. It is also possible that some will require to add tracepoints, either to the kernel, or the hypervisor code itself, in which case a userspace trace (LTTng UST) might be necessary to get all the information.
4564 === Virtual CPU analysis ===
4566 This analysis tracks the state of the virtual CPUs in conjunction with the physical CPU it is running on. For this, we need the following information:
4568 * A way to link a virtual CPU on a guest with a process on the host, such that it is possible to determine when the virtual CPU is preempted on the host. If trace data does not provide this information, some hypervisors have a command line option to dump that information. Manually feeding that information to the analysis is not supported now though.
4569 * A way to differentiate between hypervisor mode and normal mode for the virtual CPU. A virtual CPU usually runs within a process on the host, but sometimes that process may need to run hypervisor-specific code. That is called '''hypervisor mode'''. During that time, no code from the guest itself is run. Typically, the process is running on the host (not preempted), but from the guest's point of view, the virtual CPU should be preempted.
4571 A model implementation for a new hypervisor will need to implement class '''IVirtualMachineModel''', that can be found in package '''org.eclipse.tracecompass.internal.lttng2.kernel.core.analysis.vm.model'''. See the javadoc in the class itself for more information on what each method does.
4575 Logging can be quite useful to debug a class, see its interactions with other components and understand the behavior of the system. TraceCompass uses JUL to log various events in the code, which can then be used to model and analyze the system's workflow. Here are some guidelines to use logging efficiently in Trace Compass. See the User Documentation for instructions on how to enable logging and obtain traces.
4577 === Use a static logger for each class ===
4579 Each class should define and use their own static logger like this:
4581 private static final Logger LOGGER = TraceCompassLog.getLogger(StateSystem.class);
4583 It is then easy to filter the components to log by their full class name. The ''TraceCompassLog#getLogger'' method is a wrapper for ''java.util.logging.Logger#getLogger'', but the Trace Compass's logging initialization (overriding the default's ConsoleHandler and INFO level for the org.eclipse.tracecompass namespace when logging is not enabled) is done in the static initializer of this class. Using the wrapper method ensures that this code is called and the user will not see Console message all over the place.
4585 '''Note on abstract classes''': It is debatable whether to use a static logger with the abstract class name or a logger with the concrete class's name.
4587 In the former case, logging for this class uses the classes's own namespace, but it is impossible to discriminate logging statement by concrete classes unless the concrete class name is added as parameter to the statement (when necessary).
4589 The latter case has the advantage that one can log only the concrete class and see all that goes on in the abstract class as well, but the concrete class may be in another namespace and will not benefit from the ''TraceCompassLog'' logging initialization and the user will see console logging happen.
4591 Both methods have their advantages and there is no clear good answer.
4593 === Use a message supplier ===
4595 A logging statement, to be meaningful, will usually log a string that contains data from the context and will thus do string concatenation. This has a non-negligible overhead. To avoid having to do the costly string concatenation when the statement is not logged, java provides method taking a ''Supplier<String>'' as argument and that method should be used for all logging statements
4597 LOGGER.info(() -> "[Component:Action] param1=" + myParam1 + ", param2=" + myParam2);
4599 === Choose the appropriate log level ===
4601 The available log levels for JUL are SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST. The default level when not specified is INFO.
4603 * As a rule of thumb, enabling all INFO level statements should have a near zero impact on the execution, so log parameters that require some computations, or methods that are called very often should not be logged at INFO level.
4604 * CONFIG level should provide more detailed information than the INFO level, but still not impact the execution too much. It should be possible for a component to use up to CONFIG level statements and make meaningful analyses using the timestamps of the events.
4605 * FINE, FINER and FINEST are for statements that will not be used with the timestamps. Enabling them may have a visible effect on the performance of Trace Compass. They will typically be used with a purpose in mind, like debugging a component or getting data on caches for examples.
4607 === Log message format ===
4609 JUL logging will produce trace data and unless one wants to visually parse a trace one event at a time, it will typically be used with an analysis to produce a result. To do so, the log messages should have a format that can then be associated with a trace type.
4611 Third party plugins provide a custom trace parser and LTTng trace type for JUL statements that use the following format
4613 [EventName:MayContainSemiColon] paramName1=paramValue1, paramName2=paramValue2