** ''org.eclipse.tracecompass.tmf.ui.views.statesystem.TmfStateSystemExplorer.java''
** ''org.eclipse.tracecompass.analysis.os.linux.ui.views.cpuusage.CpuUsageComposite.java''
+== Timing Analysis Views and Viewers ==
+
+Trace Compass provides base implementations for timing views and viewers for generating Latency Tables, Scatter Charts, Density Graphs and Statistics Tables. They are well integrated with various Trace Compass features such as reading traces and time synchronization with other views. They also handle mouse events for navigating the trace and view, zooming or presenting detailed information at mouse position. The code can be found in the Analysis Timing plug-in ''org.eclipse.tracecompass.analysis.timing.ui''. See below for a list of relevant java packages:
+
+* Latency Table
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.table'': Base classes for Latency Tables
+* Scatter Chart
+** ''org.eclipse.tracecompass.tmf.ui.views.tmfChartView.java'': Common base classes for X-Y-Chart viewers based on SWTChart
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.scatter'': Base classes for Scatter Charts
+* Density Graph
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.density'': Base classes for Density Graphs
+* Statistics Table
+** ''org.eclipse.tracecompass.analysis.timing.ui.views.segmentstore.statistics'': Base classes for Statistics Tables
+
+Several features in Trace Compass are using this framework and can be used as example for further development:
+
+* Latency Table
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternLatencyTableView.java''
+* Scatter Chart
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyScatterView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternScatterGraphView.java''
+* Density Graph
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.SystemCallLatencyDensityView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternDensityView.java''
+
+* Statistics Table
+** ''org.eclipse.tracecompass.internal.analysis.os.linux.ui.views.latency.statistics.SystemCallLatencyStatisticsView.java''
+** ''org.eclipse.tracecompass.internal.tmf.analysis.xml.ui.views.latency.PatternStatisticsView.java''
+
= Component Interaction =
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.
Received by views that analyze packet streams.
+=== TmfStartAnalysisSignal ===
+
+''Purpose''
+
+This signal is used to indicate that an analysis has started.
+
+''Senders''
+
+Sent by an analysis module when it starts to execute the analyis.
+
+''Receivers''
+
+Received by components that need to be notified of the start of an analysis
+or that need to receive the analysis module.
+
+=== TmfCpuSelectedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that the user has selected a CPU core.
+
+''Senders''
+
+Sent by any component that allows the user to select a CPU.
+
+''Receivers''
+
+Received by viewers that show information specific to a selected CPU.
+
+=== TmfThreadSelectedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that the user has selected a thread.
+
+''Senders''
+
+Sent by any component that allows the user to select a thread.
+
+''Receivers''
+
+Received by viewers that show information specific to a selected thread.
+
+=== TmfTraceSynchronizedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that trace synchronization has been completed.
+
+''Senders''
+
+Sent by the experiment after trace synchronization.
+
+''Receivers''
+
+Received by any component that needs to be notified of trace synchronization.
+
== Debugging ==
TMF has built-in Eclipse tracing support for the debugging of signal interaction between components. To enable it, open the '''Run/Debug Configuration...''' dialog, select a configuration, click the '''Tracing''' tab, select the plug-in '''org.eclipse.tracecompass.tmf.core''', and check the '''signal''' item.
the state system. The exact implementation (how the intervals are stored) is
determined by the storage backend that is used.
-Some backends will use a state history that is peristent on disk, others do not.
+Some backends will use a state history that is persistent on disk, others do not.
When loading a trace, if a history file is available and the backend supports
it, it will be loaded right away, skipping the need to go through another
construction phase.
getQuarkAbsolute() takes a variable amount of Strings in parameter, which
represent the full path to the attribute. Some of them can be constants, some
-can come programatically, often from the event's fields.
+can come programmatically, often from the event's fields.
getQuarkRelative() is to be used when you already know the quark of a certain
attribute, and want to access on of its sub-attributes. Its first parameter is
When the construction phase is done, do not forget to call closeHistory() to
tell the backend that no more intervals will be received. Depending on the
backend type, it might have to save files, close descriptors, etc. This ensures
-that a persitent file can then be re-used when the trace is opened again.
+that a persistent file can then be re-used when the trace is opened again.
If you use the AbstractTmfStateProvider, it will call closeHistory()
automatically when it reaches the end of the trace.
=== State Provider ===
<pre>
+import static org.eclipse.tracecompass.common.core.NonNullUtils.checkNotNull;
+import org.eclipse.jdt.annotation.NonNull;
import org.eclipse.tracecompass.statesystem.core.exceptions.AttributeNotFoundException;
import org.eclipse.tracecompass.statesystem.core.exceptions.StateValueTypeException;
import org.eclipse.tracecompass.statesystem.core.exceptions.TimeRangeException;
* @param trace
* The trace to which this state provider is associated
*/
- public MyStateProvider(ITmfTrace trace) {
- super(trace, CtfTmfEvent.class, "Example"); //$NON-NLS-1$
+ public MyStateProvider(@NonNull ITmfTrace trace) {
+ super(trace, "Example"); //$NON-NLS-1$
/*
- * The third parameter here is not important, it's only used to name a
+ * The second parameter here is not important, it's only used to name a
* thread internally.
*/
}
try {
if (event.getType().getName().equals("sched_switch")) {
- ITmfStateSystemBuilder ss = getStateSystemBuilder();
+ ITmfStateSystemBuilder ss = checkNotNull(getStateSystemBuilder());
int quark = ss.getQuarkAbsoluteAndAdd("CPUs", String.valueOf(event.getCPU()), "Status");
ITmfStateValue value;
if (nextTid > 0) {
<pre>
private void createFrame() {
//...
- start.setTime(new TmfTimestamp(1000, -3));
- syn1.setTime(new TmfTimestamp(1005, -3));
- synReturn1.setTime(new TmfTimestamp(1050, -3));
- asyn1.setStartTime(new TmfTimestamp(1060, -3));
- asyn1.setEndTime(new TmfTimestamp(1070, -3));
- asynReturn1.setStartTime(new TmfTimestamp(1060, -3));
- asynReturn1.setEndTime(new TmfTimestamp(1070, -3));
+ start.setTime(TmfTimestamp.create(1000, -3));
+ syn1.setTime(TmfTimestamp.create(1005, -3));
+ synReturn1.setTime(TmfTimestamp.create(1050, -3));
+ asyn1.setStartTime(TmfTimestamp.create(1060, -3));
+ asyn1.setEndTime(TmfTimestamp.create(1070, -3));
+ asynReturn1.setStartTime(TmfTimestamp.create(1060, -3));
+ asynReturn1.setEndTime(TmfTimestamp.create(1070, -3));
//...
}
</pre>
There are other helper files that format given events for views, they are simpler and the architecture does not depend on them.
=== Limitations ===
-For the moment live trace reading is not supported, there are no sources of traces to test on.
+For the moment live CTF trace reading is not supported.
= Event matching and trace synchronization =
@Override
public Iterable<TmfAnalysisRequirement> getAnalysisRequirements() {
- // initialize the requirement: domain and events
- TmfAnalysisRequirement domainReq = new TmfAnalysisRequirement(SessionConfigStrings.CONFIG_ELEMENT_DOMAIN);
- domainReq.addValue(SessionConfigStrings.CONFIG_DOMAIN_TYPE_KERNEL, ValuePriorityLevel.MANDATORY);
+ // initialize the requirement: events
+ Set<@NonNull String> requiredEvents = ImmutableSet.of("sched_switch", "sched_wakeup");
+ TmfAbstractAnalysisRequirement eventsReq = new TmfAnalysisEventRequirement(requiredEvents, PriorityLevel.MANDATORY);
- List<String> requiredEvents = ImmutableList.of("sched_switch", "sched_wakeup");
- TmfAnalysisRequirement eventReq = new TmfAnalysisRequirement(SessionConfigStrings.CONFIG_ELEMENT_EVENT,
- requiredEvents, ValuePriorityLevel.MANDATORY);
-
- return ImmutableList.of(domainReq, eventReq);
+ return ImmutableList.of(eventsReq);
}
@Override
=== Analysis requirement provider API ===
-A requirement defines the needs of an analysis. For example, an analysis could need an event named ''"sched_switch"'' in order to be properly executed. The requirements are represented by the class '''TmfAnalysisRequirement'''. Since '''IAnalysisModule''' extends the '''IAnalysisRequirementProvider''' interface, all analysis modules must provide their requirements. If the analysis module extends '''TmfAbstractAnalysisModule''', it has the choice between overriding the requirements getter ('''IAnalysisRequirementProvider#getAnalysisRequirements()''') or not, since the abstract class returns an empty collection by default (no requirements).
+A requirement defines the needs of an analysis. For example, an analysis could need an event named ''"sched_switch"'' in order to be properly executed. The requirements are represented by extending the class '''TmfAbstractAnalysisRequirement'''. Since '''IAnalysisModule''' extends the '''IAnalysisRequirementProvider''' interface, all analysis modules must provide their requirements. If the analysis module extends '''TmfAbstractAnalysisModule''', it has the choice between overriding the requirements getter ('''IAnalysisRequirementProvider#getAnalysisRequirements()''') or not, since the abstract class returns an empty collection by default (no requirements).
=== Requirement values ===
-When instantiating a requirement, the developer needs to specify a type to which all the values added to the requirement will be linked. In the earlier example, there would be an ''"event"'' or ''"eventName"'' type. The type is represented by a string, like all values added to the requirement object. With an 'event' type requirement, a trace generator like the LTTng Control could automatically enable the required events. This is possible by calling the '''TmfAnalysisRequirementHelper''' class. Another point we have to take into consideration is the priority level of each value added to the requirement object. The enum '''TmfAnalysisRequirement#ValuePriorityLevel''' gives the choice between '''ValuePriorityLevel#MANDATORY''' and '''ValuePriorityLevel#OPTIONAL'''. That way, we can tell if an analysis can run without a value or not. To add values, one must call '''TmfAnalysisRequirement#addValue()'''.
+Each concrete analysis requirement class will define how a requirement is verified on a given trace.
+When creating a requirement, the developer will specify a set of values for that class.
+With an 'event' type requirement, a trace generator like the LTTng Control could automatically
+enable the required events.
+Another point we have to take into consideration is the priority level when creating a requirement object.
+The enum '''TmfAbstractAnalysisRequirement#PriorityLevel''' gives the choice
+between '''PriorityLevel#OPTIONAL''', '''PriorityLevel#ALL_OR_NOTHING''',
+'''PriorityLevel#AT_LEAST_ONE''' or '''PriorityLevel#MANDATORY'''. That way, we
+can tell if an analysis can run without a value or not.
+
+
+To create a requirement one has the choice to extend the abstract class
+'''TmfAbstractAnalysisRequirement''' or use the existing implementations:
+'''TmfAnalysisEventRequirement''' (will verify the presence of events identified by name),
+'''TmfAnalysisEventFieldRequirement''' (will verify the presence of fields for some or all events) or
+'''TmfCompositeAnalysisRequirement''' (join requirements together with one of the priority levels).
Moreover, information can be added to requirements. That way, the developer can explicitly give help details at the requirement level instead of at the analysis level (which would just be a general help text). To add information to a requirement, the method '''TmfAnalysisRequirement#addInformation()''' must be called. Adding information is not mandatory.
=== Example of providing requirements ===
-In this example, we will implement a method that initializes a requirement object and return it in the '''IAnalysisRequirementProvider#getAnalysisRequirements()''' getter. The example method will return a set with two requirements. The first one will indicate the events needed by a specific analysis and the last one will tell on what domain type the analysis applies. In the event type requirement, we will indicate that the analysis needs a mandatory event and an optional one.
+In this example, we will implement a method that initializes a requirement object
+and return it in the '''IAnalysisRequirementProvider#getAnalysisRequirements()'''
+getter. The example method will return a set with three requirements.
+The first one will indicate a mandatory event needed by a specific analysis,
+the second one will tell an optional event name and the third will indicate
+mandatory event fields for the given event type.
+
+Note that in LTTng event contexts are considered as event fields. Using the
+'''TmfAnalysisEventFieldRequirement''' it's possible to define requirements
+on event contexts (see 3rd requirement in example below).
<pre>
-@Override
-public Iterable<TmfAnalysisRequirement> getAnalysisRequirements() {
- Set<TmfAnalysisRequirement> requirements = new HashSet<>();
+ @Override
+ public @NonNull Iterable<@NonNull TmfAbstractAnalysisRequirement> getAnalysisRequirements() {
- /* Create requirements of type 'event' and 'domain' */
- TmfAnalysisRequirement eventRequirement = new TmfAnalysisRequirement("event");
- TmfAnalysisRequirement domainRequirement = new TmfAnalysisRequirement("domain");
+ /* Requirement on event name */
+ Set<@NonNull String> requiredEvents = ImmutableSet.of("sched_wakeup");
+ TmfAbstractAnalysisRequirement eventsReq1 = new TmfAnalysisEventRequirement(requiredEvents, PriorityLevel.MANDATORY);
- /* Add the values */
- domainRequirement.addValue("kernel", TmfAnalysisRequirement.ValuePriorityLevel.MANDATORY);
- eventRequirement.addValue("sched_switch", TmfAnalysisRequirement.ValuePriorityLevel.MANDATORY);
- eventRequirement.addValue("sched_wakeup", TmfAnalysisRequirement.ValuePriorityLevel.OPTIONAL);
+ requiredEvents = ImmutableSet.of("sched_switch");
+ TmfAbstractAnalysisRequirement eventsReq2 = new TmfAnalysisEventRequirement(requiredEvents, PriorityLevel.OPTIONAL);
- /* An information about the events */
- eventRequirement.addInformation("The event sched_wakeup is optional because it's not properly handled by this analysis yet.");
+ /* An information about the events */
+ eventsReq2.addInformation("The event sched_wakeup is optional because it's not properly handled by this analysis yet.");
- /* Add them to the set */
- requirements.add(domainRequirement);
- requirements.add(eventRequirement);
+ /* Requirement on event fields */
+ Set<@NonNull String> requiredEventFields = ImmutableSet.of("context._procname", "context._ip");
+ TmfAbstractAnalysisRequirement eventFieldRequirement = new TmfAnalysisEventFieldRequirement(
+ "event name",
+ requiredEventFields,
+ PriorityLevel.MANDATORY);
- return requirements;
-}
+ Set<TmfAbstractAnalysisRequirement> requirements = ImmutableSet.of(eventsReq1, eventsReq2, eventFieldRequirement);
+ return requirements;
+ }
</pre>
* Add the possibility for an analysis requirement to be composed of another requirement.
* Generate a trace session from analysis requirements.
+= TMF Remote API =
+The TMF remote API is based on the remote services implementation of the Eclipse PTP project. It comes with a built-in SSH implementation based JSch as well as with support for a local connection. The purpose of this API is to provide a programming interface to the PTP remote services implementation for connection handling, command-line execution and file transfer handling. It provides utility functions to simplify repetitive tasks.
+
+The TMF Remote API can be used for remote trace control, fetching of traces from a remote host into the Eclipse Tracing project or uploading files to the remote host. For example, the LTTng tracer control feature uses the TMF remote API to control an LTTng host remotely and to download corresponding traces.
+
+In the following chapters the relevant classes and features of the TMF remote API is described.
+
+== Prerequisites ==
+
+To use the TMF remote API one has to add the relevant plug-in dependencies to a plug-in project. To create a plug-in project see chapter [[#Creating an Eclipse UI Plug-in]].
+
+To add plug-in dependencies double-click on the MANIFEST.MF file. Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.tracecompass.tmf.remote.core'' and press '''OK'''. Follow the same steps, add ''org.eclipse.remote.core''. If UI elements are needed in the plug-in also add ''org.eclipse.tracecompass.tmf.remote.ui'' and ''org.eclipse.remote.ui''.
+
+== TmfRemoteConnectionFactory ==
+This class is a utility class for creating ''IRemoteConnection'' instances of PTP programatically. It also provides access methods to the OSGI remote services of PTP.
+
+=== Accessing the remote services manager (OSGI service) ===
+The main entry point into the PTP remote services system is the ''IRemoteServicesManager'' OSGI service. It provides a list of connection types and the global list of all connections.
+
+To access an OSGI service, use the method '''getService()''' of the '''TmfRemoteConnectionFactory''' class:
+
+<pre>
+IRemoteServicesManager manager = TmfRemoteConnectionFactory.getService(IRemoteServicesManager.class);
+</pre>
+
+=== Obtaining a IRemoteConnection ===
+To obtain an '''IRemoteConnection''' instance use the method '''TmfRemoteConnectionFactory.getRemoteConnection(String remoteServicesId, String name)''', where ''remoteServicesId'' is the ID of service ID for the connection, and ''name'' the name of the connection. For built-in SSH the ''remoteServicesId'' is "org.eclipse.remote.JSch".
+
+<pre>
+IRemoteConnection connection = TmfRemoteConnectionFactory.getRemoteConnection("org.eclipse.remote.JSch", "My Connection");
+</pre>
+
+Note that the connection needs to be created beforehand using the Remote Connection wizard implementation ('''Window -> Preferences -> Remote Development -> Remote Connection''') in the Eclipse application that executes this plug-in. For more information about creating connections using the Remote Connections feature of PTP refer to [http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.ptp.doc.user%2Fhtml%2FremoteTools.html&anchor=remote link]. Alternatively it can be created programmatically using the corresponding API of TMF ([[#Creating an IRemoteConnection instance]]).
+
+To obtain an '''IRemoteConnection''' instance use method '''TmfRemoteConnectionFactory.getLocalConnection()'''.
+<pre>
+IRemoteConnection connection = TmfRemoteConnectionFactory.getLocalConnection();
+</pre>
+
+=== Creating an IRemoteConnection instance ===
+It is possible to create an '''IRemoteConnection''' instance programmatically using the '''TmfRemoteConnectionFactory'''. Right now only build-in SSH or Local connection is supported.
+
+To create an '''IRemoteConnection''' instance use the method '''createConnection(URI hostURI, String name)''' of class '''TmfRemoteConnectionFactory''', where ''hostURI'' is the URI of the remote connection, and ''name'' the name of the connection. For a built-in SSH use:
+<pre>
+import org.eclipse.remote.core.IRemoteConnection;
+...
+ try {
+ URI hostUri = URIUtil.fromString("ssh://userID@127.0.0.1:22");
+ IRemoteConnection connection = TmfRemoteConnectionFactory.createConnection(hostUri, "MyHost");
+ } catch (URISyntaxException e) {
+ return new Status(IStatus.ERROR, "my.plugin.id", "URI syntax error", e);
+ } catch (RemoteConnectionException e) {
+ return new Status(IStatus.ERROR, "my.plugin.id", "Connection cannot be created", e);
+ }
+...
+</pre>
+
+Note that if a connection already exists with the given name then this connection will be returned.
+
+=== Providing a connection factory ===
+Right now only build-in SSH or Local connection of PTP is supported. If one wants to provide another connection factory with a different remote service implementation use the interface '''IConnectionFactory''' to implement a new connection factory class. Then, register the new factory to '''TmfRemoteConnectionFactory''' using method '''registerConnectionFactory(String connectionTypeId, IConnectionFactory factory)''', where ''connectionTypeId'' is a unique ID and ''factory'' is the corresponding connection factory implementation.
+
+== RemoteSystemProxy ==
+The purpose of the RemoteSystemProxy is to handle the connection state of '''IRemoteConnection''' (connect/disconnect). Before opening a connection it checks if the connection had been open previously. If it was open, disconnecting the proxy will not close the connection. This is useful if multiple components using the same connection at the same time for different features (e.g. Tracer Control and remote fetching of traces) without impacting each other.
+
+=== Creating a RemoteSystemProxy ===
+Once one has an '''IRemoteConnection''' instance a '''RemoteSystemProxy''' can be constructed by:
+<pre>
+// Get local connection (for example)
+IRemoteConnection connection = TmfRemoteConnectionFactory.getLocalConnection();
+RemoteSystemProxy proxy = new RemoteSystemProxy(connection);
+</pre>
+
+=== Opening the remote connection ===
+To open the connection call method '''connect()''':
+<pre>
+ proxy.connect();
+</pre>
+
+This will open the connection. If the connection has been previously opened then it will immediately return.
+
+=== Closing the remote connection ===
+To close the connection call method '''disconnect()''':
+<pre>
+ proxy.disconnect();
+</pre>
+
+Note: This will close the connection if the connection was opened by this proxy. Otherwise it will stay open.
+
+=== Disposing the remote connection ===
+If a remote system proxy is not needed anymore the proxy instance needs to be disposed by calling method '''dispose()'''. This may close the connection if the connection was opened by this proxy. Otherwise it will stay open.
+
+<pre>
+ proxy.dispose();
+</pre>
+
+=== Checking the connection state ===
+
+To check the connection state use method '''isConnected()''' of the '''RemoteSystemProxy''' class.
+
+<pre>
+ if (proxy.isConnected()) {
+ // do something
+ }
+</pre>
+
+
+=== Retrieving the IRemoteConnection instance ===
+To retrieve the '''IRemoteConnection''' instance use the '''getRemoteConnection()''' method of the '''RemoteSystemProxy''' class. Using this instance relevant features of the remote connection implementation can be accessed, for example remote file service ('''IRemoteFileService''') or remote process service ('''IRemoteProcessService''').
+
+<pre>
+import org.eclipse.remote.core.IRemoteConnection;
+import org.eclipse.remote.core.IRemoteFileService;
+...
+ IRemoteRemoteConnection connection = proxy.getRemoteConnection();
+ IRemoteFileService fileService = connection.getService(IRemoteFileService.class);
+ if (fileService != null) {
+ // do something (e.g. download or upload a file)
+ }
+</pre>
+
+<pre>
+import org.eclipse.remote.core.IRemoteConnection;
+import org.eclipse.remote.core.IRemoteFileService;
+...
+ IRemoteRemoteConnection connection = proxy.getRemoteConnection();
+ IRemoteFileService processService = connection.getService(IRemoteProcessService.class);
+ if (processService != null) {
+ // do something (e.g. execute command)
+ }
+</pre>
+
+=== Obtaining a command shell ===
+The TMF remote API provides a Command shell implementation to execute remote command-line commands. To obtain a command-line shell use the RemoteSystemProxy.
+
+<pre>
+import org.eclipse.remote.core.IRemoteConnection;
+import org.eclipse.remote.core.IRemoteFileService;
+import org.eclipse.tracecompass.tmf.remote.core.shell.ICommandShell
+...
+ ICommandShell shell = proxy.createCommandShell();
+ ICommandInput command = fCommandShell.createCommand();
+ command.add("ls");
+ command.add("-l");
+ ICommandResult result = shell.executeCommand(command, new NullProgressMonitor);
+ System.out.println("Return value: " result.getResult());
+ for (String line : result.getOutput()) {
+ System.out.println(line);
+ }
+ for (String line : result.getErrorOutput()) {
+ System.err.println(line);
+ }
+ shell.dispose();
+</pre>
+
+Note that the shell needs to be disposed if not needed anymore.
+
+Note for creating a command with parameters using the '''CommandInput''' class, add the command and each parameter separately instead of using one single String.
= Performance Tests =
* Add SWTBOT tests to org.eclipse.tracecompass.tmf.pcap.ui
* Add a Raw Viewer, similar to Wireshark. We could use the “Show Raw” in the event editor to do that.
* Externalize strings in org.eclipse.tracecompass.pcap.core. At the moment, all the strings are hardcoded. It would be good to externalize them all.
+
+= Markers =
+
+Markers are annotations that are defined with a time range, a color, a category and an optional label. The markers are displayed in the time graph of any view that extends ''AbstractTimeGraphView''. The markers are drawn as a line or a region (in case the time range duration is not zero) of the given color, which can have an alpha value to use transparency. The markers can be drawn in the foreground (above time graph states) or in the background (below time graph states). An optional label can be drawn in the the time scale area.
+
+The developer can add trace-specific markers and/or view-specific markers.
+
+== Trace-specific markers ==
+
+Trace-specific markers can be added by registering an ''IAdapterFactory'' with the TmfTraceAdapterManager. The adapter factory must provide adapters of the ''IMarkerEventSource'' class for a given ''ITmfTrace'' object. The adapter factory can be registered for traces of a certain class (which will include sub-classes of the given class) or it can be registered for traces of a certain trace type id (as defined in the ''org.eclipse.linuxtools.tmf.core.tracetype'' extension point).
+
+The adapter factory can be registered in the ''Activator'' of the plug-in that introduces it, in the ''start()'' method, and unregistered in the ''stop()'' method.
+
+It is recommended to extend the ''AbstractTmfTraceAdapterFactory'' class when creating the adapter factory. This will ensure that a single instance of the adapter is created for a specific trace and reused by all components that need the adapter, and that the adapter is disposed when the trace is closed.
+
+The adapter implementing the ''IMarkerEventSource'' interface must provide two methods:
+
+* ''getMarkerCategories()'' returns a list of category names which will be displayed to the user, who can then enable or disable markers on a per-category basis.
+
+* ''getMarkerList()'' returns a list of markers instances of class ''IMarkerEvent'' for the given category and time range. The resolution can be used to limit the number of markers returned for the current zoom level, and the progress monitor can be checked for early cancellation of the marker computation.
+
+The trace-specific markers for a particular trace will appear in all views extending ''AbstractTimeGraphView'' when that trace (or an experiment containing that trace) is selected.
+
+An example of a trace-specific markers implementation can be seen by examining classes ''LostEventsMarkerEventSourceFactory'', ''LostEventsMarkerEventSource'' and ''Activator'' in the ''org.eclipse.tracecompass.tmf.ui'' plug-in.
+
+== View-specific markers ==
+
+View-specific markers can by added in sub-classes of ''AbstractTimeGraphView'' by implementing the following two methods:
+
+* ''getViewMarkerCategories()'' returns a list of category names which will be displayed to the user, who can then enable or disable markers on a per-category basis.
+
+* ''getViewMarkerList()'' returns a list of markers instances of class ''IMarkerEvent'' for the given time range. The resolution can be used to limit the number of markers returned for the current zoom level, and the progress monitor can be checked for early cancellation of the marker computation.
+
+= Virtual Machine Analysis =
+
+Virtualized environment are becoming more popular and understanding them can be challenging as machines share resources (CPU, disks, memory, etc), but from their point of view, they are running on bare metal. Tracing all the machines (guests and hosts) in a virtualized environment allows information to be correlated between all the nodes to better understand the system. See the User documentation for more info on this analysis.
+
+The virtual machine analysis has been implemented in the following plugins:
+
+* '''org.eclipse.tracecompass.lttng2.kernel.core''' contains the virtual machine analysis itself, the model of the virtualized environment, as well as its implementation for different hypervisors.
+* '''org.eclipse.tracecompass.lttng2.kernel.ui''' contains the views for the analysis.
+
+== Adding support for an hypervisor ==
+
+Supporting a new hypervisor in Trace Compass requires implementing the model for this new hypervisor. The following sections will describe for each part of the model what has to be considered, what information we need to have, etc. Note that each hypervisor will require some work and investigation. The information might already be available as a single tracepoint for some, while other may require many tracepoints. It is also possible that some will require to add tracepoints, either to the kernel, or the hypervisor code itself, in which case a userspace trace (LTTng UST) might be necessary to get all the information.
+
+=== Virtual CPU analysis ===
+
+This analysis tracks the state of the virtual CPUs in conjunction with the physical CPU it is running on. For this, we need the following information:
+
+* A way to link a virtual CPU on a guest with a process on the host, such that it is possible to determine when the virtual CPU is preempted on the host. If trace data does not provide this information, some hypervisors have a command line option to dump that information. Manually feeding that information to the analysis is not supported now though.
+* A way to differentiate between hypervisor mode and normal mode for the virtual CPU. A virtual CPU usually runs within a process on the host, but sometimes that process may need to run hypervisor-specific code. That is called '''hypervisor mode'''. During that time, no code from the guest itself is run. Typically, the process is running on the host (not preempted), but from the guest's point of view, the virtual CPU should be preempted.
+
+A model implementation for a new hypervisor will need to implement class '''IVirtualMachineModel''', that can be found in package '''org.eclipse.tracecompass.internal.lttng2.kernel.core.analysis.vm.model'''. See the javadoc in the class itself for more information on what each method does.
projects / deliverable / tracecompass.git / blobdiff