4 The purpose of the '''Tracing Monitoring Framework (TMF)''' is to facilitate the integration of tracing and monitoring tools into Eclipse, to provide out-of-the-box generic functionalities/views and provide extension mechanisms of the base functionalities for application specific purposes.
6 = Implementing a New Trace Type =
8 The framework can easily be extended to support more trace types. To make a new trace type, one must define the following items:
14 * (Optional but recommended) The ''org.eclipse.linuxtools.tmf.ui.tracetype'' plug-in extension point
16 The '''event type''' must implement an ''ITmfEvent'' or extend a class that implements an ''ITmfEvent''. Typically it will extend ''TmfEvent''. The event type must contain all the data of an event. The '''trace reader''' must be of an ''ITmfTrace'' type. The ''TmfTrace'' class will supply many background operations so that the reader only needs to implement certain functions. The '''trace context''' can be seen as the internals of an iterator. It is required by the trace reader to parse events as it iterates the trace and to keep track of its rank and location. It can have a timestamp, a rank, a file position, or any other element, it should be considered to be ephemeral. The '''trace location''' is an element that is cloned often to store checkpoints, it is generally persistent. It is used to rebuild a context, therefore, it needs to contain enough information to unambiguously point to one and only one event. Finally the ''tracetype'' plug-in extension associates a given trace, non-programmatically to a trace type for use in the UI.
18 == An Example: Nexus-lite parser ==
20 === Description of the file ===
22 This is a very small subset of the nexus trace format, with some changes to make it easier to read. There is one file. This file starts with 64 Strings containing the event names, then an arbitrarily large number of events. The events are each 64 bits long. the first 32 are the timestamp in microseconds, the second 32 are split into 6 bits for the event type, and 26 for the data payload.
24 The trace type will be made of two parts, part 1 is the event description, it is just 64 strings, comma seperated and then a line feed.
27 Startup,Stop,Load,Add, ... ,reserved\n
30 Then there will be the events in this format
33 |style="width: 50%; background-color: #ffffcc;"|timestamp (32 bits)
34 |style="width: 10%; background-color: #ffccff;"|type (6 bits)
35 |style="width: 40%; background-color: #ccffcc;"|payload (26 bits)
37 |style="background-color: #ffcccc;" colspan="3"|64 bits total
40 all events will be the same size (64 bits).
42 === NexusLite Plug-in ===
44 Create a '''New''', '''Project...''', '''Plug-in Project''', set the title to '''com.example.nexuslite''', click '''Next >''' then click on '''Finish'''.
46 Now the structure for the Nexus trace Plug-in is set up.
48 Add a dependency to TMF core and UI by opening the '''MANIFEST.MF''' in '''META-INF''', selecting the '''Dependencies''' tab and '''Add ...''' '''org.eclipse.linuxtools.tmf.core''' and '''org.eclipse.linuxtools.tmf.ui'''.
50 [[Image:images/NTTAddDepend.png]]<br>
51 [[Image:images/NTTSelectProjects.png]]<br>
53 Now the project can access TMF classes.
57 The '''TmfEvent''' class will work for this example. No code required.
61 The trace reader will extend a '''TmfTrace''' class.
63 It will need to implement:
65 * validate (is the trace format valid?)
67 * initTrace (called as the trace is opened
69 * seekEvent (go to a position in the trace and create a context)
71 * getNext (implemented in the base class)
73 * parseEvent (read the next element in the trace)
75 Here is an example implementation of the Nexus Trace file
77 <pre>/*******************************************************************************
78 * Copyright (c) 2013 Ericsson
80 * All rights reserved. This program and the accompanying materials are
81 * made available under the terms of the Eclipse Public License v1.0 which
82 * accompanies this distribution, and is available at
83 * http://www.eclipse.org/legal/epl-v10.html
86 * Matthew Khouzam - Initial API and implementation
87 *******************************************************************************/
89 package com.example.nexuslite;
91 import java.io.BufferedReader;
93 import java.io.FileInputStream;
94 import java.io.FileNotFoundException;
95 import java.io.FileReader;
96 import java.io.IOException;
97 import java.nio.MappedByteBuffer;
98 import java.nio.channels.FileChannel;
99 import java.nio.channels.FileChannel.MapMode;
101 import org.eclipse.core.resources.IProject;
102 import org.eclipse.core.resources.IResource;
103 import org.eclipse.core.runtime.IStatus;
104 import org.eclipse.core.runtime.Status;
105 import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
106 import org.eclipse.linuxtools.tmf.core.event.ITmfEventField;
107 import org.eclipse.linuxtools.tmf.core.event.TmfEvent;
108 import org.eclipse.linuxtools.tmf.core.event.TmfEventField;
109 import org.eclipse.linuxtools.tmf.core.event.TmfEventType;
110 import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
111 import org.eclipse.linuxtools.tmf.core.timestamp.ITmfTimestamp;
112 import org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestamp;
113 import org.eclipse.linuxtools.tmf.core.trace.ITmfContext;
114 import org.eclipse.linuxtools.tmf.core.trace.ITmfEventParser;
115 import org.eclipse.linuxtools.tmf.core.trace.ITmfLocation;
116 import org.eclipse.linuxtools.tmf.core.trace.TmfContext;
117 import org.eclipse.linuxtools.tmf.core.trace.TmfLongLocation;
118 import org.eclipse.linuxtools.tmf.core.trace.TmfTrace;
123 * @author Matthew Khouzam
125 public class NexusTrace extends TmfTrace implements ITmfEventParser {
127 private static final int CHUNK_SIZE = 65536; // seems fast on MY system
128 private static final int EVENT_SIZE = 8; // according to spec
130 private TmfLongLocation fCurrentLocation;
131 private static final TmfLongLocation NULLLOCATION = new TmfLongLocation(
133 private static final TmfContext NULLCONTEXT = new TmfContext(NULLLOCATION,
137 private long fOffset;
139 private String[] fEventTypes;
140 private FileChannel fFileChannel;
141 private MappedByteBuffer fMappedByteBuffer;
144 public IStatus validate(@SuppressWarnings("unused") IProject project,
146 File f = new File(path);
148 return new Status(IStatus.ERROR, Activator.PLUGIN_ID,
149 "File does not exist"); //$NON-NLS-1$
152 return new Status(IStatus.ERROR, Activator.PLUGIN_ID, path
153 + " is not a file"); //$NON-NLS-1$
155 String header = readHeader(f);
156 if (header.split(",", 64).length == 64) { //$NON-NLS-1$
157 return Status.OK_STATUS;
159 return new Status(IStatus.ERROR, Activator.PLUGIN_ID,
160 "File does not start as a CSV"); //$NON-NLS-1$
164 public ITmfLocation getCurrentLocation() {
165 return fCurrentLocation;
169 public void initTrace(IResource resource, String path,
170 Class<? extends ITmfEvent> type) throws TmfTraceException {
171 super.initTrace(resource, path, type);
172 fFile = new File(path);
173 fSize = fFile.length();
175 throw new TmfTraceException("file is empty"); //$NON-NLS-1$
177 String header = readHeader(fFile);
178 if (header == null) {
179 throw new TmfTraceException("File does not start as a CSV"); //$NON-NLS-1$
181 fEventTypes = header.split(",", 64); // 64 values of types according to //$NON-NLS-1$
183 if (fEventTypes.length != 64) {
184 throw new TmfTraceException(
185 "Trace header does not contain 64 event names"); //$NON-NLS-1$
187 if (getNbEvents() < 1) {
188 throw new TmfTraceException("Trace does not have any events"); //$NON-NLS-1$
191 fFileChannel = new FileInputStream(fFile).getChannel();
193 } catch (FileNotFoundException e) {
194 throw new TmfTraceException(e.getMessage());
195 } catch (IOException e) {
196 throw new TmfTraceException(e.getMessage());
203 private String readHeader(File file) {
204 String header = new String();
207 br = new BufferedReader(new FileReader(file));
208 header = br.readLine();
210 } catch (IOException e) {
213 fOffset = header.length() + 1;
214 setNbEvents((fSize - fOffset) / EVENT_SIZE);
219 public double getLocationRatio(ITmfLocation location) {
220 return ((TmfLongLocation) location).getLocationInfo().doubleValue()
225 public ITmfContext seekEvent(ITmfLocation location) {
226 TmfLongLocation nl = (TmfLongLocation) location;
227 if (location == null) {
228 nl = new TmfLongLocation(0L);
231 seek(nl.getLocationInfo());
232 } catch (IOException e) {
235 return new TmfContext(nl, nl.getLocationInfo());
239 public ITmfContext seekEvent(double ratio) {
240 long rank = (long) (ratio * getNbEvents());
243 } catch (IOException e) {
246 return new TmfContext(new TmfLongLocation(rank), rank);
249 private void seek(long rank) throws IOException {
250 final long position = fOffset + (rank * EVENT_SIZE);
251 int size = Math.min((int) (fFileChannel.size() - position), CHUNK_SIZE);
252 fMappedByteBuffer = fFileChannel.map(MapMode.READ_ONLY, position, size);
256 public ITmfEvent parseEvent(ITmfContext context) {
257 if ((context == null) || (context.getRank() == -1)) {
260 TmfEvent event = null;
264 long pos = context.getRank();
265 if (pos < getNbEvents()) {
267 // if we are approaching the limit size, move to a new window
268 if ((fMappedByteBuffer.position() + EVENT_SIZE) > fMappedByteBuffer
270 seek(context.getRank());
273 * the trace format, is:
275 * - 32 bits for the time,
276 * - 6 for the event type,
279 * all the 0x00 stuff are masks.
283 * it may be interesting to assume if the ts goes back in time,
284 * it actually is rolling over we would need to keep the
285 * previous timestamp for that, keep the high bits and increment
286 * them if the next int ts read is lesser than the previous one
289 ts = 0x00000000ffffffffL & fMappedByteBuffer.getInt();
291 long data = 0x00000000ffffffffL & fMappedByteBuffer.getInt();
292 type = (int) (data >> 26) & (0x03f); // first 6 bits
293 payload = (int) (data & 0x003FFFFFFL); // last 26 bits
294 // the time is in microseconds.
295 TmfTimestamp timestamp = new TmfTimestamp(ts, ITmfTimestamp.MICROSECOND_SCALE);
296 final String title = fEventTypes[type];
297 // put the value in a field
298 final TmfEventField tmfEventField = new TmfEventField(
299 "value", payload, null); //$NON-NLS-1$
300 // the field must be in an array
301 final TmfEventField[] fields = new TmfEventField[1];
302 fields[0] = tmfEventField;
303 final TmfEventField content = new TmfEventField(
304 ITmfEventField.ROOT_FIELD_ID, null, fields);
305 // set the current location
307 fCurrentLocation = new TmfLongLocation(pos);
309 event = new TmfEvent(this, pos, timestamp, null,
310 new TmfEventType(title, title, null), content, null);
311 } catch (IOException e) {
312 fCurrentLocation = new TmfLongLocation(-1L);
320 In this example the '''validate''' function checks if the file exists and is not a directory.
322 The '''initTrace''' function will read the event names, and find where the data starts. After this, the number of events is known, and since each event is 8 bytes long according to the specs, the seek is then trivial.
324 The '''seek''' here will just reset the reader to the right location.
326 The '''parseEvent''' method needs to parse and return the current event and store the current location.
328 The '''getNext''' method (in base class) will read the next event and update the context. It calls the '''parseEvent''' method to read the event and update the location. It does not need to be overridden and in this example it is not. The sequence of actions necessary are parse the next event from the trace, create an '''ITmfEvent''' with that data, update the current location, call '''updateAttributes''', update the context then return the event.
330 === Trace Context ===
332 The trace context will be a '''TmfContext'''
334 === Trace Location ===
336 The trace location will be a long, representing the rank in the file. The '''TmfLongLocation''' will be the used, once again, no code is required.
338 === (Optional but recommended) The ''org.eclipse.linuxtools.tmf.ui.tracetype'' plug-in extension point ===
340 One can implement the ''tracetype'' extension in their own plug-in. In this example, the ''com.example.nexuslite'' plug-in will be modified.
342 The '''plugin.xml''' file in the ui plug-in needs to be updated if one wants users to access the given event type. It can be updated in the Eclipse plug-in editor.
344 # In Extensions tab, add the '''org.eclipse.linuxtools.tmf.ui.tracetype''' extension point.
345 [[Image:images/NTTExtension.png]]<br>
346 [[Image:images/NTTTraceType.png]]<br>
347 [[Image:images/NTTExtensionPoint.png]]<br>
349 # 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'''.
351 [[Image:images/NTTAddType.png]]<br>
353 The '''id''' is the unique identifier used to refer to the trace.
355 The '''name''' is the field that shall be displayed when a trace type is selected.
357 The '''trace type''' is the canonical path refering to the class of the trace.
359 The '''event type''' is the canonical path refering to the class of the events of a given trace.
361 The '''category''' (optional) is the container in which this trace type will be stored.
363 The '''icon''' (optional) is the image to associate with that trace type.
365 In the end, the extension menu should look like this.
367 [[Image:images/NTTPluginxmlComplete.png]]<br>
371 * Do not load the whole trace in RAM, it will limit the size of the trace that can be read.
372 * Reuse as much code as possible, it makes the trace format much easier to maintain.
373 * Use Eclipse's editor instead of editing the xml directly.
374 * Do not forget Java supports only signed data types, there may be special care needed to handle unsigned data.
375 * Keep all the code in the same plug-in as the ''tracetype'' if it makes sense from a design point of view. It will make integration easier.
377 == Download the Code ==
379 The plug-in is available [http://wiki.eclipse.org/images/3/34/Com.example.nexuslite.zip here] with a trace generator and a quick test case.
381 == Optional Trace Type Attributes ==
382 After defining the trace type as described in the previous chapters it is possible to define optional attributes for the trace type.
384 === Default Editor ===
385 The attribute '''defaultEditor''' allows for configuring the editor to use for displaying the events. If omitted, the ''TmfEventsEditor'' is used as default. To configure an editor, first add the '''defaultEditor''' attribute to the trace type in the extension definition. This can be done by selecting the trace type in the plug-in manifest editor. Then click the right mouse button and select '''New -> defaultEditor''' in the context sensitive menu. Then select the newly added attribute. Now you can specify the editor id to use on the right side of the manifest editor. For example, this attribute could be used to implement an extension of the class ''org.eclipse.ui.part.MultiPageEditor''. The first page could use the ''TmfEventsEditor''' to display the events in a table as usual and other pages can display other aspects of the trace.
387 === Events Table Type ===
388 The attribute '''eventsTableType''' allows for configuring the events table class to use in the default events editor. If omitted, the default events table will be used. To configure a trace type specific events table, first add the '''eventsTableType''' attribute to the trace type in the extension definition. This can be done by selecting the trace type in the plug-in manifest editor. Then click the right mouse button and select '''New -> eventsTableType''' in the context sensitive menu. Then select the newly added attribute and click on ''class'' on the right side of the manifest editor. The new class wizard will open. The ''superclass'' field will be already filled with the class ''org.eclipse.linuxtools.tmf.ui.viewers.events.TmfEventsTable''. Using this attribute a table with different columns than the default columns can be defined. See class org.eclipse.linuxtools.internal.lttng2.kernel.ui.viewers.events.Lttng2EventsTable for an example implementation.
390 === Statistics Viewer Type ===
391 The attribute '''statisticsViewerType''' allows for defining trace type specific statistics. If omitted, only the default statistics will be displayed in the ''Statistics'' view (part of the ''Tracing'' view category). By default this view displays the total number of events and the number of events per event type for the whole trace and for the selected time range. To configure trace type specific statistics, first add the '''statisticsViewerType''' attribute to the trace type in the extension definition. This can be done by selecting the trace type in the plug-in manifest editor. Then click the right mouse button and select '''New -> statisticsViewerType''' in the context sensitive menu. Then select the newly added attribute and click on ''class'' on the right side of the manifest editor. The new class wizard will open. The ''superclass'' field will be already filled with the class ''org.eclipse.linuxtools.tmf.ui.viewers.statistics.TmfStatisticsViewer''. Now overwrite the relevant methods to provide the trace specific statistics. When executing the plug-in extension in Eclipse and opening the ''Statistics'' view the ''Statistics'' view will show an additional tab beside the global tab that shows the default statistics. The new tab will display the trace specific statistics provided in the ''TmfStatisticsViewer'' sub-class implementation.
395 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.
397 This tutorial will cover concepts like:
400 * Signal handling (@TmfSignalHandler)
401 * Data requests (TmfEventRequest)
402 * SWTChart integration
404 === Prerequisites ===
406 The tutorial is based on Eclipse 4.3 (Eclipse Kepler), TMF 2.0.0 and SWTChart 0.7.0. You can install SWTChart by using the Orbit update site. http://download.eclipse.org/tools/orbit/downloads/
408 === Creating an Eclipse UI Plug-in ===
410 To create a new project with name org.eclipse.linuxtools.tmf.sample.ui select '''File -> New -> Project -> Plug-in Development -> Plug-in Project'''. <br>
411 [[Image:images/Screenshot-NewPlug-inProject1.png]]<br>
413 [[Image:images/Screenshot-NewPlug-inProject2.png]]<br>
415 [[Image:images/Screenshot-NewPlug-inProject3.png]]<br>
417 === Creating a View ===
419 To open the plug-in manifest, double-click on the MANIFEST.MF file. <br>
420 [[Image:images/SelectManifest.png]]<br>
422 Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.linuxtools.tmf.core'' and press '''OK'''<br>
423 Following the same steps, add ''org.eclipse.linuxtools.tmf.ui'' and ''org.swtchart''.<br>
424 [[Image:images/AddDependencyTmfUi.png]]<br>
426 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>
427 [[Image:images/AddViewExtension1.png]]<br>
429 To create a view, click the right mouse button. Then select '''New -> view'''<br>
430 [[Image:images/AddViewExtension2.png]]<br>
432 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>
433 [[Image:images/FillSampleViewExtension.png]]<br>
435 This will generate an empty class. Once the quick fixes are applied, the following code is obtained:
438 package org.eclipse.linuxtools.tmf.sample.ui;
440 import org.eclipse.swt.widgets.Composite;
441 import org.eclipse.ui.part.ViewPart;
443 public class SampleView extends TmfView {
445 public SampleView(String viewName) {
447 // TODO Auto-generated constructor stub
451 public void createPartControl(Composite parent) {
452 // TODO Auto-generated method stub
457 public void setFocus() {
458 // TODO Auto-generated method stub
465 This creates an empty view, however the basic structure is now is place.
467 === Implementing a view ===
469 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.
471 ==== Adding an Empty Chart ====
473 First, we can add an empty chart to the view and initialize some of its components.
476 private static final String SERIES_NAME = "Series";
477 private static final String Y_AXIS_TITLE = "Signal";
478 private static final String X_AXIS_TITLE = "Time";
479 private static final String FIELD = "value"; // The name of the field that we want to display on the Y axis
480 private static final String VIEW_ID = "org.eclipse.linuxtools.tmf.sample.ui.view";
482 private ITmfTrace currentTrace;
484 public SampleView() {
489 public void createPartControl(Composite parent) {
490 chart = new Chart(parent, SWT.BORDER);
491 chart.getTitle().setVisible(false);
492 chart.getAxisSet().getXAxis(0).getTitle().setText(X_AXIS_TITLE);
493 chart.getAxisSet().getYAxis(0).getTitle().setText(Y_AXIS_TITLE);
494 chart.getSeriesSet().createSeries(SeriesType.LINE, SERIES_NAME);
495 chart.getLegend().setVisible(false);
499 public void setFocus() {
504 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>
505 [[Image:images/RunEclipseApplication.png]]<br>
507 A new Eclipse application window will show. In the new window go to '''Windows -> Show View -> Other... -> Other -> Sample View'''.<br>
508 [[Image:images/ShowViewOther.png]]<br>
510 You should now see a view containing an empty chart<br>
511 [[Image:images/EmptySampleView.png]]<br>
513 ==== Signal Handling ====
515 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.
519 public void traceSelected(final TmfTraceSelectedSignal signal) {
524 ==== Requesting Data ====
526 Then we need to actually gather data from the trace. This is done asynchronously using a ''TmfEventRequest''
530 public void traceSelected(final TmfTraceSelectedSignal signal) {
531 // Don't populate the view again if we're already showing this trace
532 if (currentTrace == signal.getTrace()) {
535 currentTrace = signal.getTrace();
537 // Create the request to get data from the trace
539 TmfEventRequest req = new TmfEventRequest(TmfEvent.class,
540 TmfTimeRange.ETERNITY, TmfEventRequest.ALL_DATA,
541 ExecutionType.BACKGROUND) {
544 public void handleData(ITmfEvent data) {
545 // Called for each event
546 super.handleData(data);
550 public void handleSuccess() {
551 // Request successful, not more data available
552 super.handleSuccess();
556 public void handleFailure() {
557 // Request failed, not more data available
558 super.handleFailure();
561 ITmfTrace trace = signal.getTrace();
562 trace.sendRequest(req);
566 ==== Transferring Data to the Chart ====
568 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.
571 TmfEventRequest req = new TmfEventRequest(TmfEvent.class,
572 TmfTimeRange.ETERNITY, TmfEventRequest.ALL_DATA,
573 ExecutionType.BACKGROUND) {
575 ArrayList<Double> xValues = new ArrayList<Double>();
576 ArrayList<Double> yValues = new ArrayList<Double>();
579 public void handleData(ITmfEvent data) {
580 // Called for each event
581 super.handleData(data);
582 ITmfEventField field = data.getContent().getField(FIELD);
584 yValues.add((Double) field.getValue());
585 xValues.add((double) data.getTimestamp().getValue());
590 public void handleSuccess() {
591 // Request successful, not more data available
592 super.handleSuccess();
594 final double x[] = toArray(xValues);
595 final double y[] = toArray(yValues);
597 // This part needs to run on the UI thread since it updates the chart SWT control
598 Display.getDefault().asyncExec(new Runnable() {
602 chart.getSeriesSet().getSeries()[0].setXSeries(x);
603 chart.getSeriesSet().getSeries()[0].setYSeries(y);
612 * Convert List<Double> to double[]
614 private double[] toArray(List<Double> list) {
615 double[] d = new double[list.size()];
616 for (int i = 0; i < list.size(); ++i) {
625 ==== Adjusting the Range ====
627 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.
631 ArrayList<Double> xValues = new ArrayList<Double>();
632 ArrayList<Double> yValues = new ArrayList<Double>();
633 private double maxY = -Double.MAX_VALUE;
634 private double minY = Double.MAX_VALUE;
635 private double maxX = -Double.MAX_VALUE;
636 private double minX = Double.MAX_VALUE;
639 public void handleData(ITmfEvent data) {
640 super.handleData(data);
641 ITmfEventField field = data.getContent().getField(FIELD);
643 Double yValue = (Double) field.getValue();
644 minY = Math.min(minY, yValue);
645 maxY = Math.max(maxY, yValue);
648 double xValue = (double) data.getTimestamp().getValue();
650 minX = Math.min(minX, xValue);
651 maxX = Math.max(maxX, xValue);
656 public void handleSuccess() {
657 super.handleSuccess();
658 final double x[] = toArray(xValues);
659 final double y[] = toArray(yValues);
661 // This part needs to run on the UI thread since it updates the chart SWT control
662 Display.getDefault().asyncExec(new Runnable() {
666 chart.getSeriesSet().getSeries()[0].setXSeries(x);
667 chart.getSeriesSet().getSeries()[0].setYSeries(y);
670 if (!xValues.isEmpty() && !yValues.isEmpty()) {
671 chart.getAxisSet().getXAxis(0).setRange(new Range(0, x[x.length - 1]));
672 chart.getAxisSet().getYAxis(0).setRange(new Range(minY, maxY));
674 chart.getAxisSet().getXAxis(0).setRange(new Range(0, 1));
675 chart.getAxisSet().getYAxis(0).setRange(new Range(0, 1));
677 chart.getAxisSet().adjustRange();
685 ==== Formatting the Time Stamps ====
687 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.
691 public void createPartControl(Composite parent) {
694 chart.getAxisSet().getXAxis(0).getTick().setFormat(new TmfChartTimeStampFormat());
697 public class TmfChartTimeStampFormat extends SimpleDateFormat {
698 private static final long serialVersionUID = 1L;
700 public StringBuffer format(Date date, StringBuffer toAppendTo, FieldPosition fieldPosition) {
701 long time = date.getTime();
702 toAppendTo.append(TmfTimestampFormat.getDefaulTimeFormat().format(time));
708 public void timestampFormatUpdated(TmfTimestampFormatUpdateSignal signal) {
709 // Called when the time stamp preference is changed
710 chart.getAxisSet().getXAxis(0).getTick().setFormat(new TmfChartTimeStampFormat());
715 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.
719 public void createPartControl(Composite parent) {
722 ITmfTrace trace = getActiveTrace();
724 traceSelected(new TmfTraceSelectedSignal(this, trace));
729 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>
731 [[Image:images/SampleView.png]]<br>
733 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.
735 = Component Interaction =
737 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.
739 The TMF Signal Manager handles registration of components and the broadcasting of signals to their intended receivers.
741 Components can register as VIP receivers which will ensure they will receive the signal before non-VIP receivers.
743 == Sending Signals ==
745 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.
748 TmfExampleSignal signal = new TmfExampleSignal(this, ...);
749 TmfSignalManager.dispatchSignal(signal);
752 If the sender is an instance of the class TmfComponent, the broadcast method can be used:
755 TmfExampleSignal signal = new TmfExampleSignal(this, ...);
759 == Receiving Signals ==
761 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.
764 TmfSignalManager.register(this);
765 TmfSignalManager.registerVIP(this);
768 If the receiver is an instance of the class TmfComponent, it is automatically registered as a normal receiver in the constructor.
770 When the receiver is destroyed or disposed, it should deregister itself from the signal manager.
773 TmfSignalManager.deregister(this);
776 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.
780 public void example(TmfExampleSignal signal) {
785 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.
787 == Signal Throttling ==
789 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.
791 The signal throttler must first be initialized:
794 final int delay = 100; // in ms
795 TmfSignalThrottler throttler = new TmfSignalThrottler(this, delay);
798 Then the sending of signals should be queued through the throttler:
801 TmfExampleSignal signal = new TmfExampleSignal(this, ...);
802 throttler.queue(signal);
805 When the throttler is no longer needed, it should be disposed:
811 == Signal Reference ==
813 The following is a list of built-in signals defined in the framework.
815 === TmfStartSynchSignal ===
819 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.
823 Sent by TmfSignalManager before dispatching a signal to all receivers.
827 Received by TmfDataProvider.
829 === TmfEndSynchSignal ===
833 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.
837 Sent by TmfSignalManager after dispatching a signal to all receivers.
841 Received by TmfDataProvider.
843 === TmfTraceOpenedSignal ===
847 This signal is used to indicate that a trace has been opened in an editor.
851 Sent by a TmfEventsEditor instance when it is created.
855 Received by TmfTrace, TmfExperiment, TmfTraceManager and every view that shows trace data. Components that show trace data should handle this signal.
857 === TmfTraceSelectedSignal ===
861 This signal is used to indicate that a trace has become the currently selected trace.
865 Sent by a TmfEventsEditor instance when it receives focus. Components can send this signal to make a trace editor be brought to front.
869 Received by TmfTraceManager and every view that shows trace data. Components that show trace data should handle this signal.
871 === TmfTraceClosedSignal ===
875 This signal is used to indicate that a trace editor has been closed.
879 Sent by a TmfEventsEditor instance when it is disposed.
883 Received by TmfTraceManager and every view that shows trace data. Components that show trace data should handle this signal.
885 === TmfTraceRangeUpdatedSignal ===
889 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.
893 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.
897 Received by TmfTrace, TmfExperiment and components that process trace events. Components that need to process trace events should handle this signal.
899 === TmfTraceUpdatedSignal ===
903 This signal is used to indicate that new events have been indexed for a trace.
907 Sent by TmfCheckpointIndexer when new events have been indexed and the number of events has changed.
911 Received by components that need to be notified of a new trace event count.
913 === TmfTimeSynchSignal ===
917 This signal is used to indicate that a new time or time range has been
918 selected. It contains a begin and end time. If a single time is selected then
919 the begin and end time are the same.
923 Sent by any component that allows the user to select a time or time range.
927 Received by any component that needs to be notified of the currently selected time or time range.
929 === TmfRangeSynchSignal ===
933 This signal is used to indicate that a new time range window has been set.
937 Sent by any component that allows the user to set a time range window.
941 Received by any component that needs to be notified of the current visible time range window.
943 === TmfEventFilterAppliedSignal ===
947 This signal is used to indicate that a filter has been applied to a trace.
951 Sent by TmfEventsTable when a filter is applied.
955 Received by any component that shows trace data and needs to be notified of applied filters.
957 === TmfEventSearchAppliedSignal ===
961 This signal is used to indicate that a search has been applied to a trace.
965 Sent by TmfEventsTable when a search is applied.
969 Received by any component that shows trace data and needs to be notified of applied searches.
971 === TmfTimestampFormatUpdateSignal ===
975 This signal is used to indicate that the timestamp format preference has been updated.
979 Sent by TmfTimestampFormat when the default timestamp format preference is changed.
983 Received by any component that needs to refresh its display for the new timestamp format.
985 === TmfStatsUpdatedSignal ===
989 This signal is used to indicate that the statistics data model has been updated.
993 Sent by statistic providers when new statistics data has been processed.
997 Received by statistics viewers and any component that needs to be notified of a statistics update.
1001 TMF has built-in Eclipse tracing support for the debugging of signal interaction between components. To enable it, open the '''Run/Debug Configuration...''' dialog, select a configuration, click the '''Tracing''' tab, select the plug-in '''org.eclipse.linuxtools.tmf.core''', and check the '''signal''' item.
1003 All signals sent and received will be logged to the file TmfTrace.log located in the Eclipse home directory.
1005 = Generic State System =
1009 The Generic State System is a utility available in TMF to track different states
1010 over the duration of a trace. It works by first sending some or all events of
1011 the trace into a state provider, which defines the state changes for a given
1012 trace type. Once built, views and analysis modules can then query the resulting
1013 database of states (called "state history") to get information.
1015 For example, let's suppose we have the following sequence of events in a kernel
1018 10 s, sys_open, fd = 5, file = /home/user/myfile
1020 15 s, sys_read, fd = 5, size=32
1022 20 s, sys_close, fd = 5
1024 Now let's say we want to implement an analysis module which will track the
1025 amount of bytes read and written to eachfile. Here, of course the sys_read is
1026 interesting. However, by just looking at that event, we have no information on
1027 which file is being read, only its fd (5) is known. To get the match
1028 fd5 = /home/user/myfile, we have to go back to the sys_open event which happens
1031 But since we don't know exactly where this sys_open event is, we will have to go
1032 back to the very start of the trace, and look through events one by one! This is
1033 obviously not efficient, and will not scale well if we want to analyze many
1034 similar patterns, or for very large traces.
1036 A solution in this case would be to use the state system to keep track of the
1037 amount of bytes read/written to every *filename* (instead of every file
1038 descriptor, like we get from the events). Then the module could ask the state
1039 system "what is the amount of bytes read for file "/home/user/myfile" at time
1040 16 s", and it would return the answer "32" (assuming there is no other read
1041 than the one shown).
1043 == High-level components ==
1045 The State System infrastructure is composed of 3 parts:
1046 * The state provider
1047 * The central state system
1048 * The storage backend
1050 The state provider is the customizable part. This is where the mapping from
1051 trace events to state changes is done. This is what you want to implement for
1052 your specific trace type and analysis type. It's represented by the
1053 ITmfStateProvider interface (with a threaded implementation in
1054 AbstractTmfStateProvider, which you can extend).
1056 The core of the state system is exposed through the ITmfStateSystem and
1057 ITmfStateSystemBuilder interfaces. The former allows only read-only access and
1058 is typically used for views doing queries. The latter also allows writing to the
1059 state history, and is typically used by the state provider.
1061 Finally, each state system has its own separate backend. This determines how the
1062 intervals, or the "state history", are saved (in RAM, on disk, etc.) You can
1063 select the type of backend at construction time in the TmfStateSystemFactory.
1067 Before we dig into how to use the state system, we should go over some useful
1072 An attribute is the smallest element of the model that can be in any particular
1073 state. When we refer to the "full state", in fact it means we are interested in
1074 the state of every single attribute of the model.
1076 === Attribute Tree ===
1078 Attributes in the model can be placed in a tree-like structure, a bit like files
1079 and directories in a file system. However, note that an attribute can always
1080 have both a value and sub-attributes, so they are like files and directories at
1081 the same time. We are then able to refer to every single attribute with its
1084 For example, in the attribute tree for LTTng kernel traces, we use the following
1085 attributes, among others:
1103 In this model, the attribute "Processes/1000/PPID" refers to the PPID of process
1104 with PID 1000. The attribute "CPUs/0/Status" represents the status (running,
1105 idle, etc.) of CPU 0. "Processes/1000/PPID" and "Processes/1001/PPID" are two
1106 different attribute, even though their base name is the same: the whole path is
1107 the unique identifier.
1109 The value of each attribute can change over the duration of the trace,
1110 independently of the other ones, and independently of its position in the tree.
1112 The tree-like organization is optional, all attributes could be at the same
1113 level. But it's possible to put them in a tree, and it helps make things
1118 In addition to a given path, each attribute also has a unique integer
1119 identifier, called the "quark". To continue with the file system analogy, this
1120 is like the inode number. When a new attribute is created, a new unique quark
1121 will be assigned automatically. They are assigned incrementally, so they will
1122 normally be equal to their order of creation, starting at 0.
1124 Methods are offered to get the quark of an attribute from its path. The API
1125 methods for inserting state changes and doing queries normally use quarks
1126 instead of paths. This is to encourage users to cache the quarks and re-use
1127 them, which avoids re-walking the attribute tree over and over, which avoids
1128 unneeded hashing of strings.
1132 The path and quark of an attribute will remain constant for the whole duration
1133 of the trace. However, the value carried by the attribute will change. The value
1134 of a specific attribute at a specific time is called the state value.
1136 In the TMF implementation, state values can be integers, longs, or strings.
1137 There is also a "null value" type, which is used to indicate that no particular
1138 value is active for this attribute at this time, but without resorting to a
1141 Any other type of value could be used, as long as the backend knows how to store
1144 Note that the TMF implementation also forces every attribute to always carry the
1145 same type of state value. This is to make it simpler for views, so they can
1146 expect that an attribute will always use a given type, without having to check
1147 every single time. Null values are an exception, they are always allowed for all
1148 attributes, since they can safely be "unboxed" into all types.
1150 === State change ===
1152 A state change is the element that is inserted in the state system. It consists
1154 * a timestamp (the time at which the state change occurs)
1155 * an attribute (the attribute whose value will change)
1156 * a state value (the new value that the attribute will carry)
1158 It's not an object per se in the TMF implementation (it's represented by a
1159 function call in the state provider). Typically, the state provider will insert
1160 zero, one or more state changes for every trace event, depending on its event
1163 Note, we use "timestamp" here, but it's in fact a generic term that could be
1164 referred to as "index". For example, if a given trace type has no notion of
1165 timestamp, the event rank could be used.
1167 In the TMF implementation, the timestamp is a long (64-bit integer).
1169 === State interval ===
1171 State changes are inserted into the state system, but state intervals are the
1172 objects that come out on the other side. Those are stocked in the storage
1173 backend. A state interval represents a "state" of an attribute we want to track.
1174 When doing queries on the state system, intervals are what is returned. The
1175 components of a state interval are:
1181 The start and end times represent the time range of the state. The state value
1182 is the same as the state value in the state change that started this interval.
1183 The interval also keeps a reference to its quark, although you normally know
1184 your quark in advance when you do queries.
1186 === State history ===
1188 The state history is the name of the container for all the intervals created by
1189 the state system. The exact implementation (how the intervals are stored) is
1190 determined by the storage backend that is used.
1192 Some backends will use a state history that is peristent on disk, others do not.
1193 When loading a trace, if a history file is available and the backend supports
1194 it, it will be loaded right away, skipping the need to go through another
1197 === Construction phase ===
1199 Before we can query a state system, we need to build the state history first. To
1200 do so, trace events are sent one-by-one through the state provider, which in
1201 turn sends state changes to the central component, which then creates intervals
1202 and stores them in the backend. This is called the construction phase.
1204 Note that the state system needs to receive its events into chronological order.
1205 This phase will end once the end of the trace is reached.
1207 Also note that it is possible to query the state system while it is being build.
1208 Any timestamp between the start of the trace and the current end time of the
1209 state system (available with ITmfStateSystem#getCurrentEndTime()) is a valid
1210 timestamp that can be queried.
1214 As mentioned previously, when doing queries on the state system, the returned
1215 objects will be state intervals. In most cases it's the state *value* we are
1216 interested in, but since the backend has to instantiate the interval object
1217 anyway, there is no additional cost to return the interval instead. This way we
1218 also get the start and end times of the state "for free".
1220 There are two types of queries that can be done on the state system:
1222 ==== Full queries ====
1224 A full query means that we want to retrieve the whole state of the model for one
1225 given timestamp. As we remember, this means "the state of every single attribute
1226 in the model". As parameter we only need to pass the timestamp (see the API
1227 methods below). The return value will be an array of intervals, where the offset
1228 in the array represents the quark of each attribute.
1230 ==== Single queries ====
1232 In other cases, we might only be interested in the state of one particular
1233 attribute at one given timestamp. For these cases it's better to use a
1234 single query. For a single query. we need to pass both a timestamp and a
1235 quark in parameter. The return value will be a single interval, representing
1236 the state that this particular attribute was at that time.
1238 Single queries are typically faster than full queries (but once again, this
1239 depends on the backend that is used), but not by much. Even if you only want the
1240 state of say 10 attributes out of 200, it could be faster to use a full query
1241 and only read the ones you need. Single queries should be used for cases where
1242 you only want one attribute per timestamp (for example, if you follow the state
1243 of the same attribute over a time range).
1246 == Relevant interfaces/classes ==
1248 This section will describe the public interface and classes that can be used if
1249 you want to use the state system.
1251 === Main classes in org.eclipse.linuxtools.tmf.core.statesystem ===
1253 ==== ITmfStateProvider / AbstractTmfStateProvider ====
1255 ITmfStateProvider is the interface you have to implement to define your state
1256 provider. This is where most of the work has to be done to use a state system
1257 for a custom trace type or analysis type.
1259 For first-time users, it's recommended to extend AbstractTmfStateProvider
1260 instead. This class takes care of all the initialization mumbo-jumbo, and also
1261 runs the event handler in a separate thread. You will only need to implement
1262 eventHandle, which is the call-back that will be called for every event in the
1265 For an example, you can look at StatsStateProvider in the TMF tree, or at the
1266 small example below.
1268 ==== TmfStateSystemFactory ====
1270 Once you have defined your state provider, you need to tell your trace type to
1271 build a state system with this provider during its initialization. This consists
1272 of overriding TmfTrace#buildStateSystems() and in there of calling the method in
1273 TmfStateSystemFactory that corresponds to the storage backend you want to use
1274 (see the section [[#Comparison of state system backends]]).
1276 You will have to pass in parameter the state provider you want to use, which you
1277 should have defined already. Each backend can also ask for more configuration
1280 You must then call registerStateSystem(id, statesystem) to make your state
1281 system visible to the trace objects and the views. The ID can be any string of
1282 your choosing. To access this particular state system, the views or modules will
1283 need to use this ID.
1285 Also, don't forget to call super.buildStateSystems() in your implementation,
1286 unless you know for sure you want to skip the state providers built by the
1289 You can look at how LttngKernelTrace does it for an example. It could also be
1290 possible to build a state system only under certain conditions (like only if the
1291 trace contains certain event types).
1294 ==== ITmfStateSystem ====
1296 ITmfStateSystem is the main interface through which views or analysis modules
1297 will access the state system. It offers a read-only view of the state system,
1298 which means that no states can be inserted, and no attributes can be created.
1299 Calling TmfTrace#getStateSystems().get(id) will return you a ITmfStateSystem
1300 view of the requested state system. The main methods of interest are:
1302 ===== getQuarkAbsolute()/getQuarkRelative() =====
1304 Those are the basic quark-getting methods. The goal of the state system is to
1305 return the state values of given attributes at given timestamps. As we've seen
1306 earlier, attributes can be described with a file-system-like path. The goal of
1307 these methods is to convert from the path representation of the attribute to its
1310 Since quarks are created on-the-fly, there is no guarantee that the same
1311 attributes will have the same quark for two traces of the same type. The views
1312 should always query their quarks when dealing with a new trace or a new state
1313 provider. Beyond that however, quarks should be cached and reused as much as
1314 possible, to avoid potentially costly string re-hashing.
1316 getQuarkAbsolute() takes a variable amount of Strings in parameter, which
1317 represent the full path to the attribute. Some of them can be constants, some
1318 can come programatically, often from the event's fields.
1320 getQuarkRelative() is to be used when you already know the quark of a certain
1321 attribute, and want to access on of its sub-attributes. Its first parameter is
1322 the origin quark, followed by a String varagrs which represent the relative path
1323 to the final attribute.
1325 These two methods will throw an AttributeNotFoundException if trying to access
1326 an attribute that does not exist in the model.
1328 These methods also imply that the view has the knowledge of how the attribute
1329 tree is organized. This should be a reasonable hypothesis, since the same
1330 analysis plugin will normally ship both the state provider and the view, and
1331 they will have been written by the same person. In other cases, it's possible to
1332 use getSubAttributes() to explore the organization of the attribute tree first.
1334 ===== waitUntilBuilt() =====
1336 This is a simple method used to block the caller until the construction phase of
1337 this state system is done. If the view prefers to wait until all information is
1338 available before starting to do queries (to get all known attributes right away,
1339 for example), this is the guy to call.
1341 ===== queryFullState() =====
1343 This is the method to do full queries. As mentioned earlier, you only need to
1344 pass a target timestamp in parameter. It will return a List of state intervals,
1345 in which the offset corresponds to the attribute quark. This will represent the
1346 complete state of the model at the requested time.
1348 ===== querySingleState() =====
1350 The method to do single queries. You pass in parameter both a timestamp and an
1351 attribute quark. This will return the single state matching this
1352 timestamp/attribute pair.
1354 Other methods are available, you are encouraged to read their Javadoc and see if
1355 they can be potentially useful.
1357 ==== ITmfStateSystemBuilder ====
1359 ITmfStateSystemBuilder is the read-write interface to the state system. It
1360 extends ITmfStateSystem itself, so all its methods are available. It then adds
1361 methods that can be used to write to the state system, either by creating new
1362 attributes of inserting state changes.
1364 It is normally reserved for the state provider and should not be visible to
1365 external components. However it will be available in AbstractTmfStateProvider,
1366 in the field 'ss'. That way you can call ss.modifyAttribute() etc. in your state
1367 provider to write to the state.
1369 The main methods of interest are:
1371 ===== getQuark*AndAdd() =====
1373 getQuarkAbsoluteAndAdd() and getQuarkRelativeAndAdd() work exactly like their
1374 non-AndAdd counterparts in ITmfStateSystem. The difference is that the -AndAdd
1375 versions will not throw any exception: if the requested attribute path does not
1376 exist in the system, it will be created, and its newly-assigned quark will be
1379 When in a state provider, the -AndAdd version should normally be used (unless
1380 you know for sure the attribute already exist and don't want to create it
1381 otherwise). This means that there is no need to define the whole attribute tree
1382 in advance, the attributes will be created on-demand.
1384 ===== modifyAttribute() =====
1386 This is the main state-change-insertion method. As was explained before, a state
1387 change is defined by a timestamp, an attribute and a state value. Those three
1388 elements need to be passed to modifyAttribute as parameters.
1390 Other state change insertion methods are available (increment-, push-, pop- and
1391 removeAttribute()), but those are simply convenience wrappers around
1392 modifyAttribute(). Check their Javadoc for more information.
1394 ===== closeHistory() =====
1396 When the construction phase is done, do not forget to call closeHistory() to
1397 tell the backend that no more intervals will be received. Depending on the
1398 backend type, it might have to save files, close descriptors, etc. This ensures
1399 that a persitent file can then be re-used when the trace is opened again.
1401 If you use the AbstractTmfStateProvider, it will call closeHistory()
1402 automatically when it reaches the end of the trace.
1404 === Other relevant interfaces ===
1406 ==== o.e.l.tmf.core.statevalue.ITmfStateValue ====
1408 This is the interface used to represent state values. Those are used when
1409 inserting state changes in the provider, and is also part of the state intervals
1410 obtained when doing queries.
1412 The abstract TmfStateValue class contains the factory methods to create new
1413 state values of either int, long or string types. To retrieve the real object
1414 inside the state value, one can use the .unbox* methods.
1416 Note: Do not instantiate null values manually, use TmfStateValue.nullValue()
1418 ==== o.e.l.tmf.core.interval.ITmfStateInterval ====
1420 This is the interface to represent the state intervals, which are stored in the
1421 state history backend, and are returned when doing state system queries. A very
1422 simple implementation is available in TmfStateInterval. Its methods should be
1427 The following exceptions, found in o.e.l.tmf.core.exceptions, are related to
1428 state system activities.
1430 ==== AttributeNotFoundException ====
1432 This is thrown by getQuarkRelative() and getQuarkAbsolute() (but not byt the
1433 -AndAdd versions!) when passing an attribute path that is not present in the
1434 state system. This is to ensure that no new attribute is created when using
1435 these versions of the methods.
1437 Views can expect some attributes to be present, but they should handle these
1438 exceptions for when the attributes end up not being in the state system (perhaps
1439 this particular trace didn't have a certain type of events, etc.)
1441 ==== StateValueTypeException ====
1443 This exception will be thrown when trying to unbox a state value into a type
1444 different than its own. You should always check with ITmfStateValue#getType()
1445 beforehand if you are not sure about the type of a given state value.
1447 ==== TimeRangeException ====
1449 This exception is thrown when trying to do a query on the state system for a
1450 timestamp that is outside of its range. To be safe, you should check with
1451 ITmfStateSystem#getStartTime() and #getCurrentEndTime() for the current valid
1452 range of the state system. This is especially important when doing queries on
1453 a state system that is currently being built.
1455 ==== StateSystemDisposedException ====
1457 This exception is thrown when trying to access a state system that has been
1458 disposed, with its dispose() method. This can potentially happen at shutdown,
1459 since Eclipse is not always consistent with the order in which the components
1463 == Comparison of state system backends ==
1465 As we have seen in section [[#High-level components]], the state system needs
1466 a storage backend to save the intervals. Different implementations are
1467 available when building your state system from TmfStateSystemFactory.
1469 Do not confuse full/single queries with full/partial history! All backend types
1470 should be able to handle any type of queries defined in the ITmfStateSystem API,
1471 unless noted otherwise.
1473 === Full history ===
1475 Available with TmfStateSystemFactory#newFullHistory(). The full history uses a
1476 History Tree data structure, which is an optimized structure store state
1477 intervals on disk. Once built, it can respond to queries in a ''log(n)'' manner.
1479 You need to specify a file at creation time, which will be the container for
1480 the history tree. Once it's completely built, it will remain on disk (until you
1481 delete the trace from the project). This way it can be reused from one session
1482 to another, which makes subsequent loading time much faster.
1484 This the backend used by the LTTng kernel plugin. It offers good scalability and
1485 performance, even at extreme sizes (it's been tested with traces of sizes up to
1486 500 GB). Its main downside is the amount of disk space required: since every
1487 single interval is written to disk, the size of the history file can quite
1488 easily reach and even surpass the size of the trace itself.
1490 === Null history ===
1492 Available with TmfStateSystemFactory#newNullHistory(). As its name implies the
1493 null history is in fact an absence of state history. All its query methods will
1494 return null (see the Javadoc in NullBackend).
1496 Obviously, no file is required, and almost no memory space is used.
1498 It's meant to be used in cases where you are not interested in past states, but
1499 only in the "ongoing" one. It can also be useful for debugging and benchmarking.
1501 === In-memory history ===
1503 Available with TmfStateSystemFactory#newInMemHistory(). This is a simple wrapper
1504 using an ArrayList to store all state intervals in memory. The implementation
1505 at the moment is quite simple, it will iterate through all entries when doing
1506 queries to find the ones that match.
1508 The advantage of this method is that it's very quick to build and query, since
1509 all the information resides in memory. However, you are limited to 2^31 entries
1510 (roughly 2 billions), and depending on your state provider and trace type, that
1511 can happen really fast!
1513 There are no safeguards, so if you bust the limit you will end up with
1514 ArrayOutOfBoundsException's everywhere. If your trace or state history can be
1515 arbitrarily big, it's probably safer to use a Full History instead.
1517 === Partial history ===
1519 Available with TmfStateSystemFactory#newPartialHistory(). The partial history is
1520 a more advanced form of the full history. Instead of writing all state intervals
1521 to disk like with the full history, we only write a small fraction of them, and
1522 go back to read the trace to recreate the states in-between.
1524 It has a big advantage over a full history in terms of disk space usage. It's
1525 very possible to reduce the history tree file size by a factor of 1000, while
1526 keeping query times within a factor of two. Its main downside comes from the
1527 fact that you cannot do efficient single queries with it (they are implemented
1528 by doing full queries underneath).
1530 This makes it a poor choice for views like the Control Flow view, where you do
1531 a lot of range queries and single queries. However, it is a perfect fit for
1532 cases like statistics, where you usually do full queries already, and you store
1533 lots of small states which are very easy to "compress".
1535 However, it can't really be used until bug 409630 is fixed.
1539 Here is a small example of code that will use the state system. For this
1540 example, let's assume we want to track the state of all the CPUs in a LTTng
1541 kernel trace. To do so, we will watch for the "sched_switch" event in the state
1542 provider, and will update an attribute indicating if the associated CPU should
1543 be set to "running" or "idle".
1545 We will use an attribute tree that looks like this:
1559 The second-level attributes will be named from the information available in the
1560 trace events. Only the "Status" attributes will carry a state value (this means
1561 we could have just used "1", "2", "3",... directly, but we'll do it in a tree
1562 for the example's sake).
1564 Also, we will use integer state values to represent "running" or "idle", instead
1565 of saving the strings that would get repeated every time. This will help in
1566 reducing the size of the history file.
1568 First we will define a state provider in MyStateProvider. Then, assuming we
1569 have already implemented a custom trace type extending CtfTmfTrace, we will add
1570 a section to it to make it build a state system using the provider we defined
1571 earlier. Finally, we will show some example code that can query the state
1572 system, which would normally go in a view or analysis module.
1574 === State Provider ===
1577 import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfEvent;
1578 import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
1579 import org.eclipse.linuxtools.tmf.core.exceptions.AttributeNotFoundException;
1580 import org.eclipse.linuxtools.tmf.core.exceptions.StateValueTypeException;
1581 import org.eclipse.linuxtools.tmf.core.exceptions.TimeRangeException;
1582 import org.eclipse.linuxtools.tmf.core.statesystem.AbstractTmfStateProvider;
1583 import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
1584 import org.eclipse.linuxtools.tmf.core.statevalue.TmfStateValue;
1585 import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace;
1588 * Example state system provider.
1590 * @author Alexandre Montplaisir
1592 public class MyStateProvider extends AbstractTmfStateProvider {
1594 /** State value representing the idle state */
1595 public static ITmfStateValue IDLE = TmfStateValue.newValueInt(0);
1597 /** State value representing the running state */
1598 public static ITmfStateValue RUNNING = TmfStateValue.newValueInt(1);
1604 * The trace to which this state provider is associated
1606 public MyStateProvider(ITmfTrace trace) {
1607 super(trace, CtfTmfEvent.class, "Example"); //$NON-NLS-1$
1609 * The third parameter here is not important, it's only used to name a
1610 * thread internally.
1615 public int getVersion() {
1617 * If the version of an existing file doesn't match the version supplied
1618 * in the provider, a rebuild of the history will be forced.
1624 public MyStateProvider getNewInstance() {
1625 return new MyStateProvider(getTrace());
1629 protected void eventHandle(ITmfEvent ev) {
1631 * AbstractStateChangeInput should have already checked for the correct
1634 CtfTmfEvent event = (CtfTmfEvent) ev;
1636 final long ts = event.getTimestamp().getValue();
1637 Integer nextTid = ((Long) event.getContent().getField("next_tid").getValue()).intValue();
1641 if (event.getEventName().equals("sched_switch")) {
1642 int quark = ss.getQuarkAbsoluteAndAdd("CPUs", String.valueOf(event.getCPU()), "Status");
1643 ITmfStateValue value;
1649 ss.modifyAttribute(ts, value, quark);
1652 } catch (TimeRangeException e) {
1654 * This should not happen, since the timestamp comes from a trace
1657 throw new IllegalStateException(e);
1658 } catch (AttributeNotFoundException e) {
1660 * This should not happen either, since we're only accessing a quark
1663 throw new IllegalStateException(e);
1664 } catch (StateValueTypeException e) {
1666 * This wouldn't happen here, but could potentially happen if we try
1667 * to insert mismatching state value types in the same attribute.
1669 e.printStackTrace();
1677 === Trace type definition ===
1680 import java.io.File;
1682 import org.eclipse.core.resources.IProject;
1683 import org.eclipse.core.runtime.IStatus;
1684 import org.eclipse.core.runtime.Status;
1685 import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfTrace;
1686 import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
1687 import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateProvider;
1688 import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateSystem;
1689 import org.eclipse.linuxtools.tmf.core.statesystem.TmfStateSystemFactory;
1690 import org.eclipse.linuxtools.tmf.core.trace.TmfTraceManager;
1693 * Example of a custom trace type using a custom state provider.
1695 * @author Alexandre Montplaisir
1697 public class MyTraceType extends CtfTmfTrace {
1699 /** The file name of the history file */
1700 public final static String HISTORY_FILE_NAME = "mystatefile.ht";
1702 /** ID of the state system we will build */
1703 public static final String STATE_ID = "org.eclipse.linuxtools.lttng2.example";
1706 * Default constructor
1708 public MyTraceType() {
1713 public IStatus validate(final IProject project, final String path) {
1715 * Add additional validation code here, and return a IStatus.ERROR if
1718 return Status.OK_STATUS;
1722 protected void buildStateSystem() throws TmfTraceException {
1723 super.buildStateSystem();
1725 /* Build the custom state system for this trace */
1726 String directory = TmfTraceManager.getSupplementaryFileDir(this);
1727 final File htFile = new File(directory + HISTORY_FILE_NAME);
1728 final ITmfStateProvider htInput = new MyStateProvider(this);
1730 ITmfStateSystem ss = TmfStateSystemFactory.newFullHistory(htFile, htInput, false);
1731 fStateSystems.put(STATE_ID, ss);
1740 import java.util.List;
1742 import org.eclipse.linuxtools.tmf.core.exceptions.AttributeNotFoundException;
1743 import org.eclipse.linuxtools.tmf.core.exceptions.StateSystemDisposedException;
1744 import org.eclipse.linuxtools.tmf.core.exceptions.TimeRangeException;
1745 import org.eclipse.linuxtools.tmf.core.interval.ITmfStateInterval;
1746 import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateSystem;
1747 import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
1748 import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace;
1751 * Class showing examples of state system queries.
1753 * @author Alexandre Montplaisir
1755 public class QueryExample {
1757 private final ITmfStateSystem ss;
1763 * Trace that this "view" will display.
1765 public QueryExample(ITmfTrace trace) {
1766 ss = trace.getStateSystems().get(MyTraceType.STATE_ID);
1770 * Example method of querying one attribute in the state system.
1772 * We pass it a cpu and a timestamp, and it returns us if that cpu was
1773 * executing a process (true/false) at that time.
1778 * The timestamp of the query
1779 * @return True if the CPU was running, false otherwise
1781 public boolean cpuIsRunning(int cpu, long timestamp) {
1783 int quark = ss.getQuarkAbsolute("CPUs", String.valueOf(cpu), "Status");
1784 ITmfStateValue value = ss.querySingleState(timestamp, quark).getStateValue();
1786 if (value.equals(MyStateProvider.RUNNING)) {
1791 * Since at this level we have no guarantee on the contents of the state
1792 * system, it's important to handle these cases correctly.
1794 } catch (AttributeNotFoundException e) {
1796 * Handle the case where the attribute does not exist in the state
1797 * system (no CPU with this number, etc.)
1800 } catch (TimeRangeException e) {
1802 * Handle the case where 'timestamp' is outside of the range of the
1806 } catch (StateSystemDisposedException e) {
1808 * Handle the case where the state system is being disposed. If this
1809 * happens, it's normally when shutting down, so the view can just
1810 * return immediately and wait it out.
1818 * Example method of using a full query.
1820 * We pass it a timestamp, and it returns us how many CPUs were executing a
1821 * process at that moment.
1824 * The target timestamp
1825 * @return The amount of CPUs that were running at that time
1827 public int getNbRunningCpus(long timestamp) {
1831 /* Get the list of the quarks we are interested in. */
1832 List<Integer> quarks = ss.getQuarks("CPUs", "*", "Status");
1835 * Get the full state at our target timestamp (it's better than
1836 * doing an arbitrary number of single queries).
1838 List<ITmfStateInterval> state = ss.queryFullState(timestamp);
1840 /* Look at the value of the state for each quark */
1841 for (Integer quark : quarks) {
1842 ITmfStateValue value = state.get(quark).getStateValue();
1843 if (value.equals(MyStateProvider.RUNNING)) {
1848 } catch (TimeRangeException e) {
1850 * Handle the case where 'timestamp' is outside of the range of the
1854 } catch (StateSystemDisposedException e) {
1855 /* Handle the case where the state system is being disposed. */
1863 = UML2 Sequence Diagram Framework =
1865 The purpose of the UML2 Sequence Diagram Framework of TMF is to provide a framework for generation of UML2 sequence diagrams. It provides
1866 *UML2 Sequence diagram drawing capabilities (i.e. lifelines, messages, activations, object creation and deletion)
1867 *a generic, re-usable Sequence Diagram View
1868 *Eclipse Extension Point for the creation of sequence diagrams
1869 *callback hooks for searching and filtering within the Sequence Diagram View
1871 The following chapters describe the Sequence Diagram Framework as well as a reference implementation and its usage.
1873 == TMF UML2 Sequence Diagram Extensions ==
1875 In the UML2 Sequence Diagram Framework an Eclipse extension point is defined so that other plug-ins can contribute code to create sequence diagram.
1877 '''Identifier''': org.eclipse.linuxtools.tmf.ui.uml2SDLoader<br>
1878 '''Since''': Since 0.3.2 (based on UML2SD of org.eclipse.tptp.common.ui)<br>
1879 '''Description''': This extension point aims to list and connect any UML2 Sequence Diagram loader.<br>
1880 '''Configuration Markup''':<br>
1883 <!ELEMENT extension (uml2SDLoader)+>
1885 point CDATA #REQUIRED
1891 *point - A fully qualified identifier of the target extension point.
1892 *id - An optional identifier of the extension instance.
1893 *name - An optional name of the extension instance.
1896 <!ELEMENT uml2SDLoader EMPTY>
1897 <!ATTLIST uml2SDLoader
1899 name CDATA #REQUIRED
1900 class CDATA #REQUIRED
1901 view CDATA #REQUIRED
1902 default (true | false)
1905 *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.
1906 *name - An name of the extension instance.
1907 *class - The implementation of this UML2 SD viewer loader. The class must implement org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader.
1908 *view - The view ID of the view that this loader aims to populate. Either org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView itself or a extension of org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView.
1909 *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.
1912 == Management of the Extension Point ==
1914 The TMF UI plug-in is responsible for evaluating each contribution to the extension point.
1917 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]])
1919 == Sequence Diagram View ==
1921 For this extension point a Sequence Diagram View has to be defined as well. The Sequence Diagram View class implementation is provided by the plug-in ''org.eclipse.linuxtools.tmf.ui'' (''org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView'') and can be used as is or can also be sub-classed. For that, a view extension has to be added to the ''plugin.xml''.
1923 === Supported Widgets ===
1925 The loader class provides a frame containing all the UML2 widgets to be displayed. The following widgets exist:
1929 *Synchronous Message
1930 *Asynchronous Message
1931 *Synchronous Message Return
1932 *Asynchronous Message Return
1935 For a lifeline, a category can be defined. The lifeline category defines icons, which are displayed in the lifeline header.
1939 The Sequence Diagram View allows the user to zoom in, zoom out and reset the zoom factor.
1943 It is possible to print the whole sequence diagram as well as part of it.
1945 === Key Bindings ===
1947 *SHIFT+ALT+ARROW-DOWN - to scroll down within sequence diagram one view page at a time
1948 *SHIFT+ALT+ARROW-UP - to scroll up within sequence diagram one view page at a time
1949 *SHIFT+ALT+ARROW-RIGHT - to scroll right within sequence diagram one view page at a time
1950 *SHIFT+ALT+ARROW-LEFT - to scroll left within sequence diagram one view page at a time
1951 *SHIFT+ALT+ARROW-HOME - to jump to the beginning of the selected message if not already visible in page
1952 *SHIFT+ALT+ARROW-END - to jump to the end of the selected message if not already visible in page
1953 *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]])
1954 *CTRL+P - to open print dialog
1958 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>
1959 [[Image:images/SeqDiagramPref.png]] <br>
1960 After changing the preferences select '''OK'''.
1962 === Callback hooks ===
1964 The Sequence Diagram View provides several callback hooks so that extension can provide application specific functionality. The following interfaces can be provided:
1965 * Basic find provider or extended find Provider<br> For finding within the sequence diagram
1966 * Basic filter provider and extended Filter Provider<br> For filtering within the sequnce diagram.
1967 * Basic paging provider or advanced paging provider<br> For scalability reasons, used to limit number of displayed messages
1968 * Properies provider<br> To provide properties of selected elements
1969 * Collapse provider <br> To collapse areas of the sequence diagram
1973 This tutorial describes how to create a UML2 Sequence Diagram Loader extension and use this loader in the in Eclipse.
1975 === Prerequisites ===
1977 The tutorial is based on Eclipse 3.7 (Eclipse Indigo) and TMF 0.3.2.
1979 === Creating an Eclipse UI Plug-in ===
1981 To create a new project with name org.eclipse.linuxtools.tmf.sample.ui select '''File -> New -> Project -> Plug-in Development -> Plug-in Project'''. <br>
1982 [[Image:images/Screenshot-NewPlug-inProject1.png]]<br>
1984 [[Image:images/Screenshot-NewPlug-inProject2.png]]<br>
1986 [[Image:images/Screenshot-NewPlug-inProject3.png]]<br>
1988 === Creating a Sequence Diagram View ===
1990 To open the plug-in manifest, double-click on the MANIFEST.MF file. <br>
1991 [[Image:images/SelectManifest.png]]<br>
1993 Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.linuxtools.tmf.ui'' and press '''OK'''<br>
1994 [[Image:images/AddDependencyTmfUi.png]]<br>
1996 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>
1997 [[Image:images/AddViewExtension1.png]]<br>
1999 To create a Sequence Diagram View, click the right mouse button. Then select '''New -> view'''<br>
2000 [[Image:images/AddViewExtension2.png]]<br>
2002 A new view entry has been created. Fill in the fields ''id'', ''name'' and ''class''. Note that for ''class'' the SD view implementation (''org.eclipse.linuxtools.tmf.ui.views.SDView'') of the TMF UI plug-in is used.<br>
2003 [[Image:images/FillSampleSeqDiagram.png]]<br>
2005 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>
2006 [[Image:images/RunEclipseApplication.png]]<br>
2008 A new Eclipse application window will show. In the new window go to '''Windows -> Show View -> Other... -> Other -> Sample Sequence Diagram'''.<br>
2009 [[Image:images/ShowViewOther.png]]<br>
2011 The Sequence Diagram View will open with an blank page.<br>
2012 [[Image:images/BlankSampleSeqDiagram.png]]<br>
2014 Close the Example Application.
2016 === Defining the uml2SDLoader Extension ===
2018 After defining the Sequence Diagram View it's time to create the ''uml2SDLoader'' Extension. <br>
2020 Before doing that add a dependency to TMF. For that select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.linuxtools.tmf'' and press '''OK'''<br>
2021 [[Image:images/AddDependencyTmf.png]]<br>
2023 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>
2024 [[Image:images/AddTmfUml2SDLoader.png]]<br>
2026 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>
2027 [[Image:images/FillSampleLoader.png]]<br>
2029 Then click on ''class'' (see above) to open the new class dialog box. Fill in the relevant fields and select '''Finish'''. <br>
2030 [[Image:images/NewSampleLoaderClass.png]]<br>
2032 A new Java class will be created which implements the interface ''org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader''.<br>
2035 package org.eclipse.linuxtools.tmf.sample.ui;
2037 import org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView;
2038 import org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader;
2040 public class SampleLoader implements IUml2SDLoader {
2042 public SampleLoader() {
2043 // TODO Auto-generated constructor stub
2047 public void dispose() {
2048 // TODO Auto-generated method stub
2053 public String getTitleString() {
2054 // TODO Auto-generated method stub
2059 public void setViewer(SDView arg0) {
2060 // TODO Auto-generated method stub
2065 === Implementing the Loader Class ===
2067 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>
2070 package org.eclipse.linuxtools.tmf.sample.ui;
2072 import org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView;
2073 import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.AsyncMessage;
2074 import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.AsyncMessageReturn;
2075 import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.ExecutionOccurrence;
2076 import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.Frame;
2077 import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.Lifeline;
2078 import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.Stop;
2079 import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.SyncMessage;
2080 import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.SyncMessageReturn;
2081 import org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader;
2083 public class SampleLoader implements IUml2SDLoader {
2085 private SDView fSdView;
2087 public SampleLoader() {
2091 public void dispose() {
2095 public String getTitleString() {
2096 return "Sample Diagram";
2100 public void setViewer(SDView arg0) {
2105 private void createFrame() {
2107 Frame testFrame = new Frame();
2108 testFrame.setName("Sample Frame");
2114 Lifeline lifeLine1 = new Lifeline();
2115 lifeLine1.setName("Object1");
2116 testFrame.addLifeLine(lifeLine1);
2118 Lifeline lifeLine2 = new Lifeline();
2119 lifeLine2.setName("Object2");
2120 testFrame.addLifeLine(lifeLine2);
2124 * Create Sync Message
2126 // Get new occurrence on lifelines
2127 lifeLine1.getNewEventOccurrence();
2129 // Get Sync message instances
2130 SyncMessage start = new SyncMessage();
2131 start.setName("Start");
2132 start.setEndLifeline(lifeLine1);
2133 testFrame.addMessage(start);
2136 * Create Sync Message
2138 // Get new occurrence on lifelines
2139 lifeLine1.getNewEventOccurrence();
2140 lifeLine2.getNewEventOccurrence();
2142 // Get Sync message instances
2143 SyncMessage syn1 = new SyncMessage();
2144 syn1.setName("Sync Message 1");
2145 syn1.setStartLifeline(lifeLine1);
2146 syn1.setEndLifeline(lifeLine2);
2147 testFrame.addMessage(syn1);
2150 * Create corresponding Sync Message Return
2153 // Get new occurrence on lifelines
2154 lifeLine1.getNewEventOccurrence();
2155 lifeLine2.getNewEventOccurrence();
2157 SyncMessageReturn synReturn1 = new SyncMessageReturn();
2158 synReturn1.setName("Sync Message Return 1");
2159 synReturn1.setStartLifeline(lifeLine2);
2160 synReturn1.setEndLifeline(lifeLine1);
2161 synReturn1.setMessage(syn1);
2162 testFrame.addMessage(synReturn1);
2165 * Create Activations (Execution Occurrence)
2167 ExecutionOccurrence occ1 = new ExecutionOccurrence();
2168 occ1.setStartOccurrence(start.getEventOccurrence());
2169 occ1.setEndOccurrence(synReturn1.getEventOccurrence());
2170 lifeLine1.addExecution(occ1);
2171 occ1.setName("Activation 1");
2173 ExecutionOccurrence occ2 = new ExecutionOccurrence();
2174 occ2.setStartOccurrence(syn1.getEventOccurrence());
2175 occ2.setEndOccurrence(synReturn1.getEventOccurrence());
2176 lifeLine2.addExecution(occ2);
2177 occ2.setName("Activation 2");
2180 * Create Sync Message
2182 // Get new occurrence on lifelines
2183 lifeLine1.getNewEventOccurrence();
2184 lifeLine2.getNewEventOccurrence();
2186 // Get Sync message instances
2187 AsyncMessage asyn1 = new AsyncMessage();
2188 asyn1.setName("Async Message 1");
2189 asyn1.setStartLifeline(lifeLine1);
2190 asyn1.setEndLifeline(lifeLine2);
2191 testFrame.addMessage(asyn1);
2194 * Create corresponding Sync Message Return
2197 // Get new occurrence on lifelines
2198 lifeLine1.getNewEventOccurrence();
2199 lifeLine2.getNewEventOccurrence();
2201 AsyncMessageReturn asynReturn1 = new AsyncMessageReturn();
2202 asynReturn1.setName("Async Message Return 1");
2203 asynReturn1.setStartLifeline(lifeLine2);
2204 asynReturn1.setEndLifeline(lifeLine1);
2205 asynReturn1.setMessage(asyn1);
2206 testFrame.addMessage(asynReturn1);
2212 // Get new occurrence on lifelines
2213 lifeLine1.getNewEventOccurrence();
2215 EllipsisisMessage info = new EllipsisisMessage();
2216 info.setName("Object deletion");
2217 info.setStartLifeline(lifeLine2);
2218 testFrame.addNode(info);
2223 Stop stop = new Stop();
2224 stop.setLifeline(lifeLine2);
2225 stop.setEventOccurrence(lifeLine2.getNewEventOccurrence());
2226 lifeLine2.addNode(stop);
2228 fSdView.setFrame(testFrame);
2233 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>
2234 [[Image:images/SampleDiagram1.png]] <br>
2236 === Adding time information ===
2238 To add time information in sequence diagram the timestamp has to be set for each message. The sequence diagram framework uses the ''TmfTimestamp'' class of plug-in ''org.eclipse.linuxtools.tmf''. Use ''setTime()'' on each message ''SyncMessage'' since start and end time are the same. For each ''AsyncMessage'' set start and end time separately by using methods ''setStartTime'' and ''setEndTime''. For example: <br>
2241 private void createFrame() {
2243 start.setTime(new TmfTimestamp(1000, -3));
2244 syn1.setTime(new TmfTimestamp(1005, -3));
2245 synReturn1.setTime(new TmfTimestamp(1050, -3));
2246 asyn1.setStartTime(new TmfTimestamp(1060, -3));
2247 asyn1.setEndTime(new TmfTimestamp(1070, -3));
2248 asynReturn1.setStartTime(new TmfTimestamp(1060, -3));
2249 asynReturn1.setEndTime(new TmfTimestamp(1070, -3));
2254 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>
2256 [[Image:images/SampleDiagramTimeComp.png]] <br>
2258 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.
2260 [[Image:images/SampleDiagramSyncMessage.png]] <br>
2261 [[Image:images/SampleDiagramAsyncMessage.png]] <br>
2263 To see the time elapsed between 2 messages, select one message and hover over a second message. A tooltip will show with the delta in time. Note if the second message is before the first then a negative delta is displayed. Note that for ''AsynMessage'' the end time is used for the delta calculation.<br>
2264 [[Image:images/SampleDiagramMessageDelta.png]] <br>
2266 === Default Coolbar and Menu Items ===
2268 The Sequence Diagram View comes with default coolbar and menu items. By default, each sequence diagram shows the following actions:
2273 * Configure Min Max (drop-down menu only)
2274 * Navigation -> Show the node end (drop-down menu only)
2275 * Navigation -> Show the node start (drop-down menu only)
2277 [[Image:images/DefaultCoolbarMenu.png]]<br>
2279 === Implementing Optional Callbacks ===
2281 The following chapters describe how to use all supported provider interfaces.
2283 ==== Using the Paging Provider Interface ====
2285 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.
2287 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.
2290 public class SampleLoader implements IUml2SDLoader, ISDPagingProvider {
2295 public void dispose() {
2296 if (fSdView != null) {
2297 fSdView.resetProviders();
2302 public void setViewer(SDView arg0) {
2304 fSdView.setSDPagingProvider(this);
2308 private void createSecondFrame() {
2309 Frame testFrame = new Frame();
2310 testFrame.setName("SecondFrame");
2311 Lifeline lifeline = new Lifeline();
2312 lifeline.setName("LifeLine 0");
2313 testFrame.addLifeLine(lifeline);
2314 lifeline = new Lifeline();
2315 lifeline.setName("LifeLine 1");
2316 testFrame.addLifeLine(lifeline);
2317 for (int i = 1; i < 5; i++) {
2318 SyncMessage message = new SyncMessage();
2319 message.autoSetStartLifeline(testFrame.getLifeline(0));
2320 message.autoSetEndLifeline(testFrame.getLifeline(0));
2321 message.setName((new StringBuilder("Message ")).append(i).toString());
2322 testFrame.addMessage(message);
2324 SyncMessageReturn messageReturn = new SyncMessageReturn();
2325 messageReturn.autoSetStartLifeline(testFrame.getLifeline(0));
2326 messageReturn.autoSetEndLifeline(testFrame.getLifeline(0));
2328 testFrame.addMessage(messageReturn);
2329 messageReturn.setName((new StringBuilder("Message return ")).append(i).toString());
2330 ExecutionOccurrence occ = new ExecutionOccurrence();
2331 occ.setStartOccurrence(testFrame.getSyncMessage(i - 1).getEventOccurrence());
2332 occ.setEndOccurrence(testFrame.getSyncMessageReturn(i - 1).getEventOccurrence());
2333 testFrame.getLifeline(0).addExecution(occ);
2335 fSdView.setFrame(testFrame);
2339 public boolean hasNextPage() {
2344 public boolean hasPrevPage() {
2349 public void nextPage() {
2351 createSecondFrame();
2355 public void prevPage() {
2361 public void firstPage() {
2367 public void lastPage() {
2369 createSecondFrame();
2376 When running the example application, new actions will be shown in the coolbar and the coolbar menu. <br>
2378 [[Image:images/PageProviderAdded.png]]
2381 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.
2384 ==== Using the Find Provider Interface ====
2386 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.
2388 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.
2390 Only on at a time can be active. If the extended find provder is defined it obsoletes the basic find provider.
2392 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.
2395 public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider {
2399 public void dispose() {
2400 if (fSdView != null) {
2401 fSdView.resetProviders();
2406 public void setViewer(SDView arg0) {
2408 fSdView.setSDPagingProvider(this);
2409 fSdView.setSDFindProvider(this);
2414 public boolean isNodeSupported(int nodeType) {
2416 case ISDGraphNodeSupporter.LIFELINE:
2417 case ISDGraphNodeSupporter.SYNCMESSAGE:
2427 public String getNodeName(int nodeType, String loaderClassName) {
2429 case ISDGraphNodeSupporter.LIFELINE:
2431 case ISDGraphNodeSupporter.SYNCMESSAGE:
2432 return "Sync Message";
2438 public boolean find(Criteria criteria) {
2439 Frame frame = fSdView.getFrame();
2440 if (criteria.isLifeLineSelected()) {
2441 for (int i = 0; i < frame.lifeLinesCount(); i++) {
2442 if (criteria.matches(frame.getLifeline(i).getName())) {
2443 fSdView.getSDWidget().moveTo(frame.getLifeline(i));
2448 if (criteria.isSyncMessageSelected()) {
2449 for (int i = 0; i < frame.syncMessageCount(); i++) {
2450 if (criteria.matches(frame.getSyncMessage(i).getName())) {
2451 fSdView.getSDWidget().moveTo(frame.getSyncMessage(i));
2460 public void cancel() {
2461 // reset find parameters
2467 When running the example application, the find action will be shown in the coolbar and the coolbar menu. <br>
2468 [[Image:images/FindProviderAdded.png]]
2470 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>
2471 [[Image:images/FindDialog.png]]<br>
2473 Note that the find dialog will be opened by typing the key shortcut CRTL+F.
2475 ==== Using the Filter Provider Interface ====
2477 For filtering of sequence diagram elements two interfaces exists. One basic for filtering and one for extended filtering. The basic filtering comes with two dialog for entering filter 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.
2479 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>
2480 Note that no example implementation of ''filter()'' is provided.
2484 public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider {
2488 public void dispose() {
2489 if (fSdView != null) {
2490 fSdView.resetProviders();
2495 public void setViewer(SDView arg0) {
2497 fSdView.setSDPagingProvider(this);
2498 fSdView.setSDFindProvider(this);
2499 fSdView.setSDFilterProvider(this);
2504 public boolean filter(List<?> list) {
2511 When running the example application, the filter action will be shown in the coolbar menu. <br>
2512 [[Image:images/HidePatternsMenuItem.png]]
2514 To filter select the '''Hide Patterns...''' of the coolbar menu. A new dialog box will open. <br>
2515 [[Image:images/DialogHidePatterns.png]]
2517 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>
2518 [[Image:images/DialogHidePatterns.png]] <br>
2520 Now back at the Hide Pattern dialog. Select one or more filter and select '''OK'''.
2522 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.
2524 ==== Using the Extended Action Bar Provider Interface ====
2526 The extended action bar provider can be used to add customized actions to the Sequence Diagram View.
2527 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>
2530 public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider, ISDExtendedActionBarProvider {
2534 public void dispose() {
2535 if (fSdView != null) {
2536 fSdView.resetProviders();
2541 public void setViewer(SDView arg0) {
2543 fSdView.setSDPagingProvider(this);
2544 fSdView.setSDFindProvider(this);
2545 fSdView.setSDFilterProvider(this);
2546 fSdView.setSDExtendedActionBarProvider(this);
2551 public void supplementCoolbarContent(IActionBars iactionbars) {
2552 Action action = new Action("Refresh") {
2555 System.out.println("Refreshing...");
2558 iactionbars.getMenuManager().add(action);
2559 iactionbars.getToolBarManager().add(action);
2565 When running the example application, all new actions will be added to the coolbar and coolbar menu according to the implementation of ''supplementCoolbarContent()''<br>.
2566 For the example above the coolbar and coolbar menu will look as follows.
2568 [[Image:images/SupplCoolbar.png]]
2570 ==== Using the Properties Provider Interface====
2572 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>
2574 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.
2576 Please refer to the following Eclipse articles for more information about properties and tabed properties.
2577 *[http://www.eclipse.org/articles/Article-Properties-View/properties-view.html | Take control of your properties]
2578 *[http://www.eclipse.org/articles/Article-Tabbed-Properties/tabbed_properties_view.html | The Eclipse Tabbed Properties View]
2580 ==== Using the Collapse Provider Interface ====
2582 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.
2584 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.
2586 ==== Using the Selection Provider Service ====
2588 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.
2591 public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider, ISDExtendedActionBarProvider, ISelectionListener {
2595 public void dispose() {
2596 if (fSdView != null) {
2597 PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().removePostSelectionListener(this);
2598 fSdView.resetProviders();
2603 public String getTitleString() {
2604 return "Sample Diagram";
2608 public void setViewer(SDView arg0) {
2610 PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().addPostSelectionListener(this);
2611 fSdView.setSDPagingProvider(this);
2612 fSdView.setSDFindProvider(this);
2613 fSdView.setSDFilterProvider(this);
2614 fSdView.setSDExtendedActionBarProvider(this);
2620 public void selectionChanged(IWorkbenchPart part, ISelection selection) {
2621 ISelection sel = PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().getSelection();
2622 if (sel != null && (sel instanceof StructuredSelection)) {
2623 StructuredSelection stSel = (StructuredSelection) sel;
2624 if (stSel.getFirstElement() instanceof BaseMessage) {
2625 BaseMessage syncMsg = ((BaseMessage) stSel.getFirstElement());
2626 System.out.println("Message '" + syncMsg.getName() + "' selected.");
2635 === Printing a Sequence Diagram ===
2637 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>
2639 [[Image:images/PrintDialog.png]] <br>
2641 Fill in all the relevant information, select '''Printer...''' to choose the printer and the press '''OK'''.
2643 === Using one Sequence Diagram View with Multiple Loaders ===
2645 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:
2648 public class OpenSDView extends AbstractHandler {
2650 public Object execute(ExecutionEvent event) throws ExecutionException {
2652 IWorkbenchPage persp = TmfUiPlugin.getDefault().getWorkbench().getActiveWorkbenchWindow().getActivePage();
2653 SDView view = (SDView) persp.showView("org.eclipse.linuxtools.ust.examples.ui.componentinteraction");
2654 LoadersManager.getLoadersManager().createLoader("org.eclipse.linuxtools.tmf.ui.views.uml2sd.impl.TmfUml2SDSyncLoader", view);
2655 } catch (PartInitException e) {
2656 throw new ExecutionException("PartInitException caught: ", e);
2663 === Downloading the Tutorial ===
2665 Use the following link to download the source code of the tutorial [http://wiki.eclipse.org/images/e/e6/SamplePlugin.zip Plug-in of Tutorial].
2667 == Integration of Tracing and Monitoring Framework with Sequence Diagram Framework ==
2669 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.
2671 === Reference Implementation ===
2673 A Sequence Diagram View Extension is defined in the plug-in TMF UI as well as a uml2SDLoader Extension with the reference loader.
2675 [[Image:images/ReferenceExtensions.png]]
2677 === Used Sequence Diagram Features ===
2679 Besides the default features of the Sequence Diagram Framework, the reference implementation uses the following additional features:
2685 ==== Advanced paging ====
2687 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.
2689 ==== Basic finding ====
2691 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.
2693 ==== Basic filtering ====
2695 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.
2697 ==== Selection Service ====
2699 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 .
2701 === Used TMF Features ===
2703 The reference implementation uses the following features of TMF:
2704 *TMF Experiment and Trace for accessing traces
2705 *Event Request Framework to request TMF events from the experiment and respective traces
2706 *Signal Framework for broadcasting and receiving TMF signals for synchronization purposes
2708 ==== TMF Experiment and Trace for accessing traces ====
2710 The reference loader uses TMF Experiments to access traces and to request data from the traces.
2712 ==== TMF Event Request Framework ====
2714 The reference loader use the TMF Event Request Framework to request events from the experiment and its traces.
2716 When opening a traces (which is triggered by signal ''TmfExperimentSelected'') or when opening the Sequence Diagram View after a trace had been opened previously, a TMF background request is initiated to index the trace and to fill in the first page of the sequence diagram. The purpose of the indexing is to store time ranges for pages with 10000 messages per page. This allows quickly to move to certain pages in a trace without having to re-parse from the beginning. The request is called indexing request.
2718 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.
2720 A third type of event request is issued for finding specific data across pages.
2722 ==== TMF Signal Framework ====
2724 The reference loader extends the class ''TmfComponent''. By doing that the loader is register as TMF signal handler for sending and receiving TMF signals. The loader implements signal handlers for the following TMF signals:
2725 *''TmfTraceSelectedSignal''
2726 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.
2728 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.
2729 *''TmfTimeSynchSignal''
2730 This signal indicates that a event with a certain timestamp is selected. When receiving this signal the corresponding message is selected in the Sequence Diagram View. If necessary, the page is changed.
2731 *''TmfRangeSynchSignal''
2732 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.
2734 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''.
2736 === Supported Traces ===
2738 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>
2740 Note that combined traces of multiple components, that contain the trace information about the same interactions are not supported in the reference implementation!
2742 === Trace Format ===
2744 The reference implementation in class ''TmfUml2SDSyncLoader'' in package ''org.eclipse.linuxtools.tmf.ui.views.uml2sd.impl'' analyzes events from type ''ITmfEvent'' and creates events type ''ITmfSyncSequenceDiagramEvent'' if the ''ITmfEvent'' contains all relevant information information. The parsing algorithm looks like as follows:
2748 * @param tmfEvent Event to parse for sequence diagram event details
2749 * @return sequence diagram event if details are available else null
2751 protected ITmfSyncSequenceDiagramEvent getSequenceDiagramEvent(ITmfEvent tmfEvent){
2752 //type = .*RECEIVE.* or .*SEND.*
2753 //content = sender:<sender name>:receiver:<receiver name>,signal:<signal name>
2754 String eventType = tmfEvent.getType().toString();
2755 if (eventType.contains(Messages.TmfUml2SDSyncLoader_EventTypeSend) || eventType.contains(Messages.TmfUml2SDSyncLoader_EventTypeReceive)) {
2756 Object sender = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncLoader_FieldSender);
2757 Object receiver = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncLoader_FieldReceiver);
2758 Object name = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncLoader_FieldSignal);
2759 if ((sender instanceof ITmfEventField) && (receiver instanceof ITmfEventField) && (name instanceof ITmfEventField)) {
2760 ITmfSyncSequenceDiagramEvent sdEvent = new TmfSyncSequenceDiagramEvent(tmfEvent,
2761 ((ITmfEventField) sender).getValue().toString(),
2762 ((ITmfEventField) receiver).getValue().toString(),
2763 ((ITmfEventField) name).getValue().toString());
2772 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 from can be created. Note that Sync Messages are assumed, which means start and end time are the same.
2774 === How to use the Reference Implementation ===
2776 An example trace visualizer is provided that uses a trace in binary format. It contains trace events with sequence diagram information. To parse the data using TMF a class is provided that implements ''ITmfTrace''. Additionally, a parser is provided that reads from the file and converts a trace event to ''TmfEvent''. This parser implements the interface ''ITmfEventParser''. To get the source code see [[#Downloading the Reference Plug-in | Download the Reference Plug-in]]
2778 The plug-in structure will look like this:<br>
2779 [[Image:images/ReferencePlugin.png]]<br>
2781 To open the plug-in manifest, double-click on the MANIFEST.MF file. <br>
2782 [[Image:images/SelectManifestRef.png]]<br>
2784 Run the Reference Application. To launch the Eclipse Application select the ''Overview'' tab and click on '''Launch an Eclipse Application'''<br>
2785 [[Image:images/RunApplicationRef.png]]<br>
2787 To open the Reference Sequence Diagram View, select '''Windows -> Show View -> Other... -> TMF -> Sequence Diagram''' <br>
2788 [[Image:images/ShowTmfSDView.png]]<br>
2790 An blank Sequence Diagram View will open.
2792 Select the '''Select Experiment''' button of the toolbar to load the sequence diagram from the data provided in the trace file. What this does is open the file ''tracesets/sdEvents'', parse this file through TMF and analyze all events of type ''TmfEvent'' and generates the Sequence Diagram out of it. <br>
2793 [[Image:images/ReferenceSeqDiagram.png]]<br>
2795 Now the reference application can be explored. To demonstrate the view features try the following things:
2796 *Select a message in the Sequence diagram. As result the corresponding event will be selected in the Events View.
2797 *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.
2798 *In the Events View, press key ''End''. As result, the Sequence Diagram view will jump to the last page.
2799 *In the Events View, press key ''Home''. As result, the Sequence Diagram view will jump to the first page.
2800 *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.
2801 * 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>
2803 To dispose the diagram, select the '''Dispose Experiment''' button of the toolbar. The current sequence diagram will be disposed and an empty diagram will be loaded.
2805 === Extending the Reference Loader ===
2807 In some case it might be necessary to change the implementation of the analysis of each ''TmfEvent'' for the generation of ''Sequence Diagram Events''. For that just extend the class ''TmfUml2SDSyncLoader'' and overwrite the method ''protected ITmfSyncSequenceDiagramEvent getSequnceDiagramEvent(TmfEvent tmfEvent)'' with your own implementation.
2809 === Downloading the Reference Plug-in ===
2810 To download the reference plug-in that demonstrates the reference loader, use the following link: [http://wiki.eclipse.org/images/d/d3/ReferencePlugin.zip Reference Plug-in]. Just extract the zip file and import the extracted Eclipse plug-in (plug-in name: ''org.eclipse.linuxtools.tmf.reference.ui'') to your Eclipse workspace. <br>
2815 CTF is a format used to store traces. It is self defining, binary and made to be easy to write to.
2816 Before going further, the full specification of the CTF file format can be found at http://www.efficios.com/ .
2818 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.
2820 These files can be split into two types :
2825 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.
2827 === Event Streams ===
2828 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.
2830 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"
2832 == Reading a trace ==
2833 In order to read a CTF trace, two steps must be done.
2834 * The metadata must be read to know how to read the events.
2835 * the events must be read.
2837 The metadata is a written in a subset of the C language called TSDL. To read it, first it is depacketized (if it is not in plain text) then the raw text is parsed by an antlr grammer. The parsing is done in two phases. There is a lexer (CTFLexer.g) which separated the metatdata text into tokens. The tokens are then pattern matched using the parser (CTFParser.g) to form an AST. This AST is walked through using "IOStructGen.java" to populate streams and traces in trace parent object.
2839 When the metadata is loaded and read, the trace object will be populated with 3 items:
2840 * the event definitions available per stream: a definition is a description of the datatype.
2841 * 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.
2842 * the beginning of a packet index.
2844 Now all the trace readers for the event streams have everything they need to read a trace. They will each point to one file, and read the file from packet to packet. Everytime the trace reader changes packet, the index is updated with the new packet's information. The readers are in a priority queue and sorted by timestamp. This ensures that the events are read in a sequential order. They are also sorted by file name so that in the eventuality that two events occur at the same time, they stay in the same order.
2846 == Seeking in a trace ==
2847 The reason for maintaining an index is to speed up seeks. In the case that a user wishes to seek to a certain timestamp, they just have to find the index entry that contains the timestamp, and go there to iterate in that packet until the proper event is found. this will reduce the searches time by an order of 8000 for a 256k paket size (kernel default).
2849 == Interfacing to TMF ==
2850 The trace can be read easily now but the data is still awkward to extract.
2853 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.
2856 The CtfTmfTrace is a wrapper for the standard CTF trace that allows it to perform the following actions:
2857 * '''initTrace()''' create a trace
2858 * '''validateTrace()''' is the trace a CTF trace?
2859 * '''getLocationRatio()''' how far in the trace is my location?
2860 * '''seekEvent()''' sets the cursor to a certain point in a trace.
2861 * '''readNextEvent()''' reads the next event and then advances the cursor
2862 * '''getTraceProperties()''' gets the 'env' structures of the metadata
2865 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.
2867 === CtfIteratorManager ===
2868 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.
2870 === CtfTmfContext ===
2871 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.
2873 === CtfTmfTimestamp ===
2874 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.
2877 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.
2880 There are other helper files that format given events for views, they are simpler and the architecture does not depend on them.
2883 For the moment live trace reading is not supported, there are no sources of traces to test on.